AG-UI 1.0 gives agent apps a stable contract for streams and approvals

CopilotKit announced AG-UI 1.0 on September 30, formalizing how an agent tells an application what it is doing. The release gives developers a frozen JSON Schema and written behavioral rules for streamed messages, tool calls, shared state and run outcomes. That matters when the frontend needs to show two agents working at once, display a document returned by a tool, or ask permission before an email goes out.

The announcement follows the software release: the project’s September 17 package notes list the first 1.0 TypeScript, Python and .NET packages. A September 29 TypeScript client update has already fixed reconnecting to a thread with pending interrupts. This is a published protocol and SDK release, not merely a proposed standard.

AG-UI, short for Agent-User Interaction Protocol, sits between an agent backend and a user-facing application. It describes the request the application sends and the ordered event stream that comes back. In CopilotKit’s framing, MCP connects agents to tools, A2A connects agents to other agents, and AG-UI handles the application-facing conversation. It does not choose the model, run the agent’s workflow or decide which actions a user may authorize.

A specification beyond event shapes

Before 1.0, AG-UI defined data shapes while much of its behavior lived in the TypeScript client. The new specification separates those responsibilities: the JSON Schema governs structure, while the prose rules govern event ordering, lifecycle, attribution, error handling and compatibility.

That gives implementers more than a list of message types. It establishes what counts as a valid exchange and which side is responsible when one goes wrong. The first-party TypeScript, Python and .NET protocol types are generated from the same schema, reducing the need to maintain separate handwritten definitions.

The contract also distinguishes something unfamiliar from something broken. An unknown event or property is handled through the compatibility and enforcement pipeline, with warnings when it is dropped or stripped. A malformed value in a known field is a fatal error. Applications cannot rely on arbitrary extra event fields reaching their subscribers; metadata is the supported extension channel.

Subagents and tool results become visible

The subagent rules let delegated work carry a subagentRunId, with lifecycle events including SUBAGENT_STARTED, SUBAGENT_FINISHED and SUBAGENT_ERROR.

Consider the travel-planning example in the announcement: one subagent searches flights while another searches hotels. Attribution lets the application separate their output instead of presenting an undifferentiated stream. Developers can build independent progress views without guessing which worker produced each message. They still have to implement those views; the protocol does not supply a finished interface or an orchestration engine.

Tool results can also carry an ordered list of content parts, rather than only a string. A tool can return text alongside an image, audio, video or a document. An invoice-producing tool, for example, can identify the PDF as a document instead of burying its representation in a text response.

Whether a particular frontend displays that PDF, or a particular model accepts a media part, remains an integration question. The new contract makes the content representable; it does not make every consumer capable of rendering it.

An approval request ends the current run

The most consequential user-facing change is the interrupt-and-resume pattern. When an agent needs outside input, it closes the current run with RUN_FINISHED carrying an interrupt outcome. The next run submits the answers through its resume list.

For an email approval, the application can display the request, collect the decision and continue the thread. It is not a connection held open indefinitely waiting for a click. The consumer must cover every interrupt with an answer or an explicit abandonment; an omitted answer is not permission to continue past it.

A cancelled run is distinct, too. The protocol can report that work was stopped deliberately, rather than mislabeling partial work as success or treating the user’s stop button as an error.

Those distinctions improve what the interface can tell the user, but they are not an authorization system. The specification’s security section leaves consent flows, semantic validation and safe rendering to the application. A conforming event stream is not proof that its tool arguments are safe or its action was approved.

Token reporting without double-counting

AG-UI 1.0 defines optional token usage reporting by provider and model on terminal run events. Input and output counts are totals; cache reads, cache writes and reasoning tokens are portions of those totals, not extra buckets to add again.

The run boundary matters. Calls made by subagents count toward their enclosing run. A separately invoked child run reports its own usage, and a run resuming after an interrupt reports only the calls it makes. A missing count means the provider did not report it, not that it used zero tokens.

An application can use those fields to calculate costs, but it still needs the applicable provider prices. AG-UI supplies an accounting convention, not a universal dollar bill.

Backward-compatible does not mean upgrade-free

CopilotKit describes 1.0 as backward-compatible. The migration guide explains the qualifications developers should check before upgrading:

• TypeScript validators move to @ag-ui/core/schemas. Nonstandard event properties need to move into metadata, and code handling tool results must accept content parts as well as strings.
• Python JSON Patch entries become typed objects. Code reading patch["path"] needs to use patch.path; serialization omits whole absent optional fields rather than emitting null.
• The .NET consumer has no translator for the retired { type: "binary" } content part. A producer still emitting that legacy shape must be upgraded before the 1.0 consumer can read it.

That last case is a concrete limit on a blanket “nothing breaks” interpretation. Wire compatibility and application source compatibility are different promises, and SDK behavior differs.

For a team already using AG-UI, a useful upgrade test is a tool that requests approval: interrupt it, reload the application, reconnect, answer the request and verify that the action runs only after the intended decision. Check the usage totals across both runs. That exercises the parts of 1.0 a polished streaming-chat demo can easily miss.