AG-UI (Agent-User Interaction) is an open protocol that enables streaming events from AI agents to user interfaces, facilitating real-time communication between agent backends and frontend applications.

Overview

AG-UI provides a standardized way for agents to stream events to clients, supporting features like:

• Real-time text message streaming
• Tool execution and results rendering
• State synchronization between agent and client
• Run lifecycle management
• Multi-step agentic workflows

资料来源：sdks/typescript/packages/core/README.md:1-5

Architecture

AG-UI follows a client-server architecture where the agent backend streams events to the client using Server-Sent Events (SSE).

graph TD
    A[Agent Backend] -->|SSE Events| B[AG-UI Protocol]
    B --> C[Client Applications]
    D[State Updates] <--> B
    E[Tool Calls] <--> B
    C -->|User Input| A

Core Components

资料来源：sdks/typescript/packages/core/README.md:10-18

Event System

The AG-UI protocol defines 16 core event kinds covering the full agent interaction lifecycle.

Event Categories

资料来源：sdks/typescript/packages/core/README.md:14-15

Runtime Validation

Events are validated using schemas that catch malformed payloads early:

import { EventSchemas, EventType } from "@ag-ui/core";

EventSchemas.parse({
  type: EventType.TEXT_MESSAGE_CONTENT,
  messageId: "msg_123",
  delta: "Hello, world!",
});

资料来源：sdks/typescript/packages/core/README.md:29-35

SDKs and Language Support

AG-UI provides official and community SDKs for multiple programming languages:

Official SDKs

Community SDKs

资料来源：sdks/typescript/packages/core/README.md:1-50

资料来源：sdks/community/c++/README.md:1-100

资料来源：sdks/community/java/packages/client/README.md:1-20

Tool Integration

AG-UI supports bidirectional tool access where agents can call client-side tools and clients can execute server-side tools.

# Example: Agent accessing client-side tools (ADK Middleware)
tools=[
    AGUIToolset(tool_filter=lambda tool, readonly_context=None: tool.name.endswith('Goodbye'))
]

资料来源：integrations/adk-middleware/python/README.md:1-50

Tool Naming Convention

Tools can be filtered by naming patterns, allowing agents to selectively expose or access tools based on their suffixes or prefixes.

资料来源：integrations/adk-middleware/python/README.md:45-47

Framework Integrations

AG-UI integrates with multiple AI agent frameworks:

资料来源：sdks/typescript/packages/cli/README.md:30-40

资料来源：integrations/langroid/README.md:1-30

资料来源：integrations/pydantic-ai/typescript/README.md:1-50

Getting Started

Quick Start with CLI

npx create-ag-ui-app@latest

The CLI provides an interactive setup wizard supporting:

• CopilotKit/Next.js for web applications
• CLI clients for terminal-based interactions
• Automatic dependency installation and project structure setup

资料来源：sdks/typescript/packages/cli/README.md:1-40

Environment Configuration

资料来源：sdks/community/dart/example/README.md:50-60

Protocol Flow

sequenceDiagram
    participant Client
    participant AGUI as AG-UI Protocol
    participant Agent as Agent Backend
    
    Client->>Agent: Send user message
    Agent->>AGUI: Emit RUN_STARTED
    Agent->>AGUI: Emit TEXT_MESSAGE_START
    Agent->>AGUI: Emit TEXT_MESSAGE_CONTENT (streaming)
    Note over Agent,AGUI: Tool execution if needed
    Agent->>AGUI: Emit STATE_DELTA
    Agent->>AGUI: Emit TEXT_MESSAGE_END
    Agent->>AGUI: Emit RUN_FINISHED
    AGUI->>Client: Stream events via SSE

Documentation Resources

资料来源：sdks/typescript/packages/core/README.md:40-45

资料来源：sdks/community/ruby/README.md:1-30

License

AG-UI Protocol is licensed under the MIT License © 2025 AG-UI Protocol Contributors.

The AG-UI (Agent-User Interaction) Protocol is a framework-agnostic specification designed to enable seamless communication between AI agents and user interfaces. This document provides a comprehensive overview of the system's architecture, covering its core components, event-driven communication model, and the various SDK implementations available for different platforms.

Overview

AG-UI Protocol delivers strongly-typed building blocks that every implementation is built upon: message and state models, run inputs, and a complete set of streaming event types. The architecture is designed to be language-agnostic, supporting multiple SDK implementations including TypeScript, Python, Ruby, Dart, C++, Java, and Go.

资料来源：sdks/typescript/packages/core/README.md

Core Design Principles

The system architecture is built on several foundational principles that guide its implementation across all supported languages and frameworks:

Framework-Agnostic Design: The protocol works seamlessly in Node.js, browsers, and any agent framework capable of emitting JSON. This ensures that developers can integrate AG-UI into their existing stacks without significant refactoring.

Event-Driven Architecture: Communication between agents and clients occurs through a well-defined set of streaming events. This model supports real-time updates, tool calls, state mutations, and comprehensive run lifecycle management.

Runtime Validation: Schemas are implemented to catch malformed payloads early, ensuring data integrity throughout the communication pipeline.

High-Level Architecture

The AG-UI system consists of several interconnected layers that work together to provide a complete agent-user interaction framework.

graph TD
    subgraph Client["Client Layer"]
        FE[Frontend Client]
        Tools[Client Tools]
        State[State Management]
    end
    
    subgraph Protocol["Protocol Layer"]
        Events[Event Schemas]
        Types[Type Definitions]
        Validation[Runtime Validation]
    end
    
    subgraph Agent["Agent Layer"]
        LLM[LLM Agent]
        ServerTools[Server Tools]
        SubAgents[Sub-Agents]
    end
    
    subgraph Transport["Transport Layer"]
        HTTP[HTTP/WebSocket]
        SSE[Server-Sent Events]
    end
    
    FE --> Protocol
    Tools --> Protocol
    Protocol --> Transport
    Transport --> Agent
    ServerTools --> LLM
    SubAgents --> LLM
    State <--> Agent

资料来源：sdks/typescript/packages/core/README.md

Core Components

Protocol Layer

The protocol layer forms the backbone of the AG-UI system, providing the type definitions and event schemas that all other components depend upon.

#### Event Schemas

The @ag-ui/core package delivers strongly-typed data models including Message, Tool, Context, RunAgentInput, and State constructs. The package provides 16 core event kinds covering assistant messages, tool calls, state updates, and run lifecycle events.

资料来源：sdks/typescript/packages/core/README.md

#### Event Validation

Runtime validation is provided through schema parsing, allowing incoming events to be validated against their expected structure:

import { EventSchemas, EventType } from "@ag-ui/core";

EventSchemas.parse({
  type: EventType.TEXT_MESSAGE_CONTENT,
  messageId: "msg_123",
  delta: "Hello, world!",
});

Agent Layer

The agent layer encompasses the server-side implementations that process user requests and generate responses.

#### TypeScript Agent Implementation

The TypeScript SDK provides a comprehensive agent framework with support for sub-agents, tool integration, and state management. Agents are defined with a name, model, description, instruction, and tool configurations.

资料来源：integrations/claude-agent-sdk/typescript/README.md

#### Python Agent Integration

Python-based agents leverage frameworks like ADK (Agent Development Kit), Pydantic AI, Langroid, and AG2. These integrations bridge Python ML/AI frameworks with the AG-UI protocol, allowing any Python agent to communicate via the standardized event format.

资料来源：integrations/adk-middleware/python/README.md

#### Java Agent Components

The Java SDK provides both client and server implementations:

• AbstractAgent: Base class for agent implementations
• LocalAgent: Concrete implementation for local agent execution

资料来源：sdks/community/java/packages/server/README.md

Client Layer

The client layer handles frontend interactions, tool exposure, and state management.

#### Client Tools

Clients can expose tools to agents through a toolset mechanism. Tools are filtered and exposed based on configuration, allowing selective tool availability:

AGUIToolset(tool_filter=lambda tool, readonly_context=None: tool.name.endswith('Goodbye'))

资料来源：integrations/adk-middleware/python/README.md

#### State Management

State synchronization between client and server enables collaborative workflows. The bidirectional state sync mechanism ensures that both frontend and backend maintain consistent state views.

资料来源：integrations/claude-agent-sdk/typescript/README.md

SDK Architecture by Language

TypeScript SDK

The TypeScript SDK is organized into multiple packages that can be used independently or together:

graph LR
    subgraph TypeScript_SDK["TypeScript SDK"]
        Core["@ag-ui/core"] --> CLI["@ag-ui/cli"]
        Core --> Client["Client Libraries"]
        Core --> Server["Server Libraries"]
        CLI --> Integrations["Framework Integrations"]
    end

资料来源：sdks/typescript/packages/core/README.md 资料来源：sdks/typescript/packages/cli/README.md

Python SDK

The Python ecosystem supports multiple agent frameworks through middleware adapters:

资料来源：integrations/adk-middleware/python/README.md 资料来源：integrations/pydantic-ai/typescript/README.md

Multi-Language Support

The AG-UI protocol maintains consistent implementations across multiple programming languages, each following the same architectural patterns:

资料来源：sdks/community/java/packages/client/README.md 资料来源：sdks/community/c++/README.md

Communication Flow

Event Streaming Model

The AG-UI protocol uses a streaming event model where the server emits events that the client consumes in real-time. This enables responsive user interfaces with live updates.

sequenceDiagram
    participant Client
    participant Protocol
    participant Agent
    participant LLM
    
    Client->>Agent: POST /agent/run (RunAgentInput)
    Agent->>LLM: Query LLM
    LLM-->>Agent: Streaming Response
    Agent->>Protocol: Emit Events
    Protocol->>Client: Stream Events
    
    Note over Client,LLM: Real-time event emission during inference

Tool Call Flow

Tool invocations follow a specific sequence that enables both server-side and client-side tool execution:

graph TD
    Start[LLM Requests Tool] --> Filter{Check Tool Type}
    Filter -->|Server Tool| ServerExec[Execute Server Tool]
    Filter -->|Client Tool| ClientExec[Execute Client Tool]
    
    ServerExec --> ServerResult[Return Result]
    ClientExec --> Pause[Pause Stream]
    Pause --> Execute[Client Executes Tool]
    Execute --> Resume[Resume Stream]
    Resume --> FinalResult[Final Response]
    
    ServerResult --> FinalResult

资料来源：integrations/claude-agent-sdk/typescript/README.md

State Synchronization

State management in AG-UI supports bidirectional synchronization between client and server:

graph LR
    subgraph Client_State
        CS1[State View]
        CS2[State Mutation]
    end
    
    subgraph Server_State
        SS1[Canonical State]
        SS2[State Processing]
    end
    
    CS1 <-->|STATE_UPDATE| SS1
    CS2 -->|Mutation Event| SS2
    SS2 -->|State Confirmation| CS1

Framework Integrations

Claude Agent SDK Integration

The Claude Agent SDK adapter provides comprehensive AG-UI protocol support for Anthropic Claude models:

import { ClaudeAgentAdapter } from "@ag-ui/claude-agent-sdk";

const adapter = new ClaudeAgentAdapter({
  agentId: "my_agent",
  model: "claude-haiku-4-5",
  systemPrompt: "You are helpful",
});

const events$ = adapter.run(input);

Key features include full lifecycle management, interrupt support, dynamic frontend tool exposure, streaming tool arguments, and automatic event cleanup.

资料来源：integrations/claude-agent-sdk/typescript/README.md

ADK Middleware

The ADK middleware integrates Google Agent Development Kit with AG-UI, providing:

• 271 comprehensive tests covering all protocol features
• Tool support with automatic exposure to frontend clients
• State synchronization between frontend and backend
• Sub-agent orchestration capabilities

资料来源：integrations/adk-middleware/python/README.md

Langroid Integration

Langroid provides a multi-agent orchestration system with AG-UI support:

graph TD
    subgraph Langroid_System
        Orchestrator[Orchestrator Agent]
        Sub1[Specialist Agent 1]
        Sub2[Specialist Agent 2]
        Tools[Tool Registry]
    end
    
    Orchestrator --> Sub1
    Orchestrator --> Sub2
    Sub1 --> Tools
    Sub2 --> Tools

The integration includes both Python server implementations and TypeScript client libraries for frontend communication.

资料来源：integrations/langroid/README.md

Development Tools

CLI Tools

The AG-UI CLI provides development utilities for creating and managing AG-UI applications:

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

资料来源：sdks/typescript/packages/cli/README.md

Testing Infrastructure

Comprehensive testing is available across all SDK implementations. For example, the ADK Middleware includes 271 tests that verify protocol compliance and feature functionality:

# Run tests with coverage
pytest --cov=src/adk_middleware

资料来源：integrations/adk-middleware/python/README.md

Architecture Patterns

Builder Pattern for Agents

Many SDK implementations use the builder pattern for agent configuration:

#include "agent/http_agent.h"

auto agent = HttpAgent::builder()
    .withUrl("http://localhost:8080/api/agent/run")
    .withAgentId(AgentId("my-agent"))
    .build();

This pattern provides a fluent interface for configuring agent properties while maintaining immutability of the final agent instance.

资料来源：sdks/community/c++/README.md

Observable Pattern for Events

The TypeScript SDK and integrations use RxJS Observables for event streaming, allowing clients to subscribe to event streams with familiar patterns:

events$.subscribe({
  next: (event) => sendEvent(event),
  complete: () => res.end(),
});

资料来源：integrations/claude-agent-sdk/typescript/README.md

Security Considerations

API Key Management

The protocol supports API key authentication for securing agent endpoints:

资料来源：sdks/community/dart/example/README.md

Tool Exposure Control

Tools can be selectively exposed to agents using filter functions, preventing unauthorized access to sensitive client-side capabilities:

AGUIToolset(tool_filter=lambda tool, readonly_context=None: tool.name.endswith('Goodbye'))

资料来源：integrations/adk-middleware/python/README.md

Summary

The AG-UI Protocol architecture provides a robust, framework-agnostic foundation for building agent-user interaction systems. Its key architectural elements include:

• Event-driven communication with 16 core event kinds for comprehensive state management
• Multi-language SDK support spanning TypeScript, Python, Java, Ruby, Dart, C++, and Go
• Framework integrations for ADK, Pydantic AI, Langroid, Claude Agent SDK, and AG2
• Runtime validation ensuring data integrity across the communication pipeline
• Flexible tool exposure mechanisms for controlled tool access
• Bidirectional state synchronization enabling collaborative workflows

The architecture's modular design allows developers to use individual components independently or together, providing maximum flexibility for different use cases and technical requirements.

The Agent Protocol Stack is a multi-layered communication architecture that enables standardized interaction between AI agents and user interfaces. Built around the Agent-User Interaction (AG-UI) Protocol, this stack provides strongly-typed data models, streaming event systems, and framework-agnostic implementations across multiple programming languages.

Overview

The AG-UI Protocol defines how agents communicate with frontend applications through a streaming event-based mechanism. The protocol stack encompasses:

资料来源：sdks/typescript/packages/core/README.md

Architecture

The protocol stack follows a layered architecture where each layer builds upon the previous one:

graph TD
    A[Frontend Application] <-->|Streaming Events| B[Protocol Layer]
    B <-->|Event Translation| C[Framework Adapter]
    C <-->|Agent SDK Calls| D[Agent Runtime]
    
    E[Core Schemas] --> B
    F[Type Definitions] --> E
    
    G[TypeScript SDK] --> F
    H[Python SDK] --> F
    I[Go SDK] --> F
    J[Ruby SDK] --> F
    K[Java SDK] --> F
    L[Dart SDK] --> F
    
    M[Claude Adapter] --> C
    N[Langroid Adapter] --> C
    O[ADK Adapter] --> C
    P[Pydantic AI Adapter] --> C

资料来源：integrations/claude-agent-sdk/typescript/README.md

Core Event System

The event system is the foundation of the protocol, enabling real-time streaming communication between agents and frontends.

Event Categories

资料来源：sdks/typescript/packages/core/README.md

Event Flow Example

sequenceDiagram
    participant User
    participant Frontend
    participant Protocol
    participant Agent
    
    User->>Frontend: Send message
    Frontend->>Protocol: HTTP POST /agent/chat
    Protocol->>Agent: Forward request
    Agent->>Protocol: Emit TEXT_MESSAGE_START
    Agent->>Protocol: Emit TEXT_MESSAGE_CONTENT (streaming)
    Agent->>Protocol: Emit TOOL_CALL_START
    Agent->>Protocol: Emit TOOL_CALL_ARGS
    Agent->>Protocol: Emit TOOL_CALL_END
    Agent->>Protocol: Emit TEXT_MESSAGE_END
    Protocol->>Frontend: SSE Stream
    Frontend->>User: Render updates

资料来源：integrations/server-starter-all-features/typescript/README.md

Language SDKs

The protocol is implemented across multiple programming languages, each providing native bindings for the event system.

Available SDKs

资料来源：sdks/typescript/packages/core/README.md

TypeScript Core SDK

The TypeScript SDK provides the foundational definitions used by all other SDKs:

import { EventSchemas, EventType } from "@ag-ui/core";

EventSchemas.parse({
  type: EventType.TEXT_MESSAGE_CONTENT,
  messageId: "msg_123",
  delta: "Hello, world!",
});

Features:

• Strongly-typed data models (Message, Tool, Context, State)
• Runtime validation using JSON schemas
• Framework-agnostic (Node.js, browsers, any JS runtime)

资料来源：sdks/typescript/packages/core/README.md

Framework Adapters

Framework adapters translate between agent frameworks and the AG-UI protocol, enabling plug-and-play integration.

Supported Integrations

资料来源：integrations/claude-agent-sdk/python/README.md

Claude Agent SDK Adapter

The Claude adapter provides comprehensive lifecycle management:

import { ClaudeAgentAdapter } from "@ag-ui/claude-agent-sdk";

const adapter = new ClaudeAgentAdapter({
  agentId: "my_agent",
  model: "claude-haiku-4-5",
  systemPrompt: "You are helpful",
});

const events$ = adapter.run(input);
events$.subscribe({
  next: (event) => sendEvent(event),
  complete: () => res.end(),
});

Key Capabilities:

• Full lifecycle management (message extraction, option building, SDK querying)
• Interrupt support via adapter.interrupt()
• Dynamic frontend tools via MCP server
• Frontend tool halting for human-in-the-loop
• Streaming tool arguments
• Bidirectional state synchronization
• Context injection into prompts

资料来源：integrations/claude-agent-sdk/typescript/README.md

Go Genkit Integration

The Go integration demonstrates server implementation using Genkit:

type MyAgent struct{}

func (a *MyAgent) Run(ctx context.Context, input agents.RunAgentInput, eventsCh chan<- events.Event) error {
    // Emit TEXT_MESSAGE_START
    messageID := "msg-1"
    eventsCh <- events.NewTextMessageStartEvent(messageID, events.WithRole("assistant"))
    
    // Emit content chunks
    eventsCh <- events.NewTextMessageContentEvent(messageID, "Hello from my agent!")
    
    // Emit TEXT_MESSAGE_END
    eventsCh <- events.NewTextMessageEndEvent(messageID)
    
    return nil
}

资料来源：sdks/community/genkit/go/examples/README.md

Protocol Features

The AG-UI Protocol implements seven core features enabling rich agent-user interactions.

Feature Matrix

资料来源：integrations/server-starter-all-features/typescript/README.md

State Management

The protocol supports bidirectional state synchronization between agents and frontends:

graph LR
    A[Agent Runtime] <-->|STATE_UPDATE| B[Protocol Layer]
    B <-->|STATE_SNAPSHOT| C[Frontend State]
    
    D[User Action] -->|Update| C
    C -->|Sync| B
    B -->|Inject Context| A

State updates flow both directions, enabling:

• Agents to update UI state
• Frontends to modify agent context
• Optimistic updates during long-running operations

资料来源：integrations/claude-agent-sdk/python/README.md

Data Models

Core Types

Event Schema Example

interface TextMessageContentEvent {
  type: "TEXT_MESSAGE_CONTENT";
  messageId: string;
  delta: string;
  index?: number;
}

资料来源：sdks/typescript/packages/core/README.md

Client-Server Architecture

The protocol follows a client-server model with the server implementing the agent logic.

Java SDK Architecture

classDiagram
    class LocalAgent {
        +Run(input, events)
    }
    class AbstractAgent {
        +Name() string
        +Description() string
        +Run(ctx, input, events)
    }
    
    LocalAgent --|> AbstractAgent

Server Package (java-server):

• Contains LocalAgent abstract implementation
• Handles event emission and stream management

Client Package (java-client):

• Contains AbstractAgent base class
• Defines agent interface contracts

资料来源：sdks/community/java/packages/server/README.md

Dependency Configuration

For Java projects:

<dependency>
    <groupId>com.ag-ui.community</groupId>
    <artifactId>java-server</artifactId>
    <version>0.0.1</version>
</dependency>

<dependency>
    <groupId>com.ag-ui.community</groupId>
    <artifactId>java-client</artifactId>
    <version>0.0.1</version>
</dependency>

资料来源：sdks/community/java/packages/server/README.md

Quick Start

TypeScript

npm install @ag-ui/core

import { EventSchemas, EventType } from "@ag-ui/core";

EventSchemas.parse({
  type: EventType.TEXT_MESSAGE_CONTENT,
  messageId: "msg_123",
  delta: "Hello, world!",
});

Python

pip install ag-ui

from ag_ui import ClaudeAgentAdapter, add_claude_fastapi_endpoint

adapter = ClaudeAgentAdapter(name="my_agent", options={"model": "claude-haiku-4-5"})
add_claude_fastapi_endpoint(app=app, adapter=adapter, path="/my_agent")

Go

package main

import (
    "github.com/ag-ui-protocol/ag-ui/sdks/community/genkit/go/examples/internal/agents"
    "github.com/ag-ui-protocol/ag-ui/sdks/community/go/pkg/core/events"
)

type MyAgent struct{}

func (a *MyAgent) Run(ctx context.Context, input agents.RunAgentInput, eventsCh chan<- events.Event) error {
    // Implementation
    return nil
}

资料来源：sdks/typescript/packages/core/README.md

See Also

• AG-UI Protocol Documentation
• Concepts & Architecture
• Events Reference
• Contributing Guide

The Event Specification defines the complete contract for how the AG-UI Protocol communicates state changes, streaming content, tool interactions, and execution lifecycle events between agent backends and frontend clients. Events serve as the fundamental communication primitive in a unidirectional streaming model where the backend emits a sequence of typed events that clients consume to render UI, update state, and trigger human-in-the-loop interventions.

Overview

AG-UI events are typed, timestamped payloads that flow from an agent runtime to a connected client over Server-Sent Events (SSE) or WebSocket connections. Each event belongs to a specific category—text streaming, tool invocation, state mutation, or execution lifecycle—and carries the minimum necessary data for clients to react appropriately.

The event system is designed around three core principles:

1. Typed Events – Every event has a well-defined type string identifier that clients use to route handling logic.
2. Streaming-First – Events are emitted incrementally, allowing clients to render partial results (e.g., streaming text) in real-time.
3. Stateless Payloads – Events carry all necessary context; clients are responsible for aggregating state across event sequences.

资料来源：sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java:1-80

Event Type Categories

The AG-UI Protocol defines six logical categories of events. Each category addresses a distinct aspect of agent-client interaction.

graph TD
    A[AG-UI Events] --> B[Text Messages]
    A --> C[Thinking Messages]
    A --> D[Tool Calls]
    A --> E[Thinking Process]
    A --> F[State Management]
    A --> G[Execution Lifecycle]
    
    B --> B1[TEXT_MESSAGE_START]
    B --> B2[TEXT_MESSAGE_CONTENT]
    B --> B3[TEXT_MESSAGE_END]
    B --> B4[TEXT_MESSAGE_CHUNK]
    
    D --> D1[TOOL_CALL_START]
    D --> D2[TOOL_CALL_ARGS]
    D --> D3[TOOL_CALL_RESULT]
    D --> D4[TOOL_CALL_END]
    
    E --> E1[THINKING_MESSAGE_START]
    E --> E2[THINKING_MESSAGE_CONTENT]
    E --> E3[THINKING_MESSAGE_END]
    
    F --> F1[STATE_DELTA]
    F --> F2[STATE_SNAPSHOT]
    
    G --> G1[RUN_STARTED]
    G --> G2[RUN_FINISHED]
    G --> G3[RUN_ERROR]

Text Message Events

Text message events handle streaming textual output from the agent. These events support both incremental content delivery and complete message reconstruction on the client side.

资料来源：sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java:27-36

Tool Call Events

Tool call events enable the agent to request external tool execution with support for argument streaming and result retrieval. This category is essential for human-in-the-loop workflows where frontend clients execute tools on behalf of the agent.

资料来源：sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java

State Management Events

State events provide two complementary mechanisms for client-side state synchronization.

The StateDeltaEvent class encapsulates state changes without carrying the full application state:

public class StateDeltaEvent extends BaseEvent {
    public StateDeltaEvent() {
        super(EventType.STATE_DELTA);
    }
}

资料来源：sdks/community/java/packages/core/src/main/java/com/agui/core/event/StateDeltaEvent.java:1-40

Execution Lifecycle Events

Lifecycle events mark significant milestones in the run execution pipeline.

The RunErrorEvent captures error information for client-side error handling:

public class RunErrorEvent extends BaseEvent {
    private String error;
    
    public RunErrorEvent() {
        super(EventType.RUN_ERROR);
    }
    
    public void setError(final String error) {
        this.error = error;
    }
    
    public String getError() {
        return this.error;
    }
}

资料来源：sdks/community/java/packages/core/src/main/java/com/agui/core/event/RunErrorEvent.java:1-55

Raw Events

For extensibility and backward compatibility, the protocol includes a generic RAW event type that can carry arbitrary event data:

public class RawEvent extends BaseEvent {
    public RawEvent() {
        super(EventType.RAW);
    }
}

资料来源：sdks/community/java/packages/core/src/main/java/com/agui/core/event/RawEvent.java:1-35

Event Schema Structure

Every AG-UI event inherits from a common BaseEvent that provides standard fields required for all event types.

Base Event Fields

Event Payload Examples

Text Message Content Event:

{
  "type": "TEXT_MESSAGE_CONTENT",
  "messageId": "msg_abc123",
  "runId": "run_xyz789",
  "threadId": "thread_main",
  "delta": "Hello, how can I assist",
  "timestamp": 1704067200000
}

Tool Call Start Event:

{
  "type": "TOOL_CALL_START",
  "toolCallId": "tool_123",
  "toolName": "get_weather",
  "timestamp": 1704067200500
}

State Delta Event:

{
  "type": "STATE_DELTA",
  "state": {
    "weather": {
      "city": "San Francisco",
      "temperature": 18
    }
  },
  "timestamp": 1704067201000
}

Event Flow Architecture

The following diagram illustrates the typical event flow in an AG-UI enabled application:

sequenceDiagram
    participant FE as Frontend Client
    participant AG as AG-UI Gateway
    participant AR as Agent Runtime
    
    FE->>AG: POST /run (RunAgentInput)
    AG->>AR: Invoke agent with input
    AR->>AG: Emit TEXT_MESSAGE_START
    AG->>FE: SSE stream: TEXT_MESSAGE_START
    loop Streaming Content
        AR->>AG: Emit TEXT_MESSAGE_CONTENT
        AG->>FE: SSE stream: TEXT_MESSAGE_CONTENT
    end
    AR->>AG: Emit TOOL_CALL_START
    AG->>FE: SSE stream: TOOL_CALL_START
    Note over FE: Execute tool locally
    FE->>AG: Submit TOOL_CALL_RESULT
    AR->>AG: Emit RUN_FINISHED
    AG->>FE: SSE stream: RUN_FINISHED

Genkit Integration Example

The Genkit integration demonstrates how event types map to framework-specific content:

资料来源：integrations/community/genkit/go/README.md

// Event type handling in Genkit adapter
switch event.Type {
case events.EventTypeTextMessageStart:
    // Handle text message start
case events.EventTypeTextMessageChunk:
    // Handle text chunk
case events.EventTypeToolCallStart:
    // Handle tool call start
case events.EventTypeToolCallArgs:
    // Handle tool call arguments
case events.EventTypeToolCallResult:
    // Handle tool call result
}

Best Practices

Event Ordering

Events must be emitted in a deterministic order to ensure consistent client behavior:

1. RUN_STARTED – Always first
2. STATE_SNAPSHOT – If initial state is needed
3. Message-related events (TEXT_MESSAGE_START, content, end)
4. Tool call events (TOOL_CALL_START, args, result, end)
5. State updates (STATE_DELTA)
6. RUN_FINISHED or RUN_ERROR – Always last

Error Handling

When errors occur during event streaming:

• Emit RUN_ERROR with descriptive error message
• Include error context in the event payload
• Do not emit RUN_FINISHED after an error

Idempotency

Clients should handle duplicate events gracefully by using messageId and runId for deduplication when reconnecting or retrying requests.

Summary

The AG-UI Event Specification provides a comprehensive framework for real-time communication between agent runtimes and frontend clients. By defining clear event types, standardized schemas, and predictable event ordering, the protocol enables:

• Real-time streaming of text and tool content
• Synchronized state management across client and server
• Structured error handling and recovery
• Framework-agnostic integrations through consistent event contracts

All event types are defined as enumerations in the core SDK packages and extend a common BaseEvent class to ensure type safety and runtime validation.

Overview

The AG-UI protocol defines a comprehensive type system that enables structured communication between AI agents and frontend applications. These types serve as the foundation for the event-driven architecture that powers agent-user interactions.

Core responsibilities of the Types & Messages system:

• Define strongly-typed data models for messages, tools, context, and state
• Provide runtime validation through schema-based parsing
• Support streaming events for real-time agent communication
• Enable framework-agnostic implementation across TypeScript, Python, and other languages

资料来源：sdks/typescript/packages/core/README.md:1-15

Type System Architecture

graph TD
    A[AG-UI Types] --> B[Core Data Models]
    A --> C[Event Types]
    A --> D[Streaming Events]
    
    B --> B1[Message]
    B --> B2[Tool]
    B --> B3[Context]
    B --> B4[State]
    B --> B5[RunAgentInput]
    
    C --> C1[TextMessage Events]
    C --> C2[Thinking Events]
    C --> C3[Tool Call Events]
    C --> C4[State Update Events]
    C --> C5[Lifecycle Events]
    
    D --> D1[Server-Sent Events]
    D --> D2[JSON Payloads]
    D --> D3[Binary/Proto]

Core Data Models

Message Types

Messages represent the fundamental unit of communication in the AG-UI protocol. They are strongly typed and support various content types.

资料来源：sdks/typescript/packages/core/src/types.ts:1-50

#### Message Structure

#### Message Roles

Tool Types

Tools enable agents to perform actions and access external functionality.

资料来源：sdks/typescript/packages/core/src/types.ts:80-120

#### Tool Definition

State Types

State represents the application state that can be shared and synchronized between agent and frontend.

资料来源：sdks/typescript/packages/core/src/types.ts:150-200

#### State Structure

Run Agent Input

The RunAgentInput type defines the input schema for starting an agent run.

资料来源：sdks/typescript/packages/core/src/types.ts:250-300

#### RunAgentInput Fields

Event Types

The AG-UI protocol defines 16 core event types organized into logical categories for streaming communication.

资料来源：sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java:1-50

graph LR
    subgraph Text Messages
        T1[TEXT_MESSAGE_START]
        T2[TEXT_MESSAGE_CONTENT]
        T3[TEXT_MESSAGE_END]
        T4[TEXT_MESSAGE_CHUNK]
    end
    
    subgraph Thinking
        T5[THINKING_MESSAGE_START]
        T6[THINKING_MESSAGE_CONTENT]
        T7[THINKING_MESSAGE_END]
    end
    
    subgraph Tool Calls
        T8[TOOL_CALL_START]
        T9[TOOL_CALL_ARGUMENTS]
        T10[TOOL_CALL_END]
    end
    
    subgraph State
        T11[STATE_UPDATE]
        T12[STATE_SNAPSHOT]
    end
    
    subgraph Lifecycle
        T13[RUN_STARTED]
        T14[RUN_FINISHED]
        T15[ERROR]
    end

Text Message Events

资料来源：sdks/typescript/packages/core/src/events.ts:10-30

Thinking Events

These events enable displaying AI reasoning processes to users in real-time.

Tool Call Events

资料来源：sdks/typescript/packages/core/src/events.ts:50-80

State Management Events

Execution Lifecycle Events

Event Schema Validation

The AG-UI core package provides runtime validation through the EventSchemas class, which uses schema parsing to catch malformed payloads early.

资料来源：sdks/typescript/packages/core/README.md:30-40

import { EventSchemas, EventType } from "@ag-ui/core";

// Validate an incoming event
EventSchemas.parse({
  type: EventType.TEXT_MESSAGE_CONTENT,
  messageId: "msg_123",
  delta: "Hello, world!",
});

Event Payload Structure

All events follow a consistent structure:

Protocol Buffer Definitions

For high-performance scenarios, the AG-UI protocol includes Protocol Buffer definitions that provide binary serialization.

资料来源：sdks/typescript/packages/proto/src/generated/types.ts:1-100

The protobuf types maintain parity with the JSON types but offer advantages in bandwidth-constrained environments:

• Smaller payload sizes - Binary encoding reduces message overhead
• Faster parsing - Native binary parsing vs JSON string processing
• Language interoperability - Generated code for multiple languages

Proto Message Mapping

Serialization

The AG-UI protocol supports multiple serialization formats to accommodate different transport mechanisms and client requirements.

资料来源：docs/concepts/serialization.mdx:1-30

Supported Formats

JSON Schema

The TypeScript SDK exports JSON schemas that can be used for:

• Client-side validation - Validate incoming events
• Documentation generation - Auto-generate API docs
• Code generation - Create typed clients from schemas

Python Type System

The Python SDK provides equivalent type definitions through Pydantic models, ensuring type safety and validation in Python-based agent implementations.

资料来源：sdks/python/ag_ui/core/types.py:1-80

from ag_ui.core.types import Message, Tool, State, RunAgentInput
from ag_ui.core.events import EventType, BaseEvent

Python Type Mapping

Event Streaming Architecture

sequenceDiagram
    participant Client
    participant AGUICore
    participant Agent
    participant Tools
    
    Client->>AGUICore: Connect to stream
    Agent->>AGUICore: Emit TEXT_MESSAGE_START
    AGUICore->>Client: Stream event
    Agent->>AGUICore: Emit TEXT_MESSAGE_CONTENT
    AGUICore->>Client: Stream event (delta)
    Agent->>AGUICore: Emit TOOL_CALL_START
    AGUICore->>Client: Stream event
    Tools->>Agent: Execute tool
    Agent->>AGUICore: Emit TOOL_CALL_RESULT
    AGUICore->>Client: Stream event
    Agent->>AGUICore: Emit RUN_FINISHED
    AGUICore->>Client: Stream event

Usage Patterns

Creating a Message

import { Message, MessageRole } from "@ag-ui/core";

const userMessage: Message = {
  id: "msg_unique_123",
  role: MessageRole.User,
  content: "What's the weather in San Francisco?",
};

Defining a Tool

import { Tool } from "@ag-ui/core";

const weatherTool: Tool = {
  id: "tool_weather",
  name: "get_weather",
  description: "Get current weather for a location",
  inputSchema: {
    type: "object",
    properties: {
      location: { type: "string" },
      unit: { type: "string", enum: ["celsius", "fahrenheit"] },
    },
    required: ["location"],
  },
};

Processing Events

import { EventType } from "@ag-ui/core";

function handleEvent(event: BaseEvent) {
  switch (event.type) {
    case EventType.TEXT_MESSAGE_CONTENT:
      console.log("Received text:", event.delta);
      break;
    case EventType.TOOL_CALL_START:
      console.log("Tool called:", event.toolName);
      break;
    case EventType.STATE_UPDATE:
      console.log("State updated:", event.state);
      break;
  }
}

Framework Integration

The type system is designed to be framework-agnostic and integrates with:

• LangChain - Via @ag-ui/langchain integration
• LangGraph - Via @ag-ui/langgraph integration
• PydanticAI - Via @ag-ui/pydantic-ai integration
• ADK Middleware - Via adk-middleware integration
• Langroid - Via @ag-ui/langroid integration

Each integration maps its native types to the AG-UI type system, ensuring consistent behavior across different agent frameworks.

The Capabilities System is a fundamental component of the AG-UI (Agent-User Interaction) Protocol that enables runtime feature negotiation between clients and servers. It provides a standardized mechanism for declaring, discovering, and negotiating the features and functionalities that each party supports during an interactive session.

Overview

The AG-UI protocol supports seven core features that enable rich, interactive agent-user experiences. Not all implementations support all features, which creates the need for a capabilities negotiation system. The Capabilities System addresses this by allowing both clients and servers to advertise their supported features before or during a session, ensuring compatibility and graceful feature fallback.

The capabilities system operates on a publish-subscribe model where clients announce their capabilities to the server, and servers respond with their own capability declarations. This bidirectional capability exchange ensures that both parties understand what features are available and can adjust their behavior accordingly.

Architecture

The Capabilities System follows a layered architecture that separates capability definitions from their transport and negotiation mechanisms. This separation allows the system to be framework-agnostic while maintaining consistent behavior across different language implementations.

graph TD
    A[Client Application] --> B[AG-UI Client SDK]
    B --> C[Capabilities Manager]
    C --> D[Capability Definitions]
    C --> E[Capability Negotiation Engine]
    
    F[Server Application] --> G[AG-UI Server SDK]
    G --> H[Capabilities Validator]
    H --> D
    
    E <-->|Capability Exchange| H
    
    I[Core Capability Schemas] --> D
    J[Custom Capability Extensions] --> D

Core Capability Categories

The AG-UI protocol defines several categories of capabilities that cover different aspects of the agent-user interaction lifecycle. Each category contains specific features that implementations may choose to support or not support.

Agentic Chat Capabilities

Agentic Chat represents the foundational capability for conversational interactions between users and agents. This category includes text message streaming, multi-turn conversation management, and message state tracking. Servers with Agentic Chat capabilities can process user messages and respond with streaming text content that updates in real-time on the client side.

The core events for Agentic Chat include TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, and TEXT_MESSAGE_END events that allow for progressive rendering of agent responses. Clients supporting this capability can handle these events and display content as it arrives, providing a responsive user experience.

Backend Tool Rendering Capabilities

Backend Tool Rendering enables servers to expose server-side tools that clients can invoke through a standardized interface. This capability allows agents to perform actions on the server side, such as querying databases, calling external APIs, or executing business logic, with results streamed back to the client.

Tools are defined with names, descriptions, and parameter schemas that clients use to construct appropriate user interfaces for gathering tool inputs. The tool execution follows a request-response pattern where clients send tool call requests, servers execute the tools, and results are streamed back through dedicated events.

Human-in-the-Loop Capabilities

Human-in-the-Loop (HITL) capabilities enable agents to pause execution and await user confirmation before proceeding with critical or sensitive actions. This capability is essential for building trustworthy agentic applications where human oversight is required for certain operations.

When an agent encounters a tool call that requires human approval, it can emit a PAUSE event that stops execution. The client presents the approval request to the user, collects their response, and sends a RESUME event with the user's decision. This creates a controlled interaction pattern where agents cannot execute certain actions without explicit human authorization.

Agentic Generative UI Capabilities

Agentic Generative UI enables agents to dynamically generate custom user interface components based on the context of the conversation. Rather than relying on pre-defined UI templates, agents can emit structured data that the client transforms into interactive UI elements.

This capability supports complex, multi-step workflows where the agent breaks down tasks into discrete steps, each potentially requiring different UI presentations. The agent streams updates about the current step, progress indicators, and results, while the client renders appropriate interfaces for user interaction at each stage.

Tool-Based Generative UI Capabilities

Tool-Based Generative UI combines traditional tool calling with dynamic UI generation. Agents can call tools that return structured data, which is then transformed into rich, interactive UI components rendered on the client side. This approach leverages the precision of tool calls with the flexibility of generative UI.

Shared State Capabilities

Shared State capabilities establish bidirectional state synchronization between clients and servers. Both parties can update state, and changes are propagated to the other party in real-time through a defined protocol. This enables collaborative interactions where both humans and agents can contribute to a shared context.

The state management follows an event-sourcing pattern where state changes are represented as a sequence of events. Both clients and servers maintain authoritative views of the state and reconcile differences through a defined synchronization protocol.

Predictive State Updates Capabilities

Predictive State Updates allow servers to proactively send state updates that anticipate user needs or reflect the expected outcome of pending operations. This capability enables more responsive user experiences by reducing the latency between agent actions and UI updates.

Capability Definition Schema

The Capabilities System uses a structured schema for defining capabilities. Each capability has a name, version, and optional parameters that further describe its configuration and behavior.

Capability Negotiation Flow

The capability negotiation process occurs during session initialization and can be revisited during active sessions when new requirements emerge. The negotiation follows a request-response pattern where capabilities are proposed, accepted, or rejected.

sequenceDiagram
    participant Client
    participant Server
    participant CapabilitiesManager
    
    Client->>CapabilitiesManager: Create ClientCapabilities
    CapabilitiesManager-->>Client: Capability Instance
    Client->>Server: Send INITIALIZE with capabilities
    Server->>CapabilitiesManager: Validate client capabilities
    CapabilitiesManager-->>Server: Validation result
    Server->>CapabilitiesManager: Create ServerCapabilities
    Server->>Client: Send INITIALIZE_COMPLETE with server capabilities
    Client->>CapabilitiesManager: Compare and merge capabilities
    CapabilitiesManager-->>Client: Negotiated capability set

The negotiation process produces a merged capability set that represents the intersection of what both parties support. Implementations may choose to operate in degraded mode when certain capabilities are unavailable, or they may reject sessions when required capabilities are missing.

TypeScript Implementation

The TypeScript SDK provides a comprehensive implementation of the Capabilities System in the @ag-ui/core package. The implementation includes type-safe definitions for all standard capabilities and utility functions for capability management.

import { Capabilities, CapabilityType, negotiateCapabilities } from "@ag-ui/core";

// Define client capabilities
const clientCapabilities: Capabilities = {
  agenticChat: { enabled: true, version: "1.0.0" },
  backendToolRendering: { enabled: true, version: "1.0.0" },
  humanInTheLoop: { enabled: true, version: "1.0.0" },
  agenticGenerativeUI: { enabled: true, version: "1.0.0" },
  toolBasedGenerativeUI: { enabled: false, version: "1.0.0" },
  sharedState: { enabled: true, version: "1.0.0" },
  predictiveStateUpdates: { enabled: false, version: "1.0.0" }
};

// Negotiate with server capabilities
const negotiated = negotiateCapabilities(clientCapabilities, serverCapabilities);

The implementation provides runtime validation of capability configurations, ensuring that capability declarations conform to the expected schema before being used in negotiation.

Python Implementation

The Python SDK mirrors the TypeScript implementation, providing equivalent functionality for Python-based server and client applications. The implementation uses Pydantic models for schema validation and dataclasses for capability definitions.

from ag_ui.core.capabilities import (
    Capabilities,
    CapabilityType,
    negotiate_capabilities,
    ClientCapabilities,
    ServerCapabilities
)

# Define server capabilities
server_capabilities = ServerCapabilities(
    agentic_chat=CapabilityStatus(enabled=True, version="1.0.0"),
    backend_tool_rendering=CapabilityStatus(enabled=True, version="1.0.0"),
    human_in_the_loop=CapabilityStatus(enabled=True, version="1.0.0"),
    agentic_generative_ui=CapabilityStatus(enabled=True, version="1.0.0"),
    tool_based_generative_ui=CapabilityStatus(enabled=False, version="1.0.0"),
    shared_state=CapabilityStatus(enabled=True, version="1.0.0"),
    predictive_state_updates=CapabilityStatus(enabled=True, version="1.0.0")
)

# Negotiate with client capabilities
negotiated = negotiate_capabilities(client_capabilities, server_capabilities)

The Python implementation integrates seamlessly with FastAPI and other async web frameworks, providing capability endpoints that handle the negotiation protocol.

Integration Examples

Different agent frameworks integrate with the Capabilities System in various ways, depending on their architecture and requirements.

ADK Middleware Integration

The Google ADK Middleware integration uses the Capabilities System to expose AG-UI tools to ADK agents. The middleware declares its capabilities during initialization and validates incoming requests against the declared capability set.

from google.adk.middleware import Middleware
from ag_ui.core.capabilities import AGUIToolset

middleware = Middleware(
    name="ag_ui_middleware",
    capabilities={
        "agentic_chat": True,
        "backend_tool_rendering": True,
        "human_in_the_loop": True,
        "shared_state": True
    }
)

Claude Agent SDK Integration

The Claude Agent SDK integration implements a comprehensive set of capabilities that enable full AG-UI protocol support. The adapter handles capability negotiation and provides callback mechanisms for capability-related events.

from ag_ui_claude_sdk import ClaudeAgentAdapter

adapter = ClaudeAgentAdapter(
    name="my_agent",
    options={"model": "claude-haiku-4-5"},
    capabilities={
        "agentic_chat": True,
        "backend_tool_rendering": True,
        "human_in_the_loop": True,
        "agentic_generative_ui": True,
        "tool_based_generative_ui": True,
        "shared_state": True,
        "predictive_state_updates": True
    }
)

Capability Versioning

The Capabilities System supports semantic versioning for individual capabilities, allowing implementations to evolve independently while maintaining backward compatibility. Each capability declares its version as a semantic version string following the major.minor.patch format.

When negotiating capabilities, the system compares versions to determine compatibility. An implementation may declare that it supports a capability at version 1.2.0, while another implementation only supports version 1.0.0. The negotiation engine applies compatibility rules to determine whether these versions can interoperate.

Error Handling

The Capabilities System includes comprehensive error handling for invalid capability declarations and negotiation failures. Common error scenarios include missing required capabilities, version incompatibilities, and malformed capability objects.

Error responses include detailed information about the failure, including the specific capability that caused the error, the expected value, and the actual value that was received. This information enables developers to quickly diagnose and fix capability configuration issues.

Best Practices

When working with the Capabilities System, several best practices ensure robust and maintainable implementations.

Explicit Capability Declaration: Always explicitly declare all supported capabilities rather than relying on defaults. This makes the system's behavior predictable and documents the implementation's feature set clearly.

Version Pinning: Pin capability versions to specific values in production environments to ensure consistent behavior across deployments. Use range specifications only when testing or when backward compatibility is explicitly required.

Capability Fallback: Implement fallback behavior for unsupported capabilities. Rather than failing entirely, design agents to operate in degraded mode when certain capabilities are unavailable.

Capability Testing: Test capability negotiation thoroughly, including edge cases where partial capability sets are provided or where version mismatches occur.

Summary

The Capabilities System is a core component of the AG-UI Protocol that enables flexible, extensible agent-user interactions. By providing a standardized mechanism for declaring and negotiating features, it allows diverse implementations to interoperate while maintaining their independence. The system supports seven core feature categories and is implemented consistently across TypeScript, Python, and other supported language SDKs.

The AG-UI TypeScript SDK is a collection of strongly-typed packages that enable developers to build Agent-User Interaction (AG-UI) compliant applications in TypeScript and JavaScript. It provides the foundational building blocks for message modeling, event streaming, state management, and framework integrations.

Architecture Overview

The TypeScript SDK follows a modular architecture with core packages and framework-specific integrations.

graph TD
    A[Application Code] --> B[@ag-ui/core]
    A --> C[@ag-ui/client]
    B --> D[EventSchemas]
    B --> E[EventType]
    C --> F[Agent Client]
    C --> G[Middleware]
    F --> H[HTTP Transport]
    F --> I[WebSocket Transport]
    H --> J[LangChain]
    H --> K[LangGraph]
    H --> L[Vercel AI SDK]
    G --> M[a2a-middleware]
    G --> N[Custom Middleware]

Package Structure

Core Package (@ag-ui/core)

The @ag-ui/core package delivers the foundational type system and runtime validation for AG-UI protocol implementations.

Typed Data Models

The core package provides TypeScript interfaces for all AG-UI data models:

import { EventSchemas, EventType } from "@ag-ui/core";

// Validate an incoming event
EventSchemas.parse({
  type: EventType.TEXT_MESSAGE_CONTENT,
  messageId: "msg_123",
  delta: "Hello, world!",
});

Supported Data Models

资料来源：sdks/typescript/packages/core/README.md

Event System

The core package defines 16 core event kinds covering the complete agent lifecycle:

资料来源：sdks/typescript/packages/core/README.md

Runtime Validation

All event payloads are validated at runtime using Zod schemas, ensuring malformed payloads are caught early in the development process.

Client Package (@ag-ui/client)

The @ag-ui/client package provides the runtime client for connecting applications to AG-UI protocol servers.

Installation

npm install @ag-ui/client
pnpm add @ag-ui/client
yarn add @ag-ui/client

HTTP Agent

The HTTP agent handles communication with AG-UI backend servers:

import { HttpAgent } from "@ag-ui/client";

const agent = new HttpAgent({
  url: "http://localhost:8000/",
  apiKey: process.env.AG_UI_API_KEY,
});

#### Configuration Options

Event Streaming

The client supports full event streaming using RxJS observables:

import { createAgent } from "@ag-ui/client";

const agent = createAgent({
  url: "http://localhost:8000/",
});

agent.events$.subscribe((event) => {
  console.log("Received event:", event.type);
});

Middleware System

The TypeScript SDK implements a middleware system that allows intercepting and transforming requests and responses.

graph LR
    A[Request] --> B[Middleware 1]
    B --> C[Middleware 2]
    C --> D[Middleware N]
    D --> E[Agent]
    E --> F[Response]
    F --> G[Response Middleware]

Built-in Middleware

Creating Custom Middleware

import { createMiddleware } from "@ag-ui/client";

const loggingMiddleware = createMiddleware({
  name: "logger",
  onRequest: async (request, env) => {
    console.log("Request:", request);
    return request;
  },
  onResponse: async (response, env) => {
    console.log("Response:", response);
    return response;
  },
});

Framework Integrations

The TypeScript SDK provides pre-built integrations for popular agent frameworks:

LangChain Integration

{
  "dependencies": {
    "@ag-ui/core": ">=0.0.42",
    "@ag-ui/client": ">=0.0.42",
    "@langchain/core": "^1.1.40",
    "@langchain/langgraph-sdk": "^1.8.8",
    "langchain": ">=1.2.0"
  }
}

资料来源：integrations/langgraph/typescript/package.json

Vercel AI SDK Integration

{
  "dependencies": {
    "@ag-ui/core": ">=0.0.42",
    "@ag-ui/client": ">=0.0.42",
    "ai": "^4.3.16",
    "zod": "^3.22.4"
  }
}

资料来源：integrations/vercel-ai-sdk/typescript/package.json

A2A Middleware

The A2A (Agent-to-Agent) middleware enables interoperability with A2A protocol-compliant agents:

{
  "dependencies": {
    "@a2a-js/sdk": "^0.2.2",
    "ai": "^4.3.16",
    "zod": "^3.22.4"
  },
  "peerDependencies": {
    "@ag-ui/client": ">=0.0.40",
    "rxjs": "7.8.1"
  }
}

资料来源：middlewares/a2a-middleware/package.json

CLI Tool (@ag-ui/cli)

The AG-UI CLI provides project scaffolding capabilities:

npx create-ag-ui-app@latest my-agent-app
npx create-ag-ui-app@latest --help

资料来源：sdks/typescript/packages/cli/README.md

Quick Start

1. Install Core Dependencies

npm install @ag-ui/core @ag-ui/client

2. Create an Agent Client

import { HttpAgent } from "@ag-ui/client";
import { EventType } from "@ag-ui/core";

const agent = new HttpAgent({
  url: process.env.AG_UI_BASE_URL || "http://127.0.0.1:8000",
  apiKey: process.env.AG_UI_API_KEY,
});

// Subscribe to events
agent.events$.subscribe((event) => {
  switch (event.type) {
    case EventType.RUN_STARTED:
      console.log("Run started:", event.runId);
      break;
    case EventType.TEXT_MESSAGE_CONTENT:
      console.log("Message delta:", event.delta);
      break;
    case EventType.RUN_FINISHED:
      console.log("Run finished:", event.runId);
      break;
  }
});

3. Send a Message

await agent.send({
  type: "USER_MESSAGE",
  messageId: "msg_001",
  content: "Hello, agent!",
});

Environment Variables

Testing

The SDK includes comprehensive test coverage using Vitest:

# Run all tests
pnpm test

# Run with coverage
pnpm test:coverage

# Watch mode
pnpm test:watch

# Validate package exports
pnpm test:exports

Documentation

• Concepts & Architecture: docs.ag-ui.com/concepts/architecture
• Full API Reference: docs.ag-ui.com/sdk/js/core
• Contributing Guide: docs.ag-ui.com/development/contributing

License

MIT © 2025 AG-UI Protocol Contributors

The AG-UI Python SDK provides a Python implementation of the Agent-User Interaction (AG-UI) protocol, enabling Python developers to create server-side applications that communicate with AG-UI-compatible frontends using Server-Sent Events (SSE).

Overview

The Python SDK is designed as a lightweight, framework-agnostic foundation that offers:

• Core event models - Type-safe event definitions matching the AG-UI protocol specification
• Runtime schema validation - Pydantic-based schemas for early validation of payloads
• Event encoding - Utilities for encoding events into SSE format
• State management - Typed state models for bidirectional state synchronization

The SDK serves as the building block upon which higher-level integrations are built, including adapters for Langroid, Claude Agent SDK, ADK Middleware, Microsoft Agent Framework, and Pydantic AI.

Architecture

The Python SDK follows a modular architecture with distinct layers:

graph TD
    A[Application Layer] --> B[SDK Core]
    B --> C[Event Models]
    B --> D[Type Definitions]
    B --> E[Encoder]
    C --> F[ag_ui.core.events]
    D --> G[ag_ui.core.types]
    E --> H[ag_ui.encoder.encoder]
    F --> I[Runtime Validation]
    G --> I
    H --> J[SSE Output]
    J --> K[Frontend Client]

Package Structure

Event System

The SDK defines 16 core event kinds covering the complete AG-UI protocol lifecycle:

Event Categories

Event Validation

Events are validated at runtime using Pydantic schemas. This ensures malformed payloads are caught early and provides clear error messages for debugging.

from ag_ui.core.events import EventSchemas, EventType

# Validate an incoming event
validated_event = EventSchemas.parse({
    "type": EventType.TEXT_MESSAGE_CONTENT,
    "messageId": "msg_123",
    "delta": "Hello, world!"
})

Core Types

The SDK provides strongly-typed data models for AG-UI concepts:

Event Encoding

The encoder module handles serialization of AG-UI events into Server-Sent Events format:

sequenceDiagram
    participant App as Application
    participant SDK as Python SDK
    participant Encoder as Event Encoder
    participant Client as Frontend

    App->>SDK: Create event object
    SDK->>Encoder: Encode to SSE format
    Encoder->>Client: data: {"type": "...", ...}\n\n
    Client->>Client: Parse and render

The encoder ensures proper SSE formatting with:

• JSON serialization of event data
• Double newline termination as per SSE spec
• Support for event type naming

Integration Patterns

The Python SDK is used as the foundation for framework-specific integrations:

Direct Usage

from ag_ui import AGUIServer, Agent

agent = Agent(name="my_agent")
server = AGUIServer(agent=agent)

# Stream events to client
async for event in agent.run(input_data):
    await server.send(event)

Integration Ecosystem

Installation

pip install ag-ui
# or with uv
uv pip install ag-ui

Configuration

Testing

The SDK includes a comprehensive test suite with mock server support:

# Run tests
pytest

# With coverage
pytest --cov=src/ag_ui

# Specific test file
pytest tests/test_events.py

Documentation

Additional documentation is available at:

• Concepts & architecture: docs/concepts
• Python SDK reference: docs/sdk/python/core
• Full API reference: docs/events

Contributing

Bug reports and pull requests are welcome. Please read the contributing guide before submitting changes.

License

MIT © 2025 AG-UI Protocol Contributors

The AG-UI protocol maintains a growing ecosystem of community-developed Software Development Kits (SDKs) across multiple programming languages. These SDKs enable developers to integrate AG-UI protocol support into diverse technology stacks, extending the protocol's reach beyond the official TypeScript implementation.

Overview

Community SDKs are contributed and maintained by developers outside the core AG-UI team. Each SDK implements the AG-UI event streaming protocol, allowing agents built in various languages to communicate with AG-UI-compatible frontends. The SDKs handle:

• Event encoding and decoding following the AG-UI event schema
• HTTP/WebSocket communication with AG-UI servers
• State synchronization between agent and client
• Tool call handling and response streaming

资料来源：sdks/community/ruby/README.md

Supported Languages

The AG-UI community has contributed SDK implementations for the following programming languages:

Architecture Pattern

All community SDKs follow a consistent architectural pattern for AG-UI integration:

graph TD
    A[AG-UI Client/Frontend] <--> |SSE/WebSocket| B[Community SDK Server]
    B --> C[Language-Specific Agent Implementation]
    C --> D[Agent Logic/Tools]
    B --> E[State Management]
    E --> A
    
    F[Event Encoder] --> B
    G[Event Decoder] --> B

Component Responsibilities

资料来源：integrations/langroid/README.md

Dart SDK

The Dart SDK enables Flutter and Dart applications to interact with AG-UI protocol servers. It provides both synchronous and asynchronous communication patterns.

Environment Configuration

Basic Usage

import 'package:ag_ui_dart/ag_ui_dart.dart';

// Create an HTTP Agent
final agent = HttpAgent(
  url: 'http://localhost:8080/api/agent/run',
  agentId: 'my-agent',
);

// Subscribe to events
agent.subscribe((event) {
  print('Received event: ${event.type}');
});

// Send user message
await agent.sendMessage('Hello, agent!');

资料来源：sdks/community/dart/example/README.md

Ruby SDK

The Ruby SDK provides idiomatic Ruby integration for the AG-UI protocol, suitable for Ruby on Rails applications or standalone Ruby agents.

Installation

cd sdks/community/ruby
bundle install

Running Examples

# Navigate to example directory
cd sdks/community/ruby/example/simple-use

# Install dependencies
bundle install

# Run the example
bundle exec ruby main.rb

Testing

cd sdks/community/ruby
rake test

Documentation

Generate YARD documentation:

cd sdks/community/ruby
rake doc

资料来源：sdks/community/ruby/README.md

C++ SDK

The C++ SDK provides a header-only, dependency-light implementation suitable for embedded systems and performance-critical applications.

Build Dependencies

Building the SDK

# Clone and navigate to C++ SDK directory
git clone https://github.com/ag-ui-protocol/ag-ui.git
cd ag-ui/sdks/community/c++

# Create build directory
mkdir build && cd build

# Configure with tests enabled
cmake -DBUILD_TESTS=ON ..

# Build
make -j4

Basic Usage

#include "agent/http_agent.h"

using namespace agui;

int main() {
    auto agent = HttpAgent::builder()
        .withUrl("http://localhost:8080/api/agent/run")
        .withAgentId(AgentId("my-agent"))
        .build();
    
    // Create subscriber for events
    class MySubscriber : public IAgentSubscriber {
        AgentStateMutation onTextMessageContent(
            const TextMessageContentEvent& event,
            const std::string& buffer,
            const AgentSubscriberParams& params) override {
            std::cout << event.delta;
            return AgentStateMutation::CONTINUE;
        }
    };
    
    agent->subscribe(std::make_shared<MySubscriber>());
    return 0;
}

资料来源：sdks/community/c++/README.md

Java SDK

The Java SDK provides enterprise-grade AG-UI protocol support with two main components: the core client and an OkHttp-based HTTP client.

Maven Dependency

<dependency>
    <groupId>com.ag-ui.community</groupId>
    <artifactId>java-client</artifactId>
    <version>0.0.1</version>
</dependency>

OkHttp Client

For applications using OkHttp:

<dependency>
    <groupId>com.ag-ui.community</groupId>
    <artifactId>java-ok-http</artifactId>
    <version>4.12.0</version>
</dependency>

Key Components

资料来源：sdks/community/java/packages/client/README.md

资料来源：sdks/community/java/clients/ok-http/README.md

Kotlin SDK

The Kotlin SDK provides AG-UI protocol support for JVM applications with idiomatic Kotlin patterns including coroutines support and DSL-style builders.

Overview

The Kotlin SDK offers:

• Coroutines-based asynchronous communication
• Type-safe builders for agent configuration
• Seamless interoperability with Java

资料来源：docs/sdk/kotlin/overview.mdx

Go SDK

The Go SDK provides lightweight AG-UI protocol integration optimized for concurrent operations and minimal memory footprint.

Features

• Goroutine-friendly concurrent event processing
• Channel-based event streaming
• Minimal dependencies
• High performance for production workloads

资料来源：docs/sdk/go/overview.mdx

Rust SDK

The Rust SDK (ag-ui-client) offers memory-safe, high-performance AG-UI protocol support suitable for systems programming and performance-critical applications.

Key Features

• Zero-cost abstractions
• Async runtime support
• Memory safety guarantees
• Small binary footprint

Integration with Langroid

The Langroid integration demonstrates how community SDKs can bridge different agent frameworks with the AG-UI protocol.

graph LR
    A[TypeScript Frontend] <--> B[Langroid TypeScript Client]
    B <--> C[Langroid Python Server]
    C --> D[Python Agent Implementation]
    
    E[Python Tools] --> D
    F[AG-UI Tools] --> B

Langroid Python Integration

# Install dependencies
cd python
pip install -e .
cd examples
pip install -e .

Langroid TypeScript Client

import { LangroidHttpAgent } from "@ag-ui/langroid";

const agent = new LangroidHttpAgent({
  url: "http://localhost:8000/",
});

资料来源：integrations/langroid/README.md

资料来源：integrations/langroid/typescript/README.md

Contributing

Community SDK contributions are welcome. The project maintains contribution guidelines that all SDK contributors should follow.

Contribution Process

1. Create a new directory under sdks/community/<language>/
2. Implement the AG-UI event protocol specification
3. Include README.md with installation and usage instructions
4. Add tests for core functionality
5. Submit a pull request for review

Quality Standards

资料来源：sdks/community/ruby/README.md

License

All community SDKs are released under the MIT License. See the main AG-UI repository for complete license information.

The @ag-ui/langgraph integration provides a comprehensive bridge between LangGraph workflows and frontend applications through the Agent-User Interaction (AG-UI) Protocol. This integration enables developers to connect stateful, multi-step LangGraph agents to any AG-UI-compatible frontend, supporting both local TypeScript graph instances and remote LangGraph Cloud deployments.

Overview

LangGraph is a library for building stateful, multi-actor applications with Large Language Models (LLMs). The AG-UI LangGraph integration extends these capabilities by providing:

• Bidirectional state synchronization between graph nodes and frontend interfaces
• Real-time streaming event support for assistant messages, tool calls, and state updates
• Human-in-the-loop workflow support through interrupt handling
• Step tracking for real-time node execution progress monitoring
• Full compatibility with LangGraph Cloud and local graph deployments

资料来源：integrations/langgraph/typescript/README.md

Architecture

The integration follows a layered architecture that separates concerns between the agent runtime, state management, event streaming, and frontend communication.

graph TD
    subgraph Frontend["Frontend Client"]
        A[AG-UI Client]
        B[CopilotKit]
        C[Custom UI]
    end

    subgraph LangGraphIntegration["@ag-ui/langgraph"]
        D[LangGraphAgent]
        E[State Streaming Middleware]
        F[Event Emitters]
    end

    subgraph LangGraph["LangGraph Runtime"]
        G[Graph Definition]
        H[Graph Nodes]
        I[State Store]
    end

    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    F --> A
    G --> H
    H --> I
    I --> E

Core Components

资料来源：integrations/langgraph/typescript/README.md

Features

Cloud & Local Support

The integration operates seamlessly across two deployment modes:

Local Mode: Connect directly to TypeScript or Python graph instances running locally. This mode provides full control over the graph execution and state management.

Cloud Mode: Connect to remote LangGraph Cloud deployments via the LangGraph SDK. This mode leverages LangGraph's cloud infrastructure for scalability and reliability.

graph LR
    subgraph Deployment["Deployment Options"]
        L[Local Deployment]
        C[Cloud Deployment]
    end

    L -->|Direct Connection| AG[@ag-ui/langgraph]
    C -->|LangGraph SDK| AG

    AG -->|AG-UI Events| FE[Frontend]

资料来源：integrations/langgraph/typescript/README.md

State Management

The integration provides bidirectional state synchronization between the LangGraph state store and the AG-UI protocol:

• Read State: Middleware reads graph state at configurable intervals or triggers
• Write State: Frontend can update shared state through AG-UI state update events
• Conflict Resolution: Last-write-wins semantics with optional optimistic updates

sequenceDiagram
    participant FE as Frontend
    participant MW as State Middleware
    participant GS as Graph State
    participant LG as LangGraph

    FE->>MW: subscribeToState()
    MW->>GS: getState()
    GS-->>MW: currentState
    MW-->>FE: stateUpdate event

    LG->>GS: updateState()
    GS-->>LG: stateUpdated
    LG->>MW: notifyChange()
    MW->>FE: stateUpdate event

资料来源：integrations/langgraph/typescript/src/middlewares/state-streaming.ts

Interrupt Handling

Human-in-the-loop workflows are supported through LangGraph's interrupt mechanism. When an interrupt occurs, the integration:

1. Pauses graph execution at designated checkpoints
2. Streams current state and pending actions to the frontend
3. Waits for human approval/rejection/input
4. Resumes execution with the provided feedback

Step Tracking

Real-time progress updates track node execution through the graph:

interface StepUpdate {
  stepId: string;
  nodeName: string;
  status: 'pending' | 'running' | 'completed' | 'error';
  metadata?: Record<string, unknown>;
}

Installation

TypeScript

npm install @ag-ui/langgraph
pnpm add @ag-ui/langgraph
yarn add @ag-ui/langgraph

Peer Dependencies:

资料来源：integrations/langgraph/typescript/package.json

Python

pip install ag-ui-langgraph

Usage

TypeScript Example

import { LangGraphAgent } from "@ag-ui/langgraph";

// Create an AG-UI compatible agent
const agent = new LangGraphAgent({
  graphId: "my-graph",
  deploymentUrl: "https://your-langgraph-deployment.com",
  langsmithApiKey: "your-api-key",
});

// Run with streaming
const result = await agent.runAgent({
  messages: [{ role: "user", content: "Start the workflow" }],
});

// Subscribe to state updates
agent.subscribeToState((state) => {
  console.log("State updated:", state);
});

资料来源：integrations/langgraph/typescript/README.md

Python Example

from ag_ui_langgraph import LangGraphAgent, AgentInput

agent = LangGraphAgent(
    graph_id="my-graph",
    deployment_url="https://your-langgraph-deployment.com"
)

async for event in agent.run_agent(AgentInput(
    messages=[{"role": "user", "content": "Hello"}]
)):
    print(event)

资料来源：integrations/langgraph/python/README.md

Configuration Options

LangGraphAgent Configuration

State Streaming Middleware

Available Agents

The integration includes TypeScript examples demonstrating various agent patterns:

1. Agentic Chat (`agentic_chat`)

A simple agentic chat flow using LangGraph following the ReAct design pattern. Handles tool binding, system prompts, and model responses.

2. Agentic Generative UI (`agentic_generative_ui`)

Demonstrates agentic generative UI capabilities. Creates task steps and simulates their execution while streaming updates to the frontend.

3. Human in the Loop (`human_in_the_loop`)

Implements human-in-the-loop functionality where users can interact with and modify the agent's proposed steps before execution.

4. Predictive State Updates (`predictive_state_updates`)

Shows predictive state updates for document writing with streaming tool calls to the frontend.

5. Shared State (`shared_state`)

Demonstrates shared state management between the agent and CopilotKit, focusing on recipe creation and modification.

资料来源：integrations/langgraph/typescript/examples/README.md

Running the Examples

TypeScript Examples

cd integrations/langgraph/typescript/examples

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start with LangGraph CLI
pnpx @langchain/[email protected] dev

Python Examples

cd integrations/langgraph/python/examples

# Create .env file
cp .env.example .env

# Add your API keys
# OPENAI_API_KEY=your-key

# Install dependencies
pip install -e .

# Run the server
poetry run python -m server

The server will start on http://0.0.0.0:8003.

资料来源：integrations/langgraph/typescript/examples/README.md

Development

Build Commands

Testing

# Run all tests
npm run test

# Watch mode for development
npm run test:watch

# Coverage report
npm run test:coverage

# Export validation
npm run test:exports

Dependencies

The integration depends on the following packages:

资料来源：integrations/langgraph/typescript/package.json

Related Integrations

For other agent framework integrations, see the main integrations documentation:

• ADK Middleware: Google Agent Development Kit integration
• PydanticAI: PydanticAI agent integration
• Claude Agent SDK: Anthropic Claude agent integration
• Langroid: Multi-agent framework integration
• CrewAI: CrewAI agent integration
• Mastra: Mastra agent integration
• Agno: Agno agent integration
• LlamaIndex: LlamaIndex agent integration
• A2A Middleware: Agent-to-Agent protocol middleware

资料来源：docs/integrations.mdx

Pitfall Log / 踩坑日志

项目：ag-ui-protocol/ag-ui

摘要：发现 13 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature]: Update Zod to ^4.0.0。

1. 安装坑 · 来源证据：[Feature]: Update Zod to ^4.0.0

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Update Zod to ^4.0.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_864feb35f0a7491399ed9e6f32d716d0 | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | 来源类型 github_issue 暴露的待验证使用条件。

2. 配置坑 · 来源证据：Java dependencies not found

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Java dependencies not found
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_76cfe35c206349ceb926d2253bc2cf03 | https://github.com/ag-ui-protocol/ag-ui/issues/930 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安全/权限坑 · 来源证据：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RunAgentInput should allow null for threadId/runId to support server-minted IDs
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_53c2f6a0605444afbd53e56d090a6295 | https://github.com/ag-ui-protocol/ag-ui/issues/1454 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安装坑 · 失败模式：installation: [Feature]: Update Zod to ^4.0.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [Feature]: Update Zod to ^4.0.0
• 对用户的影响：Developers may fail before the first successful local run: [Feature]: Update Zod to ^4.0.0
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Feature]: Update Zod to ^4.0.0. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_334526f2cd6ed9dc89c052647aa8d0eb | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | [Feature]: Update Zod to ^4.0.0

5. 配置坑 · 失败模式：configuration: Java dependencies not found

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Java dependencies not found
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Java dependencies not found
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Java dependencies not found. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_cc82631789b14e6fa478fc47a467a6bd | https://github.com/ag-ui-protocol/ag-ui/issues/930 | Java dependencies not found

6. 配置坑 · 失败模式：configuration: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: RunAgentInput should allow null for threadId/runId to support server-minted IDs
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: RunAgentInput should allow null for threadId/runId to support server-minted IDs
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: RunAgentInput should allow null for threadId/runId to support server-minted IDs. Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_2a937e8cd4049e7cc373577023297a5c | https://github.com/ag-ui-protocol/ag-ui/issues/1454 | RunAgentInput should allow null for threadId/runId to support server-minted IDs

7. 配置坑 · 来源证据：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6674fe14155d4baeb366f4ac441fd962 | https://github.com/ag-ui-protocol/ag-ui/issues/1719 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

8. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | README/documentation is current enough for a first validation pass.

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | last_activity_observed missing

10. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | no_demo; severity=medium

11. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | no_demo; severity=medium

12. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | issue_or_pr_quality=unknown

13. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | release_recency=unknown