@aglit-ai/sdk

MIT-licensed SDK for building against the Aglit AI desktop API and tool runtime.

• Requires the Aglit AI desktop app/API running locally
• Type-safe fetch wrapper for the desktop API
• JSON-RPC tool executor with a required x_aglit_ai_tool_reason
• OpenAPI specs for Desktop + Tool Builder + Provider SPI APIs

You must have the Aglit AI desktop app/API running locally (localhost). Set SERVER_PORT/PORT/AGLIT_DESKTOP_BASE_URL as needed.

Install

pnpm add @aglit-ai/sdk
# or: npm install @aglit-ai/sdk

Quick Start (TypeScript)

import { createDesktopClient, executeTool } from '@aglit-ai/sdk';

const SERVER_PORT = process.env.SERVER_PORT ?? '49117';
const baseUrl = `http://127.0.0.1:${SERVER_PORT}`;
const agentId = 'root-agent';

const desktop = createDesktopClient({ baseUrl });

// Call REST endpoints (typed from OpenAPI)
const tasks = await desktop.GET('/tasks');
console.log(tasks.data?.tasks?.length);

// Execute tools via IPC (requires x_aglit_ai_tool_reason)
const response = await executeTool({
  agentId,
  request: {
    jsonrpc: '2.0',
    id: 'sdk-run-terminal',
    params: {
      name: 'p1_terminal',
      arguments: {
        action: 'open',
        x_aglit_ai_tool_reason: 'SDK example: open terminal via IPC',
      },
    },
    context: {
      sessionId: `sdk-terminal-${Date.now()}`,
      agentId,
    },
  },
});
console.log('tool response', response.data?.result);

Quick Start (JavaScript)

const { executeTool } = require('@aglit-ai/sdk');

(async () => {
  const response = await executeTool({
    agentId: 'root-agent',
    request: {
      jsonrpc: '2.0',
      id: 'sdk-ipc-example',
      params: {
        name: 'p1_todo',
        arguments: {
          action: 'list',
          x_aglit_ai_tool_reason: 'SDK IPC example: list todos',
        },
      },
      context: {
        agentId: 'root-agent',
        sessionId: 'sdk-ipc-session',
      },
    },
  });
  console.log(JSON.stringify(response, null, 2));
})();

IPC Tool Execution

Local tool execution runs over the IPC broker so there is no unauthenticated HTTP surface on loopback. If you store the IPC configuration somewhere custom, set AGLIT_SDK_IPC_CONFIG_PATH accordingly (default: <user-data>/ipc/sdk-ipc.json, where <user-data> is ~/Library/Application Support/Aglit AI/ on macOS).

On macOS, the SDK routes requests through a signed helper into an XPC broker. The broker only accepts requests from trusted apps and will prompt in the desktop app if a new app requests access. The socket endpoint is never written to disk. For local development, set AGLIT_SDK_XPC_ONLY=0 to keep the legacy socket config.

Always include x_aglit_ai_tool_reason and pass structured arguments rather than raw shell strings. The IPC broker also enforces the same tool policies you see in the UI, including approval flows and logging.

Examples

The SDK ships ready-to-run examples for common automation surfaces. Always include x_aglit_ai_tool_reason to explain why the tool is being called.

Terminal Commands

await executeTool({
  agentId: 'root-agent',
  request: {
    jsonrpc: '2.0',
    id: 'open-terminal',
    params: {
      name: 'p1_terminal',
      arguments: {
        action: 'open',
        x_aglit_ai_tool_reason: 'SDK example: open terminal',
      },
    },
    context: { sessionId: 'sdk-shell', agentId: 'root-agent' },
  },
});

await executeTool({
  agentId: 'root-agent',
  request: {
    jsonrpc: '2.0',
    id: 'type-ls',
    params: {
      name: 'p1_terminal',
      arguments: {
        action: 'type',
        windowId: '<window-id-from-open>',
        text: 'ls -la /tmp',
        submit_command: true,
        x_aglit_ai_tool_reason: 'SDK example: list temp files',
      },
    },
    context: { sessionId: 'sdk-shell', agentId: 'root-agent' },
  },
});

Browser Automation

// Navigate first
const nav = await executeTool({
  agentId: 'root-agent',
  request: {
    jsonrpc: '2.0',
    id: 'browser-nav',
    params: {
      name: 'p1_browser',
      arguments: {
        action: 'navigate',
        url: 'https://example.com',
        x_aglit_ai_tool_reason: 'SDK example: warm up page',
      },
    },
    context: { sessionId: 'sdk-browser', agentId: 'root-agent' },
  },
});

const windowId = (nav.data?.result as any)?.windowId as string;

// Inject JavaScript in that session
await executeTool({
  agentId: 'root-agent',
  request: {
    jsonrpc: '2.0',
    id: 'browser-js',
    params: {
      name: 'p1_browser',
      arguments: {
        action: 'execute_javascript',
        windowId,
        code: 'document.title',
        x_aglit_ai_tool_reason: 'SDK example: read page title',
      },
    },
    context: { sessionId: 'sdk-browser', agentId: 'root-agent' },
  },
});

Office App Automations (macOS)

await executeTool({
  agentId: 'root-agent',
  request: {
    jsonrpc: '2.0',
    id: 'app-01',
    params: {
      name: 'p1_office',
      arguments: {
        tool: 'app',
        app: 'calendar',
        action: 'list',
        x_aglit_ai_tool_reason: 'SDK example: list calendar events',
      },
    },
    context: { sessionId: 'sdk-app', agentId: 'root-agent' },
  },
});

Create Chat Sessions

import { createDesktopClient } from '@aglit-ai/sdk';

const desktop = createDesktopClient({ baseUrl });

const chat = await desktop.POST('/chats', {
  body: {
    agentId: 'root-agent',
    initialText: 'Say hello from the SDK',
  },
});
console.log('chat id', chat.data?.chat?.id);

Run the Bundled Examples

Make sure the desktop app/API is running locally, then:

pnpm --filter @aglit-ai/sdk run build        # if you haven't built yet
pnpm --filter @aglit-ai/sdk run test:examples

Configure via environment:

• AGLIT_DESKTOP_BASE_URL (overrides host/port)
• SERVER_PORT or PORT (default 49117 prod; 49217 for local dev)
• AGLIT_AGENT_ID (default root-agent)

OpenAPI Specs

The SDK resolves the current OpenAPI source files from @aglit-ai/types:

• Desktop API: @aglit-ai/types/schema/api.openapi.yaml
• Tool Builder API: @aglit-ai/types/schema/tools-api.openapi.yaml
• Provider SPI API: @aglit-ai/types/schema/provider-spi.openapi.yaml