Agent-Skills.md

Agent Skills: AG-UI Knowledge

>

UncategorizedID: 46ki75/skills/ag-ui-knowledge

Repository

46ki75/skills
46ki75

Install this agent skill to your local

pnpm dlx add-skill https://github.com/46ki75/skills/tree/HEAD/skills/ag-ui-knowledge

Skill Files

Browse the full folder contents for ag-ui-knowledge.

Download Skill

Loading file tree…

skills/ag-ui-knowledge/SKILL.md

Skill Metadata

Name
ag-ui-knowledge
Description
>

AG-UI Knowledge

You are an expert in the AG-UI (Agent–User Interaction Protocol) — the open, event-based protocol that standardizes how AI agents communicate with user-facing applications in real time.

What AG-UI Is

AG-UI sits at the Agent ↔ User Interaction layer of the agentic-protocol stack, alongside two siblings:

| Layer | Protocol | Purpose | | -------------------- | -------------------------------- | -------------------------------------------------------------- | | Agent ↔ Tools / Data | MCP (Model Context Protocol) | Securely connect agents to tools, workflows, and data sources | | Agent ↔ Agent | A2A (Agent to Agent) | Coordinate work across distributed agents | | Agent ↔ User | AG-UI | Stream events between an agent runtime and the user-facing app |

A single agent often uses all three. AG-UI is built by CopilotKit in partnership with LangGraph and CrewAI.

Design principles

  • Event-driven — every interaction is a stream of typed, discriminated events (see Event categories).
  • Transport-agnostic — events flow over SSE, WebSockets, HTTP binary (protobuf), or anything else. AG-UI does not mandate a transport.
  • Framework-agnostic — any backend (LangGraph, CrewAI, Mastra, custom) can emit AG-UI events; any frontend can consume them.
  • Bidirectional shared state — agent and frontend share a JSON state model via snapshots and JSON-Patch deltas.
  • Human-in-the-loop is first-class — agents pause mid-run by ending with an interrupt outcome; clients resume by starting a new run carrying the user's response.

Core concepts (quick reference)

Most everyday AG-UI questions can be answered from this section without opening a reference file. Open references/ for full schemas, examples, or edge cases.

Run lifecycle

Every agent interaction is a run on a thread:

  1. Client POSTs a RunAgentInput to the agent's HTTP endpoint.
  2. Agent emits RUN_STARTED { threadId, runId }.
  3. Agent streams events (text, tool calls, state, reasoning, …).
  4. Agent emits RUN_FINISHED or RUN_ERROR.
  5. RUN_FINISHED carries an optional outcome:
    • omitted → legacy normal completion
    • { type: "success" } → normal completion
    • { type: "interrupt", interrupts: [...] } → paused for human input. Client resumes by starting a new run with RunAgentInput.resume = [{ interruptId, status, payload? }, …].

A parentRunId on RUN_STARTED creates a git-like branching log within the same thread (time travel, alternative paths).

Event categories

| Category | Events | | ------------------------- | ------------------------------------------------------------------------------------------------------------ | | Lifecycle | RUN_STARTED, RUN_FINISHED, RUN_ERROR, STEP_STARTED, STEP_FINISHED | | Text message | TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END, TEXT_MESSAGE_CHUNK | | Tool call | TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_RESULT, TOOL_CALL_CHUNK | | State | STATE_SNAPSHOT, STATE_DELTA, MESSAGES_SNAPSHOT | | Activity (in-progress UI) | ACTIVITY_SNAPSHOT, ACTIVITY_DELTA | | Reasoning | REASONING_START, REASONING_MESSAGE_START/CONTENT/END/CHUNK, REASONING_END, REASONING_ENCRYPTED_VALUE | | Special | RAW, CUSTOM | | Draft | META_EVENT | | Deprecated (→ v1.0.0) | THINKING_* (replaced by REASONING_*) |

Two recurring patterns:

  • Start-Content-End for streaming (text messages, tool calls, reasoning). *_CHUNK is a convenience event that auto-opens/closes the surrounding Start/End triad.
  • Snapshot-Delta for state. Snapshots replace; deltas mutate via RFC 6902 JSON Patch.

Message roles

user, assistant, system, tool, developer, activity, reasoning.

  • user content may be a plain string or an array of multimodal InputContent (text, image, audio, video, document — each with a source of data or url).
  • assistant may carry toolCalls and optional encryptedContent for ZDR-style state continuity.
  • tool carries toolCallId linking back to the originating tool call, plus optional error.
  • activity is frontend-only — never forwarded to the agent. Use it for progress UI (activityType: "PLAN" | "SEARCH" | …, structured content).
  • reasoning represents agent chain-of-thought. May be encrypted via encryptedValue; is round-tripped back to the agent on subsequent turns.

State

  • STATE_SNAPSHOT { snapshot } — replace the entire state.
  • STATE_DELTA { delta } — apply an array of RFC 6902 JSON Patch operations (add, remove, replace, move, copy, test).
  • MESSAGES_SNAPSHOT { messages } — replace the full message history.

The reference implementation uses fast-json-patch. On patch failure a client may request a fresh snapshot. State must be emitted before a RUN_FINISHED interrupt so resume is mode-agnostic (works for both replay- style and checkpoint-style continuations).

Tools

Tools are defined by the frontend and passed in RunAgentInput.tools. The agent calls them via the TOOL_CALL_* event triad; the frontend executes and returns a tool-role message with the matching toolCallId. CopilotKit exposes this through React's useCopilotAction hook.

Interrupts (human-in-the-loop)

An Interrupt carries { id, reason, message?, toolCallId?, responseSchema?, expiresAt?, metadata? }. Core reason values: tool_call, input_required, confirmation. Frameworks namespace custom reasons as <framework>:<name> (e.g. langgraph:database_modification).

Contract: a single resume array must address every open interrupt; RunAgentInput on a thread with pending interrupts must include resume or the agent emits RUN_ERROR. For tool-bound interrupts the agent does not re-emit TOOL_CALL_START/ARGS/END after resume — it emits TOOL_CALL_RESULT against the original toolCallId.

Reasoning

REASONING_* events stream visible reasoning summaries; REASONING_ENCRYPTED_VALUE attaches an opaque chain-of-thought blob (subtype: "message" | "tool-call") that the client stores and forwards back on subsequent turns without decrypting. This is the ZDR / store:false story.

Capabilities

Agents may expose getCapabilities(): Promise<AgentCapabilities> for discovery, not negotiation. Ten typed sub-objects: identity, transport, tools, output, state, multiAgent, reasoning, multimodal, execution, humanInTheLoop, plus custom. Omitted = unknown, never assumed.

Implementation paths

When implementing AG-UI, pick the role you're playing:

| Role | When to use | Key abstractions | | -------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Server | Building a new agent from scratch; want maximum control over emitted events | FastAPI/Express endpoint, EventEncoder, emit events directly | | Middleware | Adapting an existing framework or protocol (LangGraph, CrewAI, an internal SDK) to AG-UI | Extend AbstractAgent, translate framework events to AG-UI events inside run() | | Client | Building a UI (web, mobile, CLI) that talks to an AG-UI agent | HttpAgent or AbstractAgent.subscribe, handle the event stream |

Both server and middleware implementations expose the same HTTP contract: POST RunAgentInput, return an SSE (or binary) stream of BaseEvent objects.

SDKs at a glance

| Language | Package(s) | Status | Install | | ----------------------------------------------- | ---------------------------------------------------------------- | ----------- | ------------------------------ | | TypeScript / JavaScript | @ag-ui/core, @ag-ui/client, @ag-ui/encoder, @ag-ui/proto | 1st-party | npm install @ag-ui/client | | Python | ag-ui-protocol (ag_ui.core, ag_ui.encoder) | 1st-party | pip install ag-ui-protocol | | Rust | ag-ui-client crate | Community | cargo add ag-ui-client | | Java, Kotlin, Go, Dart, Ruby | various | Community | see upstream sdks/community/ | | .NET, Nim, Flowise, Langflow, Cloudflare Agents | — | In progress | tracked as upstream issues |

Quick start: npx create-ag-ui-app@latest scaffolds a project.

Routing table — which reference file do I open?

There are 17 reference files in references/. Open the ones below based on the question. Always prefer the most specific file.

Concepts (references/concepts/)

| Question | File | | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | Full event schema, properties of every event type, draft/deprecated events | concepts/events.md | | Architecture overview, transport patterns, middleware layer | concepts/architecture.md | | AbstractAgent shape, agent capabilities (high-level), agent lifecycle | concepts/agents.md | | Message schemas (User/Assistant/System/Tool/Activity/Developer/Reasoning), multimodal input, vendor-neutrality | concepts/messages.md | | STATE_SNAPSHOT vs STATE_DELTA, RFC 6902 JSON Patch examples, CopilotKit useCoAgent | concepts/state.md | | Tool schema, frontend-defined tools, tool-call lifecycle, useCopilotAction | concepts/tools.md | | Interrupt-aware run lifecycle, Interrupt type, resume rules, tool-bound interrupts, approve-with-edits, parallel interrupts | concepts/interrupts.md | | Reasoning events, encrypted chain-of-thought, ZDR/store:false, migration from THINKING_* | concepts/reasoning.md | | AgentCapabilities and all ten typed sub-objects | concepts/capabilities.md | | Middleware pipeline mechanics (use, MiddlewareFunction, Middleware class), built-in FilterToolCallsMiddleware | concepts/middleware.md | | Stream compaction, branching with parentRunId, normalized input | concepts/serialization.md | | Generative-UI specs (A2UI/Google, Open-JSON-UI/OpenAI, MCP-UI/Microsoft+Shopify); AG-UI is the runtime, not a gen-UI spec | concepts/generative-ui-specs.md |

Quickstart (references/quickstart/)

| Question | File | | ------------------------------------------------------------------------------ | -------------------------- | | Building a Python/FastAPI AG-UI endpoint from scratch (OpenAI example) | quickstart/server.md | | Building a JS/TS adapter that wraps an existing framework | quickstart/middleware.md | | Building a client (CLI/web) that consumes AG-UI events; Mastra + tools example | quickstart/client.md |

SDKs (references/sdks/)

| Question | File | | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | TypeScript: @ag-ui/client (AbstractAgent, HttpAgent, middleware, AgentSubscriber), @ag-ui/core types and events, @ag-ui/encoder, @ag-ui/proto | sdks/typescript.md | | Python: ag_ui.core types/events, ag_ui.encoder.EventEncoder, FastAPI/SSE patterns, multimodal input | sdks/python.md | | Rust, Java, Kotlin, Go, Dart, Ruby — install hints and pointers into the upstream repo | sdks/others.md |

Integrations (references/)

| Question | File | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | | Which agent frameworks support AG-UI (LangGraph, CrewAI, Mastra, Microsoft Agent Framework, Google ADK, AWS Strands, Bedrock AgentCore, Pydantic AI, Agno, LlamaIndex, AG2), which clients (CopilotKit), which related specs (A2A, MCP Apps, A2UI, Oracle Agent Spec) | integrations.md |

Source

All references in this skill are distilled from the upstream AG-UI documentation at submodules/ag-ui/docs/ (102 MDX files, snapshotted at the submodule's current commit). When the user needs the absolute latest text — release notes, draft specs, brand-new integrations — check the submodule directly or github.com/ag-ui-protocol/ag-ui. Each reference file cites its upstream path at the top so you can verify or expand from there.