@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/clientand@ag-ui/core1.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: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:
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_ERRORcodes; upstream error text goes toonError, not the client
@ag-ui/omnara from a browser
component. See the
live Dojo examples and the
package README
for options, resume payloads, and limits.