> ## Content Index
> Fetch the complete content index at: https://claudefox.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# AG-UI: connect an AI agent to a frontend app with a shared event protocol
- URL: https://claudefox.com/ag-ui-connect-an-ai-agent-to-a-frontend-app-with-a-shared/
- Published: 2026-11-16T15:16:51.000Z
- Updated: 2026-11-17T13:06:29.000Z
- Description: AG-UI is an event protocol that connects AI agents to user-facing applications. This post covers the scaffold, the packages, the key the examples need, and the version 1.0 limits to watch.
- Author: hupicake
- Tags: Tools

If your agent already works but has no good way to talk to the screen in front of a person, ag-ui-protocol/ag-ui gives you a shared event language for that gap. An agent backend sends a stream of typed events, and a client turns that stream into chat, tool results, shared state and pauses for a human decision. The repository holds the protocol definition, the TypeScript and Python kits, framework integrations and examples, so you can start from a scaffold or add packages to an existing project.

A run follows a simple shape. The app opens it by sending the agent one RunAgentInput holding the conversation, the tools the frontend offers, shared state and context. The agent replies with typed events from eight families: run lifecycle, text messages, tool calls, state, reasoning, activity, subagents, and raw and custom passthrough events. Only the lifecycle events are required, and a run ends with a finish or error event. State changes travel as snapshots or small patches.

## Quick facts

The main language of the repository is TypeScript, and a Python kit is included in the same tree. The project is free and open source under the MIT license, and it had about 18,500 GitHub stars as of November 16, 2026\. The protocol is at version 1.0, dated to September 17, 2026 in the deprecation notes. In the tree read for this post, the TypeScript client and core packages carry version 1.0.4 and the Python package carries version 1.0.0.

- Node.js: the client guide asks for Node 22.13.0 or later with pnpm, while the repository root requires Node 18 or later.
- Python: the Python kit requires Python 3.9 or later, while the server guide asks for Python 3.12 or later with Poetry.
- Latest release: the newest entry on the Releases page as of November 16, 2026 is Release 2026-11-13, published on November 13, 2026, under the tag release/2026-11-13.

## How to install

Start with the scaffold if you want a working application. The docs say it handles any client and server, but the CLI code offers two clients, CopilotKit on Next.js and a terminal client, with others listed as coming soon. Its nine framework flags, such as --mastra, all go to the CopilotKit path.

In the folder where you want the new application created, run:

```
npx create-ag-ui-app@latest
```

For the CopilotKit client, the docs say to start the server with this command once setup is done, then open localhost:3000:

```
npm run dev
```

The terminal client downloads a template without installing its dependencies and prints its next steps. In the folder where you ran the scaffold, using the default project name:

```
export OPENAI_API_KEY=your-api-key-here
cd my-ag-ui-cli-app
npm install
npm run dev
```

It is a chat loop in the terminal, so there is no page to open.

To add the client packages to a project you already have, follow the client guide. It needs pnpm, so if pnpm is not installed, run this in your own project folder:

```
# Install pnpm
npm install -g pnpm
```

In your own project folder, create a folder for the client and move into it:

```
mkdir my-ag-ui-client
cd my-ag-ui-client
```

From that new folder, initialise a Node.js project:

```
pnpm init
```

From the same folder, add TypeScript and the tools the guide uses:

```
pnpm add -D typescript @types/node tsx
```

From the same folder, add the core, Mastra and peer packages, exactly as the guide lists them:

```
# Core AG-UI packages
pnpm add @ag-ui/client @ag-ui/core @ag-ui/mastra

# Mastra ecosystem packages
pnpm add @mastra/core @mastra/client-js @mastra/memory @mastra/libsql

# Mastra peer dependencies
pnpm add zod
```

For Python, run one of these three lines in your own project folder, using the tool your project already uses:

```
pip install ag-ui-protocol
poetry add ag-ui-protocol
pipenv install ag-ui-protocol
```

## First setup

First check whether an integration already exists for your agent framework. The quickstart introduction says that with an existing one, such as LangGraph, CrewAI or Mastra, you can go straight to building an application. If none exists, you make one: the server style emits events directly from an agent you control, and the middleware style translates an existing system.

Both quickstart guides list one credential in their prerequisites: an OpenAI API key, read from the OPENAI\_API\_KEY environment variable. The client guide starts by exporting it in your shell, and the README says the scaffold templates call OpenAI, so set it before npm run dev. The server guide builds a standalone HTTP server on the GPT-4o model that streams events and handles tools and state; it also clones the repository over SSH and installs protobuf, Nx and pnpm. The client guide builds a terminal client around a Mastra agent with a weather tool.

## What stands out

- A typed event vocabulary with written behaviour rules. The README lists 31 event types in eight families for version 1.0, matching the EventType enum in the TypeScript core. The older architecture guide still says 16 and omits reasoning, activity and subagent events, and the draft events in the docs are proposals. Version 1.0 adds rules for sequencing, for unknown values against malformed values, and for how a run reports its ending.
- Transport choice stays with the implementer. The architecture guide lists server-sent events, webhooks and WebSockets, and CLAUDE.md adds HTTP binary and custom transports. Version 1.0 specifies an HTTP and Protobuf binding negotiated by media type, with 4-byte length-prefixed frames.
- State travels both ways in two forms. A snapshot carries a complete state, and a delta carries incremental updates as JSON Patch under RFC 6902, with a separate snapshot for conversation history. Metadata from the events that build one item, such as a message or a tool call, merges key by key with the last write winning and no recursion; run, step and snapshot events have no merge target, and the ag-ui key is reserved.
- Pauses, frontend tools and delegated work are part of the stream. A finished run can carry an interrupt outcome that says what the run waits for, with resume entries for continuing, or a cancelled outcome for a run stopped on purpose, which must not be reported as success. A run that stops on a frontend tool call finishes as success and may name the unanswered calls. Delegated work carries a subagent run identifier; a subagent start event is optional, but an announced subagent must close with a finish or error event.
- Breadth comes from SDKs and integrations rather than one language. The README lists TypeScript, Python and .NET SDKs, community SDKs for Kotlin, Go, Java, Dart, Rust, Ruby, C++ and Swift, and integrations including LangChain, CrewAI, Mastra, Google ADK and the Microsoft Agent Framework. Each building block in its feature table links a live demo in the AG-UI Dojo.

## How it was built with Claude

The tree read for this post contains CLAUDE.md and AGENTS.md at the top level, a .claude folder with a settings file, and a .claude-plugin folder with a marketplace file. CLAUDE.md describes itself as guidance for Claude Code, lists the pnpm commands for building, linting, type checking and testing, and points A2UI requests to a skill file. AGENTS.md tells agents to run tasks through Nx. The settings file allows a few Nx and type-check commands, and the marketplace lists one plugin, for the .NET kit.

Commit attribution was checked only in the latest 100 commits up to the commit read for this post, from November 4 to November 15, 2026, because a full-history clone did not finish in time. In that slice, 10 distinct commits carry a Co-Authored-By line naming Claude: 9 for Claude Opus 5.5 and 1 for Claude Fable 5.1\. Two of those same 10 commits also list Claude as the author.

**Try it with your AI.** Paste this into your own AI assistant to set up a first AG-UI application from the official scaffold or the client guide, using only the steps in this article.

```
Help me set up a first AG-UI application. First check my prerequisites and tell me what
is missing before doing anything else: Node.js 22.13.0 or later with pnpm for the
TypeScript client guide, or Python 3.12 or later with Poetry for the server guide. The
examples need an OpenAI API key in the OPENAI_API_KEY environment variable: tell me to
export it in my own shell, never ask me for it, and never write it into a file.

To scaffold, run npx create-ag-ui-app@latest in the folder where the new application
should be created. It offers two clients, CopilotKit/Next.js or a CLI client; I want
[CopilotKit/Next.js or CLI client]. For CopilotKit/Next.js with a specific framework,
add the matching flag, such as --mastra or --langgraph-py. For CopilotKit/Next.js, run
npm run dev in the created folder and check http://localhost:3000. For the CLI client,
cd into the created folder, run npm install, then npm run dev; it runs in the terminal,
so there is no page to check.

To add AG-UI to my existing TypeScript project instead, follow the client guide in full:
pnpm add -D typescript @types/node tsx, then pnpm add @ag-ui/client @ag-ui/core
@ag-ui/mastra, pnpm add @mastra/core @mastra/client-js @mastra/memory @mastra/libsql,
and pnpm add zod. For Python, use pip install ag-ui-protocol.

When you write event handling, use only event types from the AG-UI 1.0 EventType list,
such as RUN_STARTED, RUN_FINISHED, RUN_ERROR, STATE_SNAPSHOT and STATE_DELTA. Show me
every risky step first and wait for my confirmation before running it. Do not install
anything from unknown sources, do not touch credential files, and do not delete
anything.
```

## Known limits

Version 1.0 retires the older thinking events in favour of the reasoning family, and the compatibility shims for pre-1.0 shapes expire on September 17, 2027\. After that date a shim may be removed in the next release and the old shape stops working, so move to the replacements in the deprecation notes. The BackwardCompatibility\_0\_0\_47 class is already gone; remove explicit imports and registrations of it.

- Unknown events and fields pass through translation and are then dropped or stripped at enforcement, where the consumer should warn, while a malformed known value must fail the run. The spec notes that the Python and .NET SDKs do not yet have that enforcement stage.
- Capability declarations are informative only: the stream is authoritative, an omitted declaration means undeclared, and retrieval is left to the implementation. The subagent list must use the key subagents, because the older spelling is ignored.
- Not everything in the tables is ready. The docs introduction marks AWS Bedrock Agents, the Nim kit, Flowise and Langflow as in progress, so treat those entries as unfinished work rather than supported integrations.
- The client guide presents a hand-built client as a way to explore the protocol, and points to a full-featured client such as CopilotKit for production use.

For security, the policy asks for vulnerability reports by email to security@copilotkit.ai, kept out of public discussion, and promises acknowledgement within 48 hours, investigation within 5 business days, and a fix or mitigation aimed within 30 days of confirmation. The MIT license provides the software as is, without warranty.

## Related on claudefox

- [Floorplan: a Claude Code and Codex plugin that maps your codebase in plain English](https://claudefox.com/floorplan-plain-english-codebase-map-claude-code-codex/)
- [BLA (bla-agents): a CLI and MCP server that trips AI reverse-engineering limits on release files](https://claudefox.com/bla-agents-mcp-cli-ai-reverse-engineering-defense/)
- [rea-video: an open-source CLI that reverse-engineers a video shot by shot](https://claudefox.com/rea-video-reverse-engineer-video-shot-by-shot/)
- [AWS releases AWS Emulator, a free local copy of its APIs written entirely by AI agents](https://claudefox.com/aws-emulator-local-aws-apis-written-by-ai-agents/)

## Problems and feedback

Report bugs, request features and propose contributions on the Issues page at https://github.com/ag-ui-protocol/ag-ui/issues. The support page points questions to the project Discord, and the README adds GitHub Discussions. Send vulnerabilities to the security email, not a public issue.

Source: [ag-ui-protocol/ag-ui repository](https://github.com/ag-ui-protocol/ag-ui?ref=claudefox.com), [README](https://github.com/ag-ui-protocol/ag-ui/blob/main/README.md?ref=claudefox.com), [Releases](https://github.com/ag-ui-protocol/ag-ui/releases?ref=claudefox.com), [Issues](https://github.com/ag-ui-protocol/ag-ui/issues?ref=claudefox.com), [LICENSE](https://github.com/ag-ui-protocol/ag-ui/blob/main/LICENSE?ref=claudefox.com), [CLAUDE.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/CLAUDE.md?ref=claudefox.com), [AGENTS.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/AGENTS.md?ref=claudefox.com), [SECURITY.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/SECURITY.md?ref=claudefox.com), [DEPRECATIONS.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/DEPRECATIONS.md?ref=claudefox.com), [Docs introduction](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/introduction.mdx?ref=claudefox.com), [Quickstart introduction](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/quickstart/introduction.mdx?ref=claudefox.com), [Quickstart: build applications](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/quickstart/applications.mdx?ref=claudefox.com), [Quickstart: build clients](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/quickstart/clients.mdx?ref=claudefox.com), [Quickstart: server](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/quickstart/server.mdx?ref=claudefox.com), [Core architecture](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/concepts/architecture.mdx?ref=claudefox.com), [Events](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/concepts/events.mdx?ref=claudefox.com), [Spec 1.0 key changes](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/spec/1.0/changelog.mdx?ref=claudefox.com), [Support](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/support.mdx?ref=claudefox.com), [Python SDK README](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/README.md?ref=claudefox.com), [Python SDK pyproject.toml](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/pyproject.toml?ref=claudefox.com), [Root package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/package.json?ref=claudefox.com), [TypeScript client package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/client/package.json?ref=claudefox.com), [TypeScript core package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/package.json?ref=claudefox.com), [Scaffold CLI source (create-ag-ui-app)](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/cli/src/index.ts?ref=claudefox.com), [CLI client template README](https://github.com/ag-ui-protocol/ag-ui/blob/main/apps/client-cli-example/README.md?ref=claudefox.com), [EventType enum (TypeScript core)](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/src/generated/types.ts?ref=claudefox.com), [Spec 1.0: processing](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/spec/1.0/basic/processing.mdx?ref=claudefox.com), [Spec 1.0: metadata](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/spec/1.0/basic/metadata.mdx?ref=claudefox.com), [Spec 1.0: runs and steps](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/spec/1.0/events/lifecycle.mdx?ref=claudefox.com), [Spec 1.0: subagents](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/spec/1.0/events/subagents.mdx?ref=claudefox.com)

This story first appeared in the [claudefox daily briefing for November 16, 2026](https://claudefox.com/daily-2026-11-16/).