Back to Details

ag-ui-pydantic

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AG-UI with Pydantic AI

AG-UI 结合 Pydantic AI

Build agentic UIs where Python agents communicate with React frontends via the AG-UI protocol.
构建通过AG-UI协议实现Python智能体与React前端通信的智能体UI。

Architecture Overview

架构概述

┌─────────────────┐     AG-UI Protocol      ┌──────────────────┐
│  Pydantic AI    │ ◄──────────────────────►│   CopilotKit     │
│  (FastAPI)      │   Events & State        │   (React/Next)   │
└─────────────────┘                         └──────────────────┘
┌─────────────────┐     AG-UI Protocol      ┌──────────────────┐
│  Pydantic AI    │ ◄──────────────────────►│   CopilotKit     │
│  (FastAPI)      │   Events & State        │   (React/Next)   │
└─────────────────┘                         └──────────────────┘

Quick Start

快速开始

Backend (Python):
python
from pydantic_ai import Agent

agent = Agent('openai:gpt-4o-mini')
app = agent.to_ag_ui()  # Creates FastAPI-compatible ASGI app
Frontend (React):
tsx
<CopilotKit runtimeUrl="/api/copilotkit" agent="myAgent">
  <CopilotChat />
</CopilotKit>
后端（Python）：
python
from pydantic_ai import Agent

agent = Agent('openai:gpt-4o-mini')
app = agent.to_ag_ui()  # Creates FastAPI-compatible ASGI app
前端（React）：
tsx
<CopilotKit runtimeUrl="/api/copilotkit" agent="myAgent">
  <CopilotChat />
</CopilotKit>

Core Patterns

核心模式

1. Agentic Chat (Basic)

1. 智能体聊天（基础版）

Simple chat with server-side tools. See 
references/backend-patterns.md#agentic-chat
.
带服务端工具的简易聊天功能。详见
references/backend-patterns.md#agentic-chat
。

2. Shared State

2. 共享状态

Bidirectional state sync between agent and UI using 
StateDeps
:
python
from pydantic_ai.ag_ui import StateDeps

agent = Agent('openai:gpt-4o-mini', deps_type=StateDeps[MyStateModel])
app = agent.to_ag_ui(deps=StateDeps(MyStateModel()))
See 
references/backend-patterns.md#shared-state
.
使用
StateDeps
实现智能体与UI之间的双向状态同步：
python
from pydantic_ai.ag_ui import StateDeps

agent = Agent('openai:gpt-4o-mini', deps_type=StateDeps[MyStateModel])
app = agent.to_ag_ui(deps=StateDeps(MyStateModel()))
详见
references/backend-patterns.md#shared-state
。

3. Generative UI

3. 生成式UI

Agent emits state events that frontend renders:
  • StateSnapshotEvent
    - Replace entire state
  • StateDeltaEvent
    - JSON Patch operations
  • CustomEvent
    - Custom frontend triggers
See 
references/backend-patterns.md#generative-ui
.
智能体发送状态事件供前端渲染：
  • StateSnapshotEvent
    - 替换整个状态
  • StateDeltaEvent
    - JSON Patch 操作
  • CustomEvent
    - 自定义前端触发事件
详见
references/backend-patterns.md#generative-ui
。

4. Human in the Loop

4. 人机协作

Tools that wait for user confirmation via 
renderAndWaitForResponse
. See 
references/frontend-patterns.md#human-in-the-loop
.
通过
renderAndWaitForResponse
等待用户确认的工具。详见
references/frontend-patterns.md#human-in-the-loop
。

5. Predictive State Updates

5. 预测性状态更新

Stream partial state before tool completion. See 
references/backend-patterns.md#predictive-state
.
在工具完成前流式传输部分状态。详见
references/backend-patterns.md#predictive-state
。

Key Integration Points

关键集成点

Backend → Frontend Events

后端 → 前端事件

Tools return AG-UI events directly:
python
@agent.tool_plain
async def update_ui(data: str) -> StateSnapshotEvent:
    return StateSnapshotEvent(
        type=EventType.STATE_SNAPSHOT,
        snapshot={"field": data}
    )
工具直接返回AG-UI事件：
python
@agent.tool_plain
async def update_ui(data: str) -> StateSnapshotEvent:
    return StateSnapshotEvent(
        type=EventType.STATE_SNAPSHOT,
        snapshot={"field": data}
    )

Frontend → Backend State

前端 → 后端状态

Use 
useCoAgent
for bidirectional state:
tsx
const { state, setState } = useCoAgent({
  name: "myAgent",
  initialState: { /* ... */ }
});
使用
useCoAgent
实现双向状态同步：
tsx
const { state, setState } = useCoAgent({
  name: "myAgent",
  initialState: { /* ... */ }
});

Resources

资源

  • Backend patterns: 
    references/backend-patterns.md
    - Python/pydantic-ai implementation details
  • Frontend patterns: 
    references/frontend-patterns.md
    - React/CopilotKit implementation details
<!-- cross-ref:start -->
  • 后端模式文档：
    references/backend-patterns.md
    - Python/pydantic-ai实现细节
  • 前端模式文档：
    references/frontend-patterns.md
    - React/CopilotKit实现细节
<!-- cross-ref:start -->

See also (related skills — AG-UI family)

相关内容（AG-UI系列相关技能）

If your issue relates to:
  • AG-UI protocol with CopilotKit — check 
    ag-ui-copilotkit
    if appropriate.
<!-- cross-ref:end -->
如果你的问题涉及：
  • AG-UI protocol with CopilotKit — 请查看
    ag-ui-copilotkit
    （如适用）。
<!-- cross-ref:end -->