SDK Overview

Two ways to embed a deployed Amodal agent in your product:

• @amodalai/react — Drop-in React components: AmodalProvider, AmodalChat, AmodalAction, and hooks. Talks to a running runtime server over HTTP/SSE.
• @amodalai/react/widget — Standalone chat widget with SSE streaming, theming, and callbacks. No React required on the host page.

React (client-side)

npm install @amodalai/react

import { AmodalProvider, AmodalChat } from "@amodalai/react";
 
function App() {
  return (
    <AmodalProvider runtimeUrl="https://your-agent.example.com" appId="my-app">
      <AmodalChat />
    </AmodalProvider>
  );
}

Your React app calls a deployed runtime over HTTP/SSE. In production, route these calls through your app backend when you need to mint user identity, scope IDs, or session tokens.

What you get

• State-machine agent loop — see State Machine for the full architecture.
• Multi-provider support — Anthropic, OpenAI, Google, DeepSeek, Groq, Mistral, xAI via the Vercel AI SDK. Provider failover chains built in.
• Tool system — store tools, connection tools with ACL enforcement, custom tools (handler.ts files), MCP tools, and admin file tools.
• Sub-agent dispatch — dispatch_task spawns a write-enabled sub-agent with its own context.
• Context compaction + loop detection — long agent runs stay coherent without blowing the budget.
• Store backends — Postgres via Drizzle ORM. Bring your own via the storeBackend injection.
• SSE streaming — every session.stream() call yields typed SSE events (init, text_delta, tool_call_start, tool_call_result, done).
• MCP support — discover tools from connected MCP servers.

When to use which