bindAgent
Connect an AG-UI agent to your application runtime.
Signature and import
Create the binding after the agent is ready, then dispose it when the owning application scope ends.
import { bindAgent } from "@generative-a11y/ag-ui";
const binding = bindAgent({
runtime,
scopeId: "research-agent",
agent,
});
// Call when the owning scope ends; the agent and runtime remain yours.
function disposeAgentBinding() {
binding.dispose();
}The binding subscribes without running the agent. Keep scopeId stable and
unique across mounted agents; disposing the binding leaves both the agent and
runtime under your app’s control.
Options
Prop
Type
After the tracking limit is exhausted, the binding suppresses subsequent lifecycle events, including events for known identities. Create a fresh binding at an intentional session boundary to resume observation.
How AgentSubscriber callbacks map to events
AG-UI integration reads public callbacks instead of rendered UI.
| AG-UI callback family | generative-a11y event | Notes |
|---|---|---|
| Run start and finish | run lifecycle | Uses protocol run identity and preserves documented lineage |
| Subagent start and finish | delegated child run lifecycle | Preserves explicit parent run, tool, and message ownership |
| Step start and finish | partial step lifecycle | Keeps stepName as a label and omits stepId |
| 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 | run and active descendant terminal events | Ends active response, tool, child run, and root run state |
| Interrupt and resume | interaction requested or resolved | Reports when the app needs user input |
| Run initialized | interaction resolution | Matches known active interrupt IDs |
Declared fidelity
AG-UI 0.0.59 provides stable run and subagent IDs. Step callbacks provide
stepName but no stable step ID, so step and hierarchy fidelity are partial.
Replay and reconnection are partial, retry support is unavailable, and custom
events require an explicit host mapping.