Docs

Sdk

The Canvas App SDK enables you to build interactive applications that run inside the Agentastic launcher. Canvas apps have access to AI capabilities, the file system, network, and more through a secure bridge API.

What are Canvas Apps?

Canvas Apps are lightweight, sandboxed applications that render in the Agentastic launcher. They can:

  • Make LLM calls - Request AI completions with custom prompts
  • Display rich UI - Use native SwiftUI (A2UI) or HTML/JavaScript for interactive interfaces
  • Access tools - Leverage Agentastic's built-in tools like file operations, calendar, etc.
  • Communicate - Send and receive messages via the bridge API

App Types

A2UI Apps (Recommended)

Define your UI using Google's A2UI protocol. Renders as native SwiftUI for best performance.

{
  "manifest_version": 1,
  "id": "dev.example.hello",
  "name": "Hello World",
  "version": "1.0.0",
  "a2ui": {
    "surface": { "id": "main", "title": "Hello World" },
    "components": [
      { "id": "root", "component": "Column", "children": ["header", "input", "button"] },
      { "id": "header", "component": "Text", "text": "Hello, Canvas!", "usageHint": "h1" },
      { "id": "input", "component": "TextField", "label": "Your Name", "path": "/form/name" },
      { "id": "button", "component": "Button", "text": "Greet Me", "action": { "name": "greet", "context": { "name": "/form/name" } } }
    ],
    "data": { "form": { "name": "" } }
  },
  "actions": [{
    "name": "greet",
    "handler": "llm:complete",
    "llm": {
      "system": "You are a friendly greeter.",
      "user": "Greet {{name}} in a fun and creative way.",
      "model": "gpt-4.1-mini"
    }
  }]
}

Packaged Apps (HTML)

Build with full HTML, CSS, and JavaScript for complex applications.

my-app/
├── manifest.json
├── index.html
├── styles.css
└── app.js

Quick Example

Here's a minimal Canvas app that greets the user with an AI-generated message:

manifest.json:

{
  "manifest_version": 1,
  "id": "dev.example.greeter",
  "name": "AI Greeter",
  "version": "1.0.0",
  "entrypoint": "index.html",
  "capabilities": ["llm.complete"]
}

index.html:

<!DOCTYPE html>
<html>
<head>
  <title>AI Greeter</title>
  <script src="agentastic://sdk/bridge.js"></script>
</head>
<body>
  <input type="text" id="name" placeholder="Enter your name">
  <button onclick="greet()">Greet Me</button>
  <div id="response"></div>

  <script>
    async function greet() {
      const name = document.getElementById('name').value;
      const result = await Agentastic.llm.ask({
        user: `Generate a friendly, creative greeting for ${name}`,
        model: 'gpt-4.1-mini'
      });
      document.getElementById('response').textContent = result;
    }
  </script>
</body>
</html>

SDK Namespaces

The Canvas App SDK provides several namespaces:

NamespacePurpose
Agentastic.llmAI completions and streaming
Agentastic.uiToasts, modals, theme, and window control
Agentastic.agentContext, tool registration, and conversation injection
Agentastic.ipcInter-app communication
Agentastic.fsSandboxed file system operations
Agentastic.netNetwork requests
Agentastic.contextRuntime environment information

New in v0.2.0

Agent Namespace Enhancements:

  • agent.sendMessage() - Inject messages into the conversation as user or assistant
  • agent.setInput() - Populate the input field without sending
  • agent.unregisterTool() - Remove previously registered tools
  • agent.onThinking() - Subscribe to thinking state changes

UI Namespace Enhancements:

  • ui.openExternal() - Open URLs in the default browser
  • ui.setHeight() / ui.setSize() - Control app dimensions
  • ui.requestExpand() / ui.requestCollapse() - Toggle fullscreen mode
  • ui.onDisplayModeChange() - React to display mode changes

Context API:

  • Access runtime environment via Agentastic.context - locale, platform, color scheme, display mode, and more

Response Visibility Scoping:

  • Control what data is visible to AI models vs. your app only
  • Configure via responseScoping in manifest actions

Filesystem Security

Canvas apps have sandboxed filesystem access:

  • App directory - Always accessible at ~/Library/Application Support/agentastic/apps/<app-slug>/
  • External paths - Require explicit permissions in manifest.json
  • System paths - Always blocked (/System, /private, etc.)
{
  "permissions": {
    "filesystem": {
      "read": ["~/Documents/MyApp"],
      "write": ["~/Documents/MyApp"]
    }
  }
}

See the Filesystem API documentation for details.

Getting Started

  1. Create a manifest - Define your app's metadata and permissions
  2. Build your UI - Use A2UI JSON or custom HTML/JS
  3. Connect the bridge - Import the SDK to access Agentastic features
  4. Test locally - Use the developer tools to debug
  5. Package and deploy - Distribute your app

Next Steps