Skip to main content
@ag-ui/omnara connects an AG-UI frontend to Omnara agents. Each chat thread gets its own Omnara agent per user, launched from an Omnara profile or an inline definition, and that agent keeps running in Omnara between requests.

Prerequisites

  • Node.js 22.12 or newer
  • @ag-ui/client and @ag-ui/core 1.x (use a CopilotKit release that resolves the 1.x line)
  • An Omnara project, an org API key with the developer role on it, and a profile to launch (or an inline definition, below)

Add Omnara to an application

Install the server dependencies:
Set your key and project in the environment the server reads:
Create app/api/copilotkit/route.ts. The agent is built per request, so its user comes from your own auth:
apiKey defaults to OMNARA_API_KEY. To launch from an inline agent config instead of a profile, replace profile with a definition. omnara-openrouter is the model provider every organization starts with:
The frontend can now select the assistant agent through any AG-UI client. A CopilotKit React application uses runtimeUrl="/api/copilotkit" and agent="assistant" on its CopilotKit provider.

Threads, runs, and Stop

A thread’s agent is keyed by agent, user and thread id and is reused across runs, so changing the profile or definition applies to new threads. A closed tab or dropped connection cancels nothing: the next run catches the chat up from Omnara’s log. abortRun() (CopilotKit’s Stop button) cancels the agent and its running subagents. Thread ids come from the client, so check that the caller owns the thread in beforeRequestMiddleware. A thread belongs to one user: to continue a chat as someone else, start a new thread.

Supported integration behavior

  • Streaming text and reasoning, ending each run with a snapshot of Omnara’s log
  • Omnara’s built-in and MCP tool calls with their results
  • Frontend tools, added to the thread’s agent as custom tools (the run ends with pendingToolCallIds), and backend tools your server runs (backendTools)
  • Omnara approvals and questions as resumable interrupts, subagents’ included
  • Subagent reports, and messages sent from elsewhere (Omnara’s dashboard, the API) with the sender’s name
  • App context, and image and document attachments
  • Stable RUN_ERROR codes; upstream error text goes to onError, not the client
The integration is server-only: never import @ag-ui/omnara from a browser component. See the live Dojo examples and the package README for options, resume payloads, and limits.