A custom agent can gain AG-UI through a gateway that translates native events and maps threads to saved sessions. The app needs an AG-UI client and event renderers. Shared state and approvals require explicit agent hooks; existing MCP servers can remain unchanged.
Adapting a custom agent and application to AG-UI
The following is an implementation proposal, not a tested integration with the Operator's agents.
Agent boundary
Expose an endpoint that accepts RunAgentInput and returns protocol events. The default transport is an HTTP POST followed by an SSE response. The request identifies a conversation with threadId, a turn with runId, and carries the visible message history; application state, context, frontend tools and interrupt responses are additional inputs. A 1.0 implementation also declares its protocol version. Run input, HTTP + SSE
A gateway translates the input into the existing harness's invocation and translates its structured output back:
| Native information | AG-UI representation |
|---|---|
| Turn starts | RUN_STARTED |
| Assistant response | Text-message start, content and end events |
| Tool activity and result | Tool-call events and result |
| Shared application data | State snapshot or delta |
| Successful completion | RUN_FINISHED |
| Failure after the stream opens | RUN_ERROR |
Use the existing framework integration where one fits, or implement this bridge around the harness's native API, ACP connection or structured CLI output. A protocol proxy can be the producer; AG-UI does not require every underlying agent process to implement HTTP. Specification roles, server example
If only final text is available, the gateway can emit that as a text message when it arrives. Rich progress, tool attribution and shared-state updates require corresponding information from the harness.
Interaction hooks
Define the application's shared-state structure and decide how it enters agent context. Emit snapshots or patches when the agent changes that state. A generic adapter cannot infer domain data reliably from arbitrary prose. Shared state
For approvals, the runtime needs a pause point before the relevant action. The bridge exposes the interrupt; the next request carries the user's response, which the runtime handles before continuing. Emitting an approval prompt after an action has already executed would not implement this workflow. Interrupt lifecycle
Application boundary
Use an AG-UI client such as HttpAgent from @ag-ui/client, subscribing to events and connecting them to the application's displays. CopilotKit is an optional framework providing frontend primitives and a runtime around this interaction. HttpAgent, CopilotKit introduction
Start with conversational text and completion, then add the state and approval flows the application actually needs. The agent's existing MCP tool connections can continue operating behind the bridge.