AG-UI

bindAgent

Connect one AG-UI agent through its public callbacks and send those events to a core runtime supplied by your app.

Signature and import

Create the binding after the agent is ready, then dispose it when the owning application scope ends.

typescript

import { bindAgent } from "@generative-a11y/ag-ui";

const binding = bindAgent({
  runtime,
  scopeId: "research-agent",
  agent,
  maxTrackedEntities: 1_000,
});

// Unsubscribes without disposing agent or runtime.
binding.dispose();

How this code works

01
Connect the agent
AgentBinding subscribes to documented callbacks without running your agent.
02
Separate agent IDs
scopeId prevents message, tool, and interrupt IDs from colliding across agents.
03
Limit stored IDs
After reaching its limit, the adapter ignores new IDs instead of removing active records.
04
Dispose the subscription
Your app still owns the runtime and agent after the binding is disposed.

Options and return values

runtimePick<GenerativeA11yRuntime, 'dispatch'>Required

Receives adapter events while remaining under your app's control.

Default: n/a

scopeIdstringRequired

Stable non-empty namespace for AG-UI message, tool, and interrupt IDs.

Default: n/a

agentAgentSourceRequired

Borrowed object exposing documented subscribe behavior.

Default: n/a

maxTrackedEntitiesnumberOptional

Positive safe integer bounding tracked responses, tools, and interactions.

Default: 1000

returnAgentBindingReturn

An idempotent dispose method for the protocol subscription.

Default: n/a

How AgentSubscriber callbacks map to events

AG-UI integration reads public callbacks instead of rendered UI.

AG-UI callback family	generative-a11y event	Notes
Text message start, content, end	response lifecycle	Each update contains only new text
Tool call start, args, result, end	tool lifecycle	Arguments alone do not mean execution started
Run error or interruption	`response.failed` or interrupted	Uses short, translated text that is safe to share
Interrupt and resume	interaction requested or resolved	Reports when the app needs user input
Run initialized	interaction resolution	Matches known active interrupt IDs