{
"canonical_name": "ag-ui-protocol/ag-ui",
"compilation_id": "pack_5f39f538174b431398669750057890e4",
"created_at": "2026-05-19T13:22:42.139771+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx create-ag-ui-app` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx create-ag-ui-app",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_67e62eaa6e91413faf7c5d2352246230"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_124e7bb94d7d127301e0b741ea290eff",
"canonical_name": "ag-ui-protocol/ag-ui",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/ag-ui-protocol/ag-ui",
"slug": "ag-ui",
"source_packet_id": "phit_f3941a951f4b425d84574482fa97e1ff",
"source_validation_id": "dval_42f281090908484ebb30ed913ed8a721"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 1217,
"github_stars": 13587,
"one_liner_en": "AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.",
"one_liner_zh": "AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.",
"primary_category": {
"category_id": "software-development",
"name_zh": "软件开发与交付",
"name_en": "Software Development",
"confidence": "high",
"reason": "semantic truth gate fallback rework"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "ag-ui",
"title_zh": "ag-ui 能力包",
"visible_tags": [
{
"type": "product_domain",
"label_zh": "生成式 UI",
"label_en": "Generative UI",
"tag_id": "product_domain-generative-ui",
"source": "semantic_truth_gate_rework"
},
{
"type": "user_job",
"label_zh": "Agent UI 协议",
"label_en": "Agent UI Protocol",
"tag_id": "user_job-agent-ui-protocol",
"source": "semantic_truth_gate_rework"
},
{
"type": "core_capability",
"label_zh": "前端集成",
"label_en": "Frontend Integration",
"tag_id": "core_capability-frontend-integration",
"source": "semantic_truth_gate_rework"
},
{
"type": "workflow_pattern",
"label_zh": "UI 状态同步",
"label_en": "UI State Sync",
"tag_id": "workflow_pattern-ui-state-sync",
"source": "semantic_truth_gate_rework"
},
{
"type": "selection_signal",
"label_zh": "协议边界",
"label_en": "Protocol Boundary",
"tag_id": "selection_signal-protocol-boundary",
"source": "semantic_truth_gate_rework"
}
]
},
"packet_id": "phit_f3941a951f4b425d84574482fa97e1ff",
"page_model": {
"artifacts": {
"artifact_slug": "ag-ui",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx create-ag-ui-app",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/ag-ui-protocol/ag-ui#readme",
"verified": true
}
],
"display_tags": [
"生成式 UI",
"Agent UI 协议",
"前端集成",
"UI 状态同步",
"协议边界"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Update Zod to ^4.0.0",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_864feb35f0a7491399ed9e6f32d716d0 | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Feature]: Update Zod to ^4.0.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Java dependencies not found",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_76cfe35c206349ceb926d2253bc2cf03 | https://github.com/ag-ui-protocol/ag-ui/issues/930 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Java dependencies not found",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_53c2f6a0605444afbd53e56d090a6295 | https://github.com/ag-ui-protocol/ag-ui/issues/1454 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "Developers should check this installation risk before relying on the project: [Feature]: Update Zod to ^4.0.0",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_334526f2cd6ed9dc89c052647aa8d0eb | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | [Feature]: Update Zod to ^4.0.0"
],
"severity": "medium",
"suggested_check": "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.",
"title": "失败模式：installation: [Feature]: Update Zod to ^4.0.0",
"user_impact": "Developers may fail before the first successful local run: [Feature]: Update Zod to ^4.0.0"
},
{
"body": "Developers should check this configuration risk before relying on the project: Java dependencies not found",
"category": "配置坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_cc82631789b14e6fa478fc47a467a6bd | https://github.com/ag-ui-protocol/ag-ui/issues/930 | Java dependencies not found"
],
"severity": "medium",
"suggested_check": "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.",
"title": "失败模式：configuration: Java dependencies not found",
"user_impact": "Developers may misconfigure credentials, environment, or host setup: Java dependencies not found"
},
{
"body": "Developers should check this configuration risk before relying on the project: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs",
"category": "配置坑",
"evidence": [
"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"
],
"severity": "medium",
"suggested_check": "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",
"title": "失败模式：configuration: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs",
"user_impact": "Developers may misconfigure credentials, environment, or host setup: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_6674fe14155d4baeb366f4ac441fd962 | https://github.com/ag-ui-protocol/ag-ui/issues/1719 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 13 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature]: Update Zod to ^4.0.0。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 106,
"forks": 1217,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 13587
},
"source_url": "https://github.com/ag-ui-protocol/ag-ui",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "面向 Agent 前端集成和生成式 UI 的协议能力包，重点是 UI 状态、事件协议、前端边界和交互接入。",
"title": "ag-ui 能力包",
"trial_prompt": "# ag-ui - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for ag-ui-protocol/ag-ui.\n\nProject:\n- Name: ag-ui\n- Repository: https://github.com/ag-ui-protocol/ag-ui\n- Summary: AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. intro: Introduction to AG-UI. Produce one small intermediate artifact and wait for confirmation.\n2. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. events: Event Specification. Produce one small intermediate artifact and wait for confirmation.\n4. types-messages: Types & Messages. Produce one small intermediate artifact and wait for confirmation.\n5. typescript-sdk: TypeScript SDK. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/ag-ui-protocol/ag-ui\n- https://github.com/ag-ui-protocol/ag-ui#readme\n- README.md\n- docs/introduction.mdx\n- docs/concepts/architecture.mdx\n- docs/ag_ui.md\n- docs/concepts/capabilities.mdx\n- sdks/typescript/packages/core/src/events.ts\n- sdks/typescript/packages/core/src/event-factories.ts\n- sdks/python/ag_ui/core/events.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agent（https://github.com/ag-ui-protocol/ag-ui/issues/1719）；github/github_issue: [Feature]: Update Zod to ^4.0.0（https://github.com/ag-ui-protocol/ag-ui/issues/1397）；github/github_issue: [Feature]: Update Zod to ^4.0.0（https://github.com/ag-ui-protocol/ag-ui/issues/1397）；github/github_issue: Java dependencies not found（https://github.com/ag-ui-protocol/ag-ui/issues/930）；github/github_issue: `RunAgentInput` should allow `null` for `threadId`/`runId` to support se（https://github.com/ag-ui-protocol/ag-ui/issues/1454）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agent",
"url": "https://github.com/ag-ui-protocol/ag-ui/issues/1719"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature]: Update Zod to ^4.0.0",
"url": "https://github.com/ag-ui-protocol/ag-ui/issues/1397"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Feature]: Update Zod to ^4.0.0",
"url": "https://github.com/ag-ui-protocol/ag-ui/issues/1397"
},
{
"kind": "github_issue",
"source": "github",
"title": "Java dependencies not found",
"url": "https://github.com/ag-ui-protocol/ag-ui/issues/930"
},
{
"kind": "github_issue",
"source": "github",
"title": "`RunAgentInput` should allow `null` for `threadId`/`runId` to support se",
"url": "https://github.com/ag-ui-protocol/ag-ui/issues/1454"
}
],
"status": "已收录 5 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "面向 Agent 前端集成和生成式 UI 的协议能力包，重点是 UI 状态、事件协议、前端边界和交互接入。",
"effort": "安装已验证",
"forks": 1217,
"icon": "code",
"name": "ag-ui 能力包",
"risk": "可发布",
"slug": "ag-ui",
"stars": 13587,
"tags": [
"生成式 UI",
"Agent UI 协议",
"前端集成",
"UI 状态同步",
"协议边界"
],
"thumb": "gray",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/ag-ui-protocol/ag-ui 项目说明书\n\n生成时间：2026-05-18 03:33:32 UTC\n\n## 目录\n\n- [Introduction to AG-UI](#intro)\n- [System Architecture](#architecture)\n- [The Agent Protocol Stack](#protocol-stack)\n- [Event Specification](#events)\n- [Types & Messages](#types-messages)\n- [Capabilities System](#capabilities)\n- [TypeScript SDK](#typescript-sdk)\n- [Python SDK](#python-sdk)\n- [Community SDKs](#community-sdks)\n- [LangGraph Integration](#langgraph-integration)\n\n\n\n## Introduction to AG-UI\n\n### 相关页面\n\n相关主题：[The Agent Protocol Stack](#protocol-stack), [Event Specification](#events)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n- [sdks/typescript/packages/cli/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/cli/README.md)\n- [sdks/community/ruby/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/ruby/README.md)\n- [sdks/community/dart/example/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/dart/example/README.md)\n- [sdks/community/c++/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/c++/README.md)\n- [integrations/adk-middleware/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/adk-middleware/python/README.md)\n- [integrations/langroid/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/README.md)\n- [integrations/pydantic-ai/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/pydantic-ai/typescript/README.md)\n- [integrations/ag2/python/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/ag2/python/examples/README.md)\n \n\n# Introduction to AG-UI\n\n**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.\n\n## Overview\n\nAG-UI provides a standardized way for agents to stream events to clients, supporting features like:\n\n- Real-time text message streaming\n- Tool execution and results rendering\n- State synchronization between agent and client\n- Run lifecycle management\n- Multi-step agentic workflows\n\n资料来源：[sdks/typescript/packages/core/README.md:1-5]()\n\n## Architecture\n\nAG-UI follows a client-server architecture where the agent backend streams events to the client using Server-Sent Events (SSE).\n\n```mermaid\ngraph TD\n A[Agent Backend] -->|SSE Events| B[AG-UI Protocol]\n B --> C[Client Applications]\n D[State Updates] <--> B\n E[Tool Calls] <--> B\n C -->|User Input| A\n```\n\n### Core Components\n\n| Component | Description |\n|-----------|-------------|\n| **Event Stream** | Server-Sent Events (SSE) for real-time streaming |\n| **State Management** | Bidirectional state synchronization |\n| **Tool System** | Agent tools exposed to clients and vice versa |\n| **Run Lifecycle** | Management of agent execution runs |\n\n资料来源：[sdks/typescript/packages/core/README.md:10-18]()\n\n## Event System\n\nThe AG-UI protocol defines 16 core event kinds covering the full agent interaction lifecycle.\n\n### Event Categories\n\n| Category | Events | Purpose |\n|----------|--------|---------|\n| **Messages** | `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END` | Stream text responses |\n| **Lifecycle** | `RUN_STARTED`, `RUN_FINISHED` | Track agent execution |\n| **State** | `STATE_SNAPSHOT`, `STATE_DELTA` | Synchronize application state |\n| **Tools** | `TOOL_CALL_START`, `TOOL_CALL_END`, `TOOL_CALL_RESULT` | Execute and display tool results |\n\n资料来源：[sdks/typescript/packages/core/README.md:14-15]()\n\n### Runtime Validation\n\nEvents are validated using schemas that catch malformed payloads early:\n\n```ts\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n资料来源：[sdks/typescript/packages/core/README.md:29-35]()\n\n## SDKs and Language Support\n\nAG-UI provides official and community SDKs for multiple programming languages:\n\n### Official SDKs\n\n| SDK | Language | Status | Purpose |\n|-----|----------|--------|---------|\n| `@ag-ui/core` | TypeScript | Official | Type definitions & runtime schemas |\n| `create-ag-ui-app` | TypeScript | Official | CLI scaffolding tool |\n\n### Community SDKs\n\n| SDK | Language | Package |\n|-----|----------|---------|\n| Ruby SDK | Ruby | Community maintained |\n| Dart SDK | Dart | Community maintained |\n| C++ SDK | C++ | Community maintained |\n| Java SDK | Java | Community maintained |\n| Kotlin SDK | Kotlin | Community maintained |\n| Go SDK | Go | Community maintained |\n\n资料来源：[sdks/typescript/packages/core/README.md:1-50]()\n\n资料来源：[sdks/community/c++/README.md:1-100]()\n\n资料来源：[sdks/community/java/packages/client/README.md:1-20]()\n\n## Tool Integration\n\nAG-UI supports bidirectional tool access where agents can call client-side tools and clients can execute server-side tools.\n\n```python\n# Example: Agent accessing client-side tools (ADK Middleware)\ntools=[\n AGUIToolset(tool_filter=lambda tool, readonly_context=None: tool.name.endswith('Goodbye'))\n]\n```\n\n资料来源：[integrations/adk-middleware/python/README.md:1-50]()\n\n### Tool Naming Convention\n\nTools can be filtered by naming patterns, allowing agents to selectively expose or access tools based on their suffixes or prefixes.\n\n资料来源：[integrations/adk-middleware/python/README.md:45-47]()\n\n## Framework Integrations\n\nAG-UI integrates with multiple AI agent frameworks:\n\n| Framework | Type | Documentation |\n|-----------|------|---------------|\n| **LangGraph** | Python | Scaffolding via CLI |\n| **CrewAI** | Python | Scaffolding via CLI |\n| **Mastra** | TypeScript | Scaffolding via CLI |\n| **Agno** | Python | Scaffolding via CLI |\n| **LlamaIndex** | Python | Scaffolding via CLI |\n| **Pydantic AI** | Python/TypeScript | Integration package |\n| **ADK (Google)** | Python/TypeScript | Middleware integration |\n| **Langroid** | Python/TypeScript | Full integration |\n| **Genkit** | Go | Community integration |\n| **AG2 (AutoGen)** | Python | Example integration |\n\n资料来源：[sdks/typescript/packages/cli/README.md:30-40]()\n\n资料来源：[integrations/langroid/README.md:1-30]()\n\n资料来源：[integrations/pydantic-ai/typescript/README.md:1-50]()\n\n## Getting Started\n\n### Quick Start with CLI\n\n```bash\nnpx create-ag-ui-app@latest\n```\n\nThe CLI provides an interactive setup wizard supporting:\n- CopilotKit/Next.js for web applications\n- CLI clients for terminal-based interactions\n- Automatic dependency installation and project structure setup\n\n资料来源：[sdks/typescript/packages/cli/README.md:1-40]()\n\n### Environment Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AG_UI_BASE_URL` | Base URL of the AG-UI server | `http://127.0.0.1:8000` |\n| `AG_UI_API_KEY` | API key for authentication | None |\n| `DEBUG` | Enable debug logging | `false` |\n\n资料来源：[sdks/community/dart/example/README.md:50-60]()\n\n## Protocol Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant AGUI as AG-UI Protocol\n participant Agent as Agent Backend\n \n Client->>Agent: Send user message\n Agent->>AGUI: Emit RUN_STARTED\n Agent->>AGUI: Emit TEXT_MESSAGE_START\n Agent->>AGUI: Emit TEXT_MESSAGE_CONTENT (streaming)\n Note over Agent,AGUI: Tool execution if needed\n Agent->>AGUI: Emit STATE_DELTA\n Agent->>AGUI: Emit TEXT_MESSAGE_END\n Agent->>AGUI: Emit RUN_FINISHED\n AGUI->>Client: Stream events via SSE\n```\n\n## Documentation Resources\n\n| Resource | Link |\n|----------|------|\n| Concepts & Architecture | [docs/concepts](https://docs.ag-ui.com/concepts/architecture) |\n| API Reference | [docs/events](https://docs.ag-ui.com/concepts/events) |\n| Ruby SDK Docs | `rake doc` in `sdks/community/ruby` |\n| Contributing Guide | [CONTRIBUTING.md](https://docs.ag-ui.com/development/contributing) |\n\n资料来源：[sdks/typescript/packages/core/README.md:40-45]()\n\n资料来源：[sdks/community/ruby/README.md:1-30]()\n\n## License\n\nAG-UI Protocol is licensed under the **MIT License** © 2025 AG-UI Protocol Contributors.\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Event Specification](#events), [TypeScript SDK](#typescript-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n- [sdks/typescript/packages/cli/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/cli/README.md)\n- [sdks/community/c++/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/c++/README.md)\n- [integrations/adk-middleware/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/adk-middleware/python/README.md)\n- [integrations/claude-agent-sdk/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/typescript/README.md)\n- [sdks/community/java/packages/client/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/client/README.md)\n- [sdks/community/java/packages/server/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/server/README.md)\n- [integrations/langroid/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/README.md)\n- [integrations/pydantic-ai/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/pydantic-ai/typescript/README.md)\n \n\n# System Architecture\n\nThe 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.\n\n## Overview\n\nAG-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.\n\n资料来源：[sdks/typescript/packages/core/README.md]()\n\n### Core Design Principles\n\nThe system architecture is built on several foundational principles that guide its implementation across all supported languages and frameworks:\n\n**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.\n\n**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.\n\n**Runtime Validation**: Schemas are implemented to catch malformed payloads early, ensuring data integrity throughout the communication pipeline.\n\n## High-Level Architecture\n\nThe AG-UI system consists of several interconnected layers that work together to provide a complete agent-user interaction framework.\n\n```mermaid\ngraph TD\n subgraph Client[\"Client Layer\"]\n FE[Frontend Client]\n Tools[Client Tools]\n State[State Management]\n end\n \n subgraph Protocol[\"Protocol Layer\"]\n Events[Event Schemas]\n Types[Type Definitions]\n Validation[Runtime Validation]\n end\n \n subgraph Agent[\"Agent Layer\"]\n LLM[LLM Agent]\n ServerTools[Server Tools]\n SubAgents[Sub-Agents]\n end\n \n subgraph Transport[\"Transport Layer\"]\n HTTP[HTTP/WebSocket]\n SSE[Server-Sent Events]\n end\n \n FE --> Protocol\n Tools --> Protocol\n Protocol --> Transport\n Transport --> Agent\n ServerTools --> LLM\n SubAgents --> LLM\n State <--> Agent\n```\n\n资料来源：[sdks/typescript/packages/core/README.md]()\n\n## Core Components\n\n### Protocol Layer\n\nThe protocol layer forms the backbone of the AG-UI system, providing the type definitions and event schemas that all other components depend upon.\n\n#### Event Schemas\n\nThe `@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.\n\n资料来源：[sdks/typescript/packages/core/README.md]()\n\n| Event Category | Description | Key Events |\n|----------------|-------------|------------|\n| Message Events | Text and content streaming | TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END |\n| Tool Events | Tool invocation and results | TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END |\n| State Events | State synchronization | STATE_UPDATE, STATE_SNAPSHOT |\n| Lifecycle Events | Run management | RUN_STARTED, RUN_FINISHED, MESSAGES_SNAPSHOT |\n\n#### Event Validation\n\nRuntime validation is provided through schema parsing, allowing incoming events to be validated against their expected structure:\n\n```typescript\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n### Agent Layer\n\nThe agent layer encompasses the server-side implementations that process user requests and generate responses.\n\n#### TypeScript Agent Implementation\n\nThe 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.\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md]()\n\n#### Python Agent Integration\n\nPython-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.\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n\n#### Java Agent Components\n\nThe Java SDK provides both client and server implementations:\n\n- **AbstractAgent**: Base class for agent implementations\n- **LocalAgent**: Concrete implementation for local agent execution\n\n资料来源：[sdks/community/java/packages/server/README.md]()\n\n### Client Layer\n\nThe client layer handles frontend interactions, tool exposure, and state management.\n\n#### Client Tools\n\nClients can expose tools to agents through a toolset mechanism. Tools are filtered and exposed based on configuration, allowing selective tool availability:\n\n```python\nAGUIToolset(tool_filter=lambda tool, readonly_context=None: tool.name.endswith('Goodbye'))\n```\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n\n#### State Management\n\nState synchronization between client and server enables collaborative workflows. The bidirectional state sync mechanism ensures that both frontend and backend maintain consistent state views.\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md]()\n\n## SDK Architecture by Language\n\n### TypeScript SDK\n\nThe TypeScript SDK is organized into multiple packages that can be used independently or together:\n\n```mermaid\ngraph LR\n subgraph TypeScript_SDK[\"TypeScript SDK\"]\n Core[\"@ag-ui/core\"] --> CLI[\"@ag-ui/cli\"]\n Core --> Client[\"Client Libraries\"]\n Core --> Server[\"Server Libraries\"]\n CLI --> Integrations[\"Framework Integrations\"]\n end\n```\n\n| Package | Purpose |\n|---------|---------|\n| @ag-ui/core | Type definitions and event schemas |\n| @ag-ui/cli | Command-line tools for development |\n| @ag-ui/client | Client-side event handling |\n| @ag-ui/server | Server-side agent implementation |\n\n资料来源：[sdks/typescript/packages/core/README.md]()\n资料来源：[sdks/typescript/packages/cli/README.md]()\n\n### Python SDK\n\nThe Python ecosystem supports multiple agent frameworks through middleware adapters:\n\n| Integration | Framework | Features |\n|-------------|-----------|----------|\n| ADK Middleware | Google ADK | Tool support, state sync |\n| Pydantic AI | Pydantic AI | Agentic chat, backend tools |\n| Langroid | Langroid | Multi-agent orchestration |\n| AG2 | AutoGen | Agent collaboration |\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n资料来源：[integrations/pydantic-ai/typescript/README.md]()\n\n### Multi-Language Support\n\nThe AG-UI protocol maintains consistent implementations across multiple programming languages, each following the same architectural patterns:\n\n| Language | Client | Server | Status |\n|----------|--------|--------|--------|\n| TypeScript | ✅ | ✅ | Primary |\n| Python | ✅ | ✅ | Primary |\n| Java | ✅ | ✅ | Community |\n| Ruby | ✅ | - | Community |\n| Dart | ✅ | - | Community |\n| C++ | ✅ | - | Community |\n| Go | - | ✅ | Community |\n\n资料来源：[sdks/community/java/packages/client/README.md]()\n资料来源：[sdks/community/c++/README.md]()\n\n## Communication Flow\n\n### Event Streaming Model\n\nThe 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.\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Protocol\n participant Agent\n participant LLM\n \n Client->>Agent: POST /agent/run (RunAgentInput)\n Agent->>LLM: Query LLM\n LLM-->>Agent: Streaming Response\n Agent->>Protocol: Emit Events\n Protocol->>Client: Stream Events\n \n Note over Client,LLM: Real-time event emission during inference\n```\n\n### Tool Call Flow\n\nTool invocations follow a specific sequence that enables both server-side and client-side tool execution:\n\n```mermaid\ngraph TD\n Start[LLM Requests Tool] --> Filter{Check Tool Type}\n Filter -->|Server Tool| ServerExec[Execute Server Tool]\n Filter -->|Client Tool| ClientExec[Execute Client Tool]\n \n ServerExec --> ServerResult[Return Result]\n ClientExec --> Pause[Pause Stream]\n Pause --> Execute[Client Executes Tool]\n Execute --> Resume[Resume Stream]\n Resume --> FinalResult[Final Response]\n \n ServerResult --> FinalResult\n```\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md]()\n\n### State Synchronization\n\nState management in AG-UI supports bidirectional synchronization between client and server:\n\n```mermaid\ngraph LR\n subgraph Client_State\n CS1[State View]\n CS2[State Mutation]\n end\n \n subgraph Server_State\n SS1[Canonical State]\n SS2[State Processing]\n end\n \n CS1 <-->|STATE_UPDATE| SS1\n CS2 -->|Mutation Event| SS2\n SS2 -->|State Confirmation| CS1\n```\n\n## Framework Integrations\n\n### Claude Agent SDK Integration\n\nThe Claude Agent SDK adapter provides comprehensive AG-UI protocol support for Anthropic Claude models:\n\n```typescript\nimport { ClaudeAgentAdapter } from \"@ag-ui/claude-agent-sdk\";\n\nconst adapter = new ClaudeAgentAdapter({\n agentId: \"my_agent\",\n model: \"claude-haiku-4-5\",\n systemPrompt: \"You are helpful\",\n});\n\nconst events$ = adapter.run(input);\n```\n\nKey features include full lifecycle management, interrupt support, dynamic frontend tool exposure, streaming tool arguments, and automatic event cleanup.\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md]()\n\n### ADK Middleware\n\nThe ADK middleware integrates Google Agent Development Kit with AG-UI, providing:\n\n- **271 comprehensive tests** covering all protocol features\n- Tool support with automatic exposure to frontend clients\n- State synchronization between frontend and backend\n- Sub-agent orchestration capabilities\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n\n### Langroid Integration\n\nLangroid provides a multi-agent orchestration system with AG-UI support:\n\n```mermaid\ngraph TD\n subgraph Langroid_System\n Orchestrator[Orchestrator Agent]\n Sub1[Specialist Agent 1]\n Sub2[Specialist Agent 2]\n Tools[Tool Registry]\n end\n \n Orchestrator --> Sub1\n Orchestrator --> Sub2\n Sub1 --> Tools\n Sub2 --> Tools\n```\n\nThe integration includes both Python server implementations and TypeScript client libraries for frontend communication.\n\n资料来源：[integrations/langroid/README.md]()\n\n## Development Tools\n\n### CLI Tools\n\nThe AG-UI CLI provides development utilities for creating and managing AG-UI applications:\n\n```bash\nnpx create-ag-ui-app@latest --help\n```\n\n资料来源：[sdks/typescript/packages/cli/README.md]()\n\n### Testing Infrastructure\n\nComprehensive testing is available across all SDK implementations. For example, the ADK Middleware includes 271 tests that verify protocol compliance and feature functionality:\n\n```bash\n# Run tests with coverage\npytest --cov=src/adk_middleware\n```\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n\n## Architecture Patterns\n\n### Builder Pattern for Agents\n\nMany SDK implementations use the builder pattern for agent configuration:\n\n```cpp\n#include \"agent/http_agent.h\"\n\nauto agent = HttpAgent::builder()\n .withUrl(\"http://localhost:8080/api/agent/run\")\n .withAgentId(AgentId(\"my-agent\"))\n .build();\n```\n\nThis pattern provides a fluent interface for configuring agent properties while maintaining immutability of the final agent instance.\n\n资料来源：[sdks/community/c++/README.md]()\n\n### Observable Pattern for Events\n\nThe TypeScript SDK and integrations use RxJS Observables for event streaming, allowing clients to subscribe to event streams with familiar patterns:\n\n```typescript\nevents$.subscribe({\n next: (event) => sendEvent(event),\n complete: () => res.end(),\n});\n```\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md]()\n\n## Security Considerations\n\n### API Key Management\n\nThe protocol supports API key authentication for securing agent endpoints:\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| AG_UI_BASE_URL | Base URL of the AG-UI server | http://127.0.0.1:8000 |\n| AG_UI_API_KEY | API key for authentication | None |\n| DEBUG | Enable debug logging | false |\n\n资料来源：[sdks/community/dart/example/README.md]()\n\n### Tool Exposure Control\n\nTools can be selectively exposed to agents using filter functions, preventing unauthorized access to sensitive client-side capabilities:\n\n```python\nAGUIToolset(tool_filter=lambda tool, readonly_context=None: tool.name.endswith('Goodbye'))\n```\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n\n## Summary\n\nThe AG-UI Protocol architecture provides a robust, framework-agnostic foundation for building agent-user interaction systems. Its key architectural elements include:\n\n- **Event-driven communication** with 16 core event kinds for comprehensive state management\n- **Multi-language SDK support** spanning TypeScript, Python, Java, Ruby, Dart, C++, and Go\n- **Framework integrations** for ADK, Pydantic AI, Langroid, Claude Agent SDK, and AG2\n- **Runtime validation** ensuring data integrity across the communication pipeline\n- **Flexible tool exposure** mechanisms for controlled tool access\n- **Bidirectional state synchronization** enabling collaborative workflows\n\nThe architecture's modular design allows developers to use individual components independently or together, providing maximum flexibility for different use cases and technical requirements.\n\n---\n\n\n\n## The Agent Protocol Stack\n\n### 相关页面\n\n相关主题：[Introduction to AG-UI](#intro), [Event Specification](#events)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n- [integrations/claude-agent-sdk/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/typescript/README.md)\n- [integrations/claude-agent-sdk/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/python/README.md)\n- [sdks/community/genkit/go/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/community/genkit/go/examples/README.md)\n- [integrations/server-starter-all-features/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/server-starter-all-features/typescript/README.md)\n- [sdks/community/java/packages/server/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/server/README.md)\n- [sdks/community/java/packages/client/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/client/README.md)\n \n\n# The Agent Protocol Stack\n\nThe 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.\n\n## Overview\n\nThe AG-UI Protocol defines how agents communicate with frontend applications through a streaming event-based mechanism. The protocol stack encompasses:\n\n| Layer | Description |\n|-------|-------------|\n| **Core Definitions** | TypeScript definitions and runtime schemas for all protocol types |\n| **Event System** | 16+ core event kinds for streaming interactions |\n| **SDK Implementations** | Language-specific SDKs (TypeScript, Python, Ruby, Go, Java, Kotlin, Dart) |\n| **Framework Adapters** | Integrations with agent frameworks (Claude, Langroid, ADK, Pydantic AI, etc.) |\n| **Reference Implementations** | Server starters demonstrating protocol features |\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n## Architecture\n\nThe protocol stack follows a layered architecture where each layer builds upon the previous one:\n\n```mermaid\ngraph TD\n A[Frontend Application] <-->|Streaming Events| B[Protocol Layer]\n B <-->|Event Translation| C[Framework Adapter]\n C <-->|Agent SDK Calls| D[Agent Runtime]\n \n E[Core Schemas] --> B\n F[Type Definitions] --> E\n \n G[TypeScript SDK] --> F\n H[Python SDK] --> F\n I[Go SDK] --> F\n J[Ruby SDK] --> F\n K[Java SDK] --> F\n L[Dart SDK] --> F\n \n M[Claude Adapter] --> C\n N[Langroid Adapter] --> C\n O[ADK Adapter] --> C\n P[Pydantic AI Adapter] --> C\n```\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/typescript/README.md)\n\n## Core Event System\n\nThe event system is the foundation of the protocol, enabling real-time streaming communication between agents and frontends.\n\n### Event Categories\n\n| Category | Events | Purpose |\n|----------|--------|---------|\n| **Message Lifecycle** | `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END` | Stream text responses |\n| **Tool Execution** | `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END` | Backend tool invocation |\n| **State Management** | `STATE_UPDATE`, `STATE_SNAPSHOT` | Synchronize shared state |\n| **Run Lifecycle** | `RUN_STARTED`, `RUN_FINISHED` | Track agent execution |\n| **UI Generation** | `VIEW_UPDATE`, `COMPONENT_DEFINITION` | Generate dynamic UIs |\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n### Event Flow Example\n\n```mermaid\nsequenceDiagram\n participant User\n participant Frontend\n participant Protocol\n participant Agent\n \n User->>Frontend: Send message\n Frontend->>Protocol: HTTP POST /agent/chat\n Protocol->>Agent: Forward request\n Agent->>Protocol: Emit TEXT_MESSAGE_START\n Agent->>Protocol: Emit TEXT_MESSAGE_CONTENT (streaming)\n Agent->>Protocol: Emit TOOL_CALL_START\n Agent->>Protocol: Emit TOOL_CALL_ARGS\n Agent->>Protocol: Emit TOOL_CALL_END\n Agent->>Protocol: Emit TEXT_MESSAGE_END\n Protocol->>Frontend: SSE Stream\n Frontend->>User: Render updates\n```\n\n资料来源：[integrations/server-starter-all-features/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/server-starter-all-features/typescript/README.md)\n\n## Language SDKs\n\nThe protocol is implemented across multiple programming languages, each providing native bindings for the event system.\n\n### Available SDKs\n\n| Language | Package | Status | Key Features |\n|----------|---------|--------|--------------|\n| TypeScript | `@ag-ui/core` | Stable | Full event definitions, runtime validation |\n| Python | `ag-ui` | Stable | FastAPI integration, async support |\n| Ruby | `ag-ui` | Community | Simple usage example |\n| Go | `ag-ui-go` | Community | Genkit integration |\n| Java | `com.ag-ui.community` | Community | Server and Client packages |\n| Kotlin | `ag-ui-kotlin` | Community | JVM compatibility |\n| Dart | `ag_ui` | Community | Flutter-ready |\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n### TypeScript Core SDK\n\nThe TypeScript SDK provides the foundational definitions used by all other SDKs:\n\n```typescript\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n**Features:**\n- Strongly-typed data models (Message, Tool, Context, State)\n- Runtime validation using JSON schemas\n- Framework-agnostic (Node.js, browsers, any JS runtime)\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n## Framework Adapters\n\nFramework adapters translate between agent frameworks and the AG-UI protocol, enabling plug-and-play integration.\n\n### Supported Integrations\n\n| Framework | Language | Features Supported |\n|-----------|----------|-------------------|\n| Claude Agent SDK | TypeScript, Python | Tool calling, state sync, interrupts |\n| Langroid | Python, TypeScript | Agentic chat, backend tools, shared state |\n| ADK (Agent Development Kit) | Python, TypeScript | All 7 features |\n| Pydantic AI | Python, TypeScript | Agentic chat, frontend tools |\n| Microsoft Agent Framework | Python | All 7 features |\n| AG2 (AutoGen) | Python | Agentic chat, backend tools |\n| Agent Spec | Python | All 4 dojo features |\n\n资料来源：[integrations/claude-agent-sdk/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/python/README.md)\n\n### Claude Agent SDK Adapter\n\nThe Claude adapter provides comprehensive lifecycle management:\n\n```typescript\nimport { ClaudeAgentAdapter } from \"@ag-ui/claude-agent-sdk\";\n\nconst adapter = new ClaudeAgentAdapter({\n agentId: \"my_agent\",\n model: \"claude-haiku-4-5\",\n systemPrompt: \"You are helpful\",\n});\n\nconst events$ = adapter.run(input);\nevents$.subscribe({\n next: (event) => sendEvent(event),\n complete: () => res.end(),\n});\n```\n\n**Key Capabilities:**\n- Full lifecycle management (message extraction, option building, SDK querying)\n- Interrupt support via `adapter.interrupt()`\n- Dynamic frontend tools via MCP server\n- Frontend tool halting for human-in-the-loop\n- Streaming tool arguments\n- Bidirectional state synchronization\n- Context injection into prompts\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/typescript/README.md)\n\n### Go Genkit Integration\n\nThe Go integration demonstrates server implementation using Genkit:\n\n```go\ntype MyAgent struct{}\n\nfunc (a *MyAgent) Run(ctx context.Context, input agents.RunAgentInput, eventsCh chan<- events.Event) error {\n // Emit TEXT_MESSAGE_START\n messageID := \"msg-1\"\n eventsCh <- events.NewTextMessageStartEvent(messageID, events.WithRole(\"assistant\"))\n \n // Emit content chunks\n eventsCh <- events.NewTextMessageContentEvent(messageID, \"Hello from my agent!\")\n \n // Emit TEXT_MESSAGE_END\n eventsCh <- events.NewTextMessageEndEvent(messageID)\n \n return nil\n}\n```\n\n资料来源：[sdks/community/genkit/go/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/community/genkit/go/examples/README.md)\n\n## Protocol Features\n\nThe AG-UI Protocol implements seven core features enabling rich agent-user interactions.\n\n### Feature Matrix\n\n| Feature | Description | Events Used |\n|---------|-------------|-------------|\n| **Agentic Chat** | Basic conversational interaction | TEXT_MESSAGE_*, TOOL_CALL_* |\n| **Backend Tool Rendering** | Server-executed tool calls with UI display | TOOL_CALL_*, VIEW_UPDATE |\n| **Human in the Loop** | User approval workflows | TOOL_CALL_START (pause), USER_APPROVAL |\n| **Agentic Generative UI** | Dynamic step-by-step task progress | STATE_UPDATE, VIEW_UPDATE |\n| **Tool-based Generative UI** | Custom UI components from tools | COMPONENT_DEFINITION |\n| **Shared State** | Bidirectional state synchronization | STATE_UPDATE, STATE_SNAPSHOT |\n| **Predictive State Updates** | Optimistic UI updates during tools | STATE_UPDATE (optimistic) |\n\n资料来源：[integrations/server-starter-all-features/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/server-starter-all-features/typescript/README.md)\n\n### State Management\n\nThe protocol supports bidirectional state synchronization between agents and frontends:\n\n```mermaid\ngraph LR\n A[Agent Runtime] <-->|STATE_UPDATE| B[Protocol Layer]\n B <-->|STATE_SNAPSHOT| C[Frontend State]\n \n D[User Action] -->|Update| C\n C -->|Sync| B\n B -->|Inject Context| A\n```\n\nState updates flow both directions, enabling:\n- Agents to update UI state\n- Frontends to modify agent context\n- Optimistic updates during long-running operations\n\n资料来源：[integrations/claude-agent-sdk/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/python/README.md)\n\n## Data Models\n\n### Core Types\n\n| Model | Fields | Purpose |\n|-------|--------|---------|\n| `Message` | id, role, content, toolCalls | Chat messages |\n| `Tool` | name, description, parameters | Tool definitions |\n| `Context` | variables, metadata | Execution context |\n| `State` | data, version | Application state |\n| `RunAgentInput` | messages, context, tools, state | Agent input |\n| `Event` | type, payload, timestamp | Streaming events |\n\n### Event Schema Example\n\n```typescript\ninterface TextMessageContentEvent {\n type: \"TEXT_MESSAGE_CONTENT\";\n messageId: string;\n delta: string;\n index?: number;\n}\n```\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n## Client-Server Architecture\n\nThe protocol follows a client-server model with the server implementing the agent logic.\n\n### Java SDK Architecture\n\n```mermaid\nclassDiagram\n class LocalAgent {\n +Run(input, events)\n }\n class AbstractAgent {\n +Name() string\n +Description() string\n +Run(ctx, input, events)\n }\n \n LocalAgent --|> AbstractAgent\n```\n\n**Server Package (`java-server`):**\n- Contains `LocalAgent` abstract implementation\n- Handles event emission and stream management\n\n**Client Package (`java-client`):**\n- Contains `AbstractAgent` base class\n- Defines agent interface contracts\n\n资料来源：[sdks/community/java/packages/server/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/server/README.md)\n\n### Dependency Configuration\n\nFor Java projects:\n\n```xml\n\n com.ag-ui.community\n java-server\n 0.0.1\n\n```\n\n```xml\n\n com.ag-ui.community\n java-client\n 0.0.1\n\n```\n\n资料来源：[sdks/community/java/packages/server/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/server/README.md)\n\n## Quick Start\n\n### TypeScript\n\n```bash\nnpm install @ag-ui/core\n```\n\n```typescript\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n### Python\n\n```bash\npip install ag-ui\n```\n\n```python\nfrom ag_ui import ClaudeAgentAdapter, add_claude_fastapi_endpoint\n\nadapter = ClaudeAgentAdapter(name=\"my_agent\", options={\"model\": \"claude-haiku-4-5\"})\nadd_claude_fastapi_endpoint(app=app, adapter=adapter, path=\"/my_agent\")\n```\n\n### Go\n\n```go\npackage main\n\nimport (\n \"github.com/ag-ui-protocol/ag-ui/sdks/community/genkit/go/examples/internal/agents\"\n \"github.com/ag-ui-protocol/ag-ui/sdks/community/go/pkg/core/events\"\n)\n\ntype MyAgent struct{}\n\nfunc (a *MyAgent) Run(ctx context.Context, input agents.RunAgentInput, eventsCh chan<- events.Event) error {\n // Implementation\n return nil\n}\n```\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n## See Also\n\n- [AG-UI Protocol Documentation](https://docs.ag-ui.com/introduction)\n- [Concepts & Architecture](https://docs.ag-ui.com/concepts/architecture)\n- [Events Reference](https://docs.ag-ui.com/concepts/events)\n- [Contributing Guide](https://github.com/ag-ui-protocol/ag-ui/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## Event Specification\n\n### 相关页面\n\n相关主题：[Types & Messages](#types-messages), [Capabilities System](#capabilities), [TypeScript SDK](#typescript-sdk)\n\n\nRelated Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java)\n- [sdks/community/java/packages/core/src/main/java/com/agui/core/event/StateDeltaEvent.java](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/core/src/main/java/com/agui/core/event/StateDeltaEvent.java)\n- [sdks/community/java/packages/core/src/main/java/com/agui/core/event/RunErrorEvent.java](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/core/src/main/java/com/agui/core/event/RunErrorEvent.java)\n- [sdks/community/java/packages/core/src/main/java/com/agui/core/event/RawEvent.java](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/core/src/main/java/com/agui/core/event/RawEvent.java)\n- [integrations/community/genkit/go/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/community/genkit/go/README.md)\n \n\n# Event Specification\n\nThe 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.\n\n## Overview\n\nAG-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.\n\nThe event system is designed around three core principles:\n\n1. **Typed Events** – Every event has a well-defined `type` string identifier that clients use to route handling logic.\n2. **Streaming-First** – Events are emitted incrementally, allowing clients to render partial results (e.g., streaming text) in real-time.\n3. **Stateless Payloads** – Events carry all necessary context; clients are responsible for aggregating state across event sequences.\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java:1-80]()\n\n## Event Type Categories\n\nThe AG-UI Protocol defines six logical categories of events. Each category addresses a distinct aspect of agent-client interaction.\n\n```mermaid\ngraph TD\n A[AG-UI Events] --> B[Text Messages]\n A --> C[Thinking Messages]\n A --> D[Tool Calls]\n A --> E[Thinking Process]\n A --> F[State Management]\n A --> G[Execution Lifecycle]\n \n B --> B1[TEXT_MESSAGE_START]\n B --> B2[TEXT_MESSAGE_CONTENT]\n B --> B3[TEXT_MESSAGE_END]\n B --> B4[TEXT_MESSAGE_CHUNK]\n \n D --> D1[TOOL_CALL_START]\n D --> D2[TOOL_CALL_ARGS]\n D --> D3[TOOL_CALL_RESULT]\n D --> D4[TOOL_CALL_END]\n \n E --> E1[THINKING_MESSAGE_START]\n E --> E2[THINKING_MESSAGE_CONTENT]\n E --> E3[THINKING_MESSAGE_END]\n \n F --> F1[STATE_DELTA]\n F --> F2[STATE_SNAPSHOT]\n \n G --> G1[RUN_STARTED]\n G --> G2[RUN_FINISHED]\n G --> G3[RUN_ERROR]\n```\n\n### Text Message Events\n\nText message events handle streaming textual output from the agent. These events support both incremental content delivery and complete message reconstruction on the client side.\n\n| Event Type | Purpose |\n|------------|---------|\n| `TEXT_MESSAGE_START` | Signals the beginning of a new text message stream, includes `messageId` and metadata |\n| `TEXT_MESSAGE_CONTENT` | Carries incremental text delta content |\n| `TEXT_MESSAGE_CHUNK` | Alternative chunk format for raw text segments |\n| `TEXT_MESSAGE_END` | Signals completion of the text message stream |\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java:27-36]()\n\n### Tool Call Events\n\nTool 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.\n\n| Event Type | Purpose |\n|------------|---------|\n| `TOOL_CALL_START` | Indicates initiation of a tool call with tool name and call ID |\n| `TOOL_CALL_ARGS` | Streams tool arguments as JSON chunks arrive |\n| `TOOL_CALL_RESULT` | Delivers the tool execution result back to the agent |\n| `TOOL_CALL_END` | Signals completion of the tool call sequence |\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java](integrations/community/genkit/go/README.md)\n\n### State Management Events\n\nState events provide two complementary mechanisms for client-side state synchronization.\n\n| Event Type | Purpose |\n|------------|---------|\n| `STATE_DELTA` | Represents incremental changes to application state |\n| `STATE_SNAPSHOT` | Provides a complete state snapshot for initial synchronization |\n\nThe `StateDeltaEvent` class encapsulates state changes without carrying the full application state:\n\n```java\npublic class StateDeltaEvent extends BaseEvent {\n public StateDeltaEvent() {\n super(EventType.STATE_DELTA);\n }\n}\n```\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/event/StateDeltaEvent.java:1-40]()\n\n### Execution Lifecycle Events\n\nLifecycle events mark significant milestones in the run execution pipeline.\n\n| Event Type | Purpose |\n|------------|---------|\n| `RUN_STARTED` | Signals that a new agent run has begun |\n| `RUN_FINISHED` | Indicates successful completion of the run |\n| `RUN_ERROR` | Reports an error that occurred during execution |\n\nThe `RunErrorEvent` captures error information for client-side error handling:\n\n```java\npublic class RunErrorEvent extends BaseEvent {\n private String error;\n \n public RunErrorEvent() {\n super(EventType.RUN_ERROR);\n }\n \n public void setError(final String error) {\n this.error = error;\n }\n \n public String getError() {\n return this.error;\n }\n}\n```\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/event/RunErrorEvent.java:1-55]()\n\n### Raw Events\n\nFor extensibility and backward compatibility, the protocol includes a generic `RAW` event type that can carry arbitrary event data:\n\n```java\npublic class RawEvent extends BaseEvent {\n public RawEvent() {\n super(EventType.RAW);\n }\n}\n```\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/event/RawEvent.java:1-35]()\n\n## Event Schema Structure\n\nEvery AG-UI event inherits from a common `BaseEvent` that provides standard fields required for all event types.\n\n### Base Event Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `type` | `string` | The event type identifier (e.g., `TEXT_MESSAGE_START`) |\n| `timestamp` | `number` | Unix timestamp when the event was generated |\n| `messageId` | `string` | Unique identifier for message grouping (when applicable) |\n| `runId` | `string` | Identifier of the current run execution (when applicable) |\n| `threadId` | `string` | Identifier of the conversation thread (when applicable) |\n| `rawEvent` | `object` | Raw event payload data |\n\n### Event Payload Examples\n\n**Text Message Content Event:**\n```json\n{\n \"type\": \"TEXT_MESSAGE_CONTENT\",\n \"messageId\": \"msg_abc123\",\n \"runId\": \"run_xyz789\",\n \"threadId\": \"thread_main\",\n \"delta\": \"Hello, how can I assist\",\n \"timestamp\": 1704067200000\n}\n```\n\n**Tool Call Start Event:**\n```json\n{\n \"type\": \"TOOL_CALL_START\",\n \"toolCallId\": \"tool_123\",\n \"toolName\": \"get_weather\",\n \"timestamp\": 1704067200500\n}\n```\n\n**State Delta Event:**\n```json\n{\n \"type\": \"STATE_DELTA\",\n \"state\": {\n \"weather\": {\n \"city\": \"San Francisco\",\n \"temperature\": 18\n }\n },\n \"timestamp\": 1704067201000\n}\n```\n\n## Event Flow Architecture\n\nThe following diagram illustrates the typical event flow in an AG-UI enabled application:\n\n```mermaid\nsequenceDiagram\n participant FE as Frontend Client\n participant AG as AG-UI Gateway\n participant AR as Agent Runtime\n \n FE->>AG: POST /run (RunAgentInput)\n AG->>AR: Invoke agent with input\n AR->>AG: Emit TEXT_MESSAGE_START\n AG->>FE: SSE stream: TEXT_MESSAGE_START\n loop Streaming Content\n AR->>AG: Emit TEXT_MESSAGE_CONTENT\n AG->>FE: SSE stream: TEXT_MESSAGE_CONTENT\n end\n AR->>AG: Emit TOOL_CALL_START\n AG->>FE: SSE stream: TOOL_CALL_START\n Note over FE: Execute tool locally\n FE->>AG: Submit TOOL_CALL_RESULT\n AR->>AG: Emit RUN_FINISHED\n AG->>FE: SSE stream: RUN_FINISHED\n```\n\n## Genkit Integration Example\n\nThe Genkit integration demonstrates how event types map to framework-specific content:\n\n| Genkit Content | AG-UI Event |\n|----------------|-------------|\n| Text content (first chunk) | `TEXT_MESSAGE_START` + `TEXT_MESSAGE_CHUNK` |\n| Text content (subsequent) | `TEXT_MESSAGE_CHUNK` |\n| Tool request | `TOOL_CALL_START` + `TOOL_CALL_ARGS` |\n| Tool response | `TOOL_CALL_RESULT` |\n\n资料来源：[integrations/community/genkit/go/README.md](integrations/community/genkit/go/README.md)\n\n```go\n// Event type handling in Genkit adapter\nswitch event.Type {\ncase events.EventTypeTextMessageStart:\n // Handle text message start\ncase events.EventTypeTextMessageChunk:\n // Handle text chunk\ncase events.EventTypeToolCallStart:\n // Handle tool call start\ncase events.EventTypeToolCallArgs:\n // Handle tool call arguments\ncase events.EventTypeToolCallResult:\n // Handle tool call result\n}\n```\n\n## Best Practices\n\n### Event Ordering\n\nEvents must be emitted in a deterministic order to ensure consistent client behavior:\n\n1. `RUN_STARTED` – Always first\n2. `STATE_SNAPSHOT` – If initial state is needed\n3. Message-related events (`TEXT_MESSAGE_START`, content, end)\n4. Tool call events (`TOOL_CALL_START`, args, result, end)\n5. State updates (`STATE_DELTA`)\n6. `RUN_FINISHED` or `RUN_ERROR` – Always last\n\n### Error Handling\n\nWhen errors occur during event streaming:\n\n- Emit `RUN_ERROR` with descriptive error message\n- Include error context in the event payload\n- Do not emit `RUN_FINISHED` after an error\n\n### Idempotency\n\nClients should handle duplicate events gracefully by using `messageId` and `runId` for deduplication when reconnecting or retrying requests.\n\n## Summary\n\nThe 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:\n\n- Real-time streaming of text and tool content\n- Synchronized state management across client and server\n- Structured error handling and recovery\n- Framework-agnostic integrations through consistent event contracts\n\nAll event types are defined as enumerations in the core SDK packages and extend a common `BaseEvent` class to ensure type safety and runtime validation.\n\n---\n\n\n\n## Types & Messages\n\n### 相关页面\n\n相关主题：[Event Specification](#events), [Capabilities System](#capabilities)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/src/types.ts](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/src/types.ts)\n- [sdks/typescript/packages/proto/src/generated/types.ts](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/proto/src/generated/types.ts)\n- [sdks/python/ag_ui/core/types.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/core/types.py)\n- [docs/concepts/messages.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/concepts/messages.mdx)\n- [docs/concepts/serialization.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/concepts/serialization.mdx)\n- [sdks/typescript/packages/core/src/events.ts](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/src/events.ts)\n \n\n# Types & Messages\n\n## Overview\n\nThe 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.\n\n**Core responsibilities of the Types & Messages system:**\n\n- Define strongly-typed data models for messages, tools, context, and state\n- Provide runtime validation through schema-based parsing\n- Support streaming events for real-time agent communication\n- Enable framework-agnostic implementation across TypeScript, Python, and other languages\n\n资料来源：[sdks/typescript/packages/core/README.md:1-15]()\n\n## Type System Architecture\n\n```mermaid\ngraph TD\n A[AG-UI Types] --> B[Core Data Models]\n A --> C[Event Types]\n A --> D[Streaming Events]\n \n B --> B1[Message]\n B --> B2[Tool]\n B --> B3[Context]\n B --> B4[State]\n B --> B5[RunAgentInput]\n \n C --> C1[TextMessage Events]\n C --> C2[Thinking Events]\n C --> C3[Tool Call Events]\n C --> C4[State Update Events]\n C --> C5[Lifecycle Events]\n \n D --> D1[Server-Sent Events]\n D --> D2[JSON Payloads]\n D --> D3[Binary/Proto]\n```\n\n## Core Data Models\n\n### Message Types\n\nMessages represent the fundamental unit of communication in the AG-UI protocol. They are strongly typed and support various content types.\n\n资料来源：[sdks/typescript/packages/core/src/types.ts:1-50]()\n\n#### Message Structure\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `id` | `string` | Yes | Unique identifier for the message |\n| `role` | `MessageRole` | Yes | Sender role (user, assistant, system, tool) |\n| `content` | `string` | Yes | Message content |\n| `type` | `string` | No | Message type discriminator |\n| `name` | `string` | No | Optional name for the sender |\n| `toolCallId` | `string` | No | Tool call ID for tool messages |\n| `toolName` | `string` | No | Name of the tool being called |\n| `metadata` | `Record` | No | Additional message metadata |\n\n#### Message Roles\n\n| Role | Description |\n|------|-------------|\n| `user` | Human user message |\n| `assistant` | AI agent response |\n| `system` | System-level instructions |\n| `tool` | Tool execution result |\n\n### Tool Types\n\nTools enable agents to perform actions and access external functionality.\n\n资料来源：[sdks/typescript/packages/core/src/types.ts:80-120]()\n\n#### Tool Definition\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `id` | `string` | Yes | Unique tool identifier |\n| `name` | `string` | Yes | Tool name for invocation |\n| `description` | `string` | Yes | Human-readable description |\n| `inputSchema` | `object` | Yes | JSON Schema for tool inputs |\n| `type` | `string` | No | Tool type (default: \"function\") |\n\n### State Types\n\nState represents the application state that can be shared and synchronized between agent and frontend.\n\n资料来源：[sdks/typescript/packages/core/src/types.ts:150-200]()\n\n#### State Structure\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `stateId` | `string` | Yes | Unique state identifier |\n| `data` | `Record` | Yes | State data payload |\n| `version` | `number` | No | State version for conflict resolution |\n| `timestamp` | `number` | No | Last update timestamp |\n\n### Run Agent Input\n\nThe `RunAgentInput` type defines the input schema for starting an agent run.\n\n资料来源：[sdks/typescript/packages/core/src/types.ts:250-300]()\n\n#### RunAgentInput Fields\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `messages` | `Message[]` | Yes | Conversation history |\n| `tools` | `Tool[]` | No | Available tools |\n| `context` | `Context` | No | Execution context |\n| `systemPrompt` | `string` | No | System-level instructions |\n| `temperature` | `number` | No | Sampling temperature |\n| `maxTokens` | `number` | No | Maximum response tokens |\n\n## Event Types\n\nThe AG-UI protocol defines 16 core event types organized into logical categories for streaming communication.\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java:1-50]()\n\n```mermaid\ngraph LR\n subgraph Text Messages\n T1[TEXT_MESSAGE_START]\n T2[TEXT_MESSAGE_CONTENT]\n T3[TEXT_MESSAGE_END]\n T4[TEXT_MESSAGE_CHUNK]\n end\n \n subgraph Thinking\n T5[THINKING_MESSAGE_START]\n T6[THINKING_MESSAGE_CONTENT]\n T7[THINKING_MESSAGE_END]\n end\n \n subgraph Tool Calls\n T8[TOOL_CALL_START]\n T9[TOOL_CALL_ARGUMENTS]\n T10[TOOL_CALL_END]\n end\n \n subgraph State\n T11[STATE_UPDATE]\n T12[STATE_SNAPSHOT]\n end\n \n subgraph Lifecycle\n T13[RUN_STARTED]\n T14[RUN_FINISHED]\n T15[ERROR]\n end\n```\n\n### Text Message Events\n\n| Event Type | Description |\n|------------|-------------|\n| `TEXT_MESSAGE_START` | Signals the beginning of a text message stream |\n| `TEXT_MESSAGE_CONTENT` | Represents incremental text message content |\n| `TEXT_MESSAGE_END` | Signals the completion of a text message stream |\n| `TEXT_MESSAGE_CHUNK` | Represents a chunk of text message data |\n\n资料来源：[sdks/typescript/packages/core/src/events.ts:10-30]()\n\n### Thinking Events\n\n| Event Type | Description |\n|------------|-------------|\n| `THINKING_MESSAGE_START` | Signals the beginning of a thinking process |\n| `THINKING_MESSAGE_CONTENT` | Contains intermediate thinking content |\n| `THINKING_MESSAGE_END` | Signals the completion of thinking |\n\nThese events enable displaying AI reasoning processes to users in real-time.\n\n### Tool Call Events\n\n| Event Type | Description |\n|------------|-------------|\n| `TOOL_CALL_START` | Initiates a tool invocation |\n| `TOOL_CALL_ARGUMENTS` | Streams tool arguments incrementally |\n| `TOOL_CALL_END` | Completes a tool call |\n| `TOOL_CALL_RESULT` | Contains the tool execution result |\n\n资料来源：[sdks/typescript/packages/core/src/events.ts:50-80]()\n\n### State Management Events\n\n| Event Type | Description |\n|------------|-------------|\n| `STATE_UPDATE` | Represents a partial state change |\n| `STATE_SNAPSHOT` | Contains the complete current state |\n| `STATE_DIFF` | Represents state differences |\n\n### Execution Lifecycle Events\n\n| Event Type | Description |\n|------------|-------------|\n| `RUN_STARTED` | Signals the start of an agent run |\n| `RUN_FINISHED` | Signals the completion of a run |\n| `STEP_STARTED` | Signals the beginning of a step |\n| `STEP_FINISHED` | Signals the completion of a step |\n| `ERROR` | Contains error information |\n\n## Event Schema Validation\n\nThe AG-UI core package provides runtime validation through the `EventSchemas` class, which uses schema parsing to catch malformed payloads early.\n\n资料来源：[sdks/typescript/packages/core/README.md:30-40]()\n\n```typescript\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\n// Validate an incoming event\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n### Event Payload Structure\n\nAll events follow a consistent structure:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `type` | `string` | Event type identifier |\n| `data` | `object` | Event-specific payload |\n| `timestamp` | `number` | Event timestamp (optional) |\n| `runId` | `string` | Associated run identifier (optional) |\n\n## Protocol Buffer Definitions\n\nFor high-performance scenarios, the AG-UI protocol includes Protocol Buffer definitions that provide binary serialization.\n\n资料来源：[sdks/typescript/packages/proto/src/generated/types.ts:1-100]()\n\nThe protobuf types maintain parity with the JSON types but offer advantages in bandwidth-constrained environments:\n\n- **Smaller payload sizes** - Binary encoding reduces message overhead\n- **Faster parsing** - Native binary parsing vs JSON string processing\n- **Language interoperability** - Generated code for multiple languages\n\n### Proto Message Mapping\n\n| JSON Type | Proto Message | Notes |\n|-----------|---------------|-------|\n| `Message` | `Message` | Full parity |\n| `Tool` | `ToolDefinition` | Input schema as `google.protobuf.Struct` |\n| `State` | `AgentState` | Version field for conflict resolution |\n| `Event` | `StreamEvent` | Union type for all event types |\n\n## Serialization\n\nThe AG-UI protocol supports multiple serialization formats to accommodate different transport mechanisms and client requirements.\n\n资料来源：[docs/concepts/serialization.mdx:1-30]()\n\n### Supported Formats\n\n| Format | Use Case | Performance |\n|--------|----------|--------------|\n| JSON | REST APIs, Browser clients | Good |\n| Server-Sent Events (SSE) | Streaming responses | Excellent |\n| Protocol Buffers | High-throughput systems | Best |\n| Binary | Minimal payload sizes | Best |\n\n### JSON Schema\n\nThe TypeScript SDK exports JSON schemas that can be used for:\n\n- **Client-side validation** - Validate incoming events\n- **Documentation generation** - Auto-generate API docs\n- **Code generation** - Create typed clients from schemas\n\n## Python Type System\n\nThe Python SDK provides equivalent type definitions through Pydantic models, ensuring type safety and validation in Python-based agent implementations.\n\n资料来源：[sdks/python/ag_ui/core/types.py:1-80]()\n\n```python\nfrom ag_ui.core.types import Message, Tool, State, RunAgentInput\nfrom ag_ui.core.events import EventType, BaseEvent\n```\n\n### Python Type Mapping\n\n| Python Type | TypeScript Equivalent | Validation |\n|-------------|---------------------|------------|\n| `Message` | `Message` | Pydantic validators |\n| `Tool` | `Tool` | JSON Schema validation |\n| `State` | `State` | Version checking |\n| `RunAgentInput` | `RunAgentInput` | Required field validation |\n\n## Event Streaming Architecture\n\n```mermaid\nsequenceDiagram\n participant Client\n participant AGUICore\n participant Agent\n participant Tools\n \n Client->>AGUICore: Connect to stream\n Agent->>AGUICore: Emit TEXT_MESSAGE_START\n AGUICore->>Client: Stream event\n Agent->>AGUICore: Emit TEXT_MESSAGE_CONTENT\n AGUICore->>Client: Stream event (delta)\n Agent->>AGUICore: Emit TOOL_CALL_START\n AGUICore->>Client: Stream event\n Tools->>Agent: Execute tool\n Agent->>AGUICore: Emit TOOL_CALL_RESULT\n AGUICore->>Client: Stream event\n Agent->>AGUICore: Emit RUN_FINISHED\n AGUICore->>Client: Stream event\n```\n\n## Usage Patterns\n\n### Creating a Message\n\n```typescript\nimport { Message, MessageRole } from \"@ag-ui/core\";\n\nconst userMessage: Message = {\n id: \"msg_unique_123\",\n role: MessageRole.User,\n content: \"What's the weather in San Francisco?\",\n};\n```\n\n### Defining a Tool\n\n```typescript\nimport { Tool } from \"@ag-ui/core\";\n\nconst weatherTool: Tool = {\n id: \"tool_weather\",\n name: \"get_weather\",\n description: \"Get current weather for a location\",\n inputSchema: {\n type: \"object\",\n properties: {\n location: { type: \"string\" },\n unit: { type: \"string\", enum: [\"celsius\", \"fahrenheit\"] },\n },\n required: [\"location\"],\n },\n};\n```\n\n### Processing Events\n\n```typescript\nimport { EventType } from \"@ag-ui/core\";\n\nfunction handleEvent(event: BaseEvent) {\n switch (event.type) {\n case EventType.TEXT_MESSAGE_CONTENT:\n console.log(\"Received text:\", event.delta);\n break;\n case EventType.TOOL_CALL_START:\n console.log(\"Tool called:\", event.toolName);\n break;\n case EventType.STATE_UPDATE:\n console.log(\"State updated:\", event.state);\n break;\n }\n}\n```\n\n## Framework Integration\n\nThe type system is designed to be framework-agnostic and integrates with:\n\n- **LangChain** - Via `@ag-ui/langchain` integration\n- **LangGraph** - Via `@ag-ui/langgraph` integration\n- **PydanticAI** - Via `@ag-ui/pydantic-ai` integration\n- **ADK Middleware** - Via `adk-middleware` integration\n- **Langroid** - Via `@ag-ui/langroid` integration\n\nEach integration maps its native types to the AG-UI type system, ensuring consistent behavior across different agent frameworks.\n\n---\n\n\n\n## Capabilities System\n\n### 相关页面\n\n相关主题：[Event Specification](#events), [TypeScript SDK](#typescript-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/src/capabilities.ts](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/src/capabilities.ts)\n- [sdks/python/ag_ui/core/capabilities.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/core/capabilities.py)\n- [docs/concepts/capabilities.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/concepts/capabilities.mdx)\n- [docs/concepts/generative-ui-specs.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/concepts/generative-ui-specs.mdx)\n \n\n# Capabilities System\n\nThe 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.\n\n## Overview\n\nThe 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.\n\nThe 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.\n\n## Architecture\n\nThe 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.\n\n```mermaid\ngraph TD\n A[Client Application] --> B[AG-UI Client SDK]\n B --> C[Capabilities Manager]\n C --> D[Capability Definitions]\n C --> E[Capability Negotiation Engine]\n \n F[Server Application] --> G[AG-UI Server SDK]\n G --> H[Capabilities Validator]\n H --> D\n \n E <-->|Capability Exchange| H\n \n I[Core Capability Schemas] --> D\n J[Custom Capability Extensions] --> D\n```\n\n## Core Capability Categories\n\nThe 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.\n\n### Agentic Chat Capabilities\n\nAgentic 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.\n\nThe 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.\n\n### Backend Tool Rendering Capabilities\n\nBackend 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.\n\nTools 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.\n\n### Human-in-the-Loop Capabilities\n\nHuman-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.\n\nWhen 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.\n\n### Agentic Generative UI Capabilities\n\nAgentic 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.\n\nThis 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.\n\n### Tool-Based Generative UI Capabilities\n\nTool-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.\n\n### Shared State Capabilities\n\nShared 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.\n\nThe 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.\n\n### Predictive State Updates Capabilities\n\nPredictive 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.\n\n## Capability Definition Schema\n\nThe 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.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | string | Unique identifier for the capability |\n| `version` | string | Semantic version of the capability implementation |\n| `enabled` | boolean | Whether the capability is currently active |\n| `parameters` | object | Capability-specific configuration parameters |\n| `dependencies` | string[] | Other capabilities required for this capability |\n\n## Capability Negotiation Flow\n\nThe 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.\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant CapabilitiesManager\n \n Client->>CapabilitiesManager: Create ClientCapabilities\n CapabilitiesManager-->>Client: Capability Instance\n Client->>Server: Send INITIALIZE with capabilities\n Server->>CapabilitiesManager: Validate client capabilities\n CapabilitiesManager-->>Server: Validation result\n Server->>CapabilitiesManager: Create ServerCapabilities\n Server->>Client: Send INITIALIZE_COMPLETE with server capabilities\n Client->>CapabilitiesManager: Compare and merge capabilities\n CapabilitiesManager-->>Client: Negotiated capability set\n```\n\nThe 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.\n\n## TypeScript Implementation\n\nThe 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.\n\n```typescript\nimport { Capabilities, CapabilityType, negotiateCapabilities } from \"@ag-ui/core\";\n\n// Define client capabilities\nconst clientCapabilities: Capabilities = {\n agenticChat: { enabled: true, version: \"1.0.0\" },\n backendToolRendering: { enabled: true, version: \"1.0.0\" },\n humanInTheLoop: { enabled: true, version: \"1.0.0\" },\n agenticGenerativeUI: { enabled: true, version: \"1.0.0\" },\n toolBasedGenerativeUI: { enabled: false, version: \"1.0.0\" },\n sharedState: { enabled: true, version: \"1.0.0\" },\n predictiveStateUpdates: { enabled: false, version: \"1.0.0\" }\n};\n\n// Negotiate with server capabilities\nconst negotiated = negotiateCapabilities(clientCapabilities, serverCapabilities);\n```\n\nThe implementation provides runtime validation of capability configurations, ensuring that capability declarations conform to the expected schema before being used in negotiation.\n\n## Python Implementation\n\nThe 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.\n\n```python\nfrom ag_ui.core.capabilities import (\n Capabilities,\n CapabilityType,\n negotiate_capabilities,\n ClientCapabilities,\n ServerCapabilities\n)\n\n# Define server capabilities\nserver_capabilities = ServerCapabilities(\n agentic_chat=CapabilityStatus(enabled=True, version=\"1.0.0\"),\n backend_tool_rendering=CapabilityStatus(enabled=True, version=\"1.0.0\"),\n human_in_the_loop=CapabilityStatus(enabled=True, version=\"1.0.0\"),\n agentic_generative_ui=CapabilityStatus(enabled=True, version=\"1.0.0\"),\n tool_based_generative_ui=CapabilityStatus(enabled=False, version=\"1.0.0\"),\n shared_state=CapabilityStatus(enabled=True, version=\"1.0.0\"),\n predictive_state_updates=CapabilityStatus(enabled=True, version=\"1.0.0\")\n)\n\n# Negotiate with client capabilities\nnegotiated = negotiate_capabilities(client_capabilities, server_capabilities)\n```\n\nThe Python implementation integrates seamlessly with FastAPI and other async web frameworks, providing capability endpoints that handle the negotiation protocol.\n\n## Integration Examples\n\nDifferent agent frameworks integrate with the Capabilities System in various ways, depending on their architecture and requirements.\n\n### ADK Middleware Integration\n\nThe 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.\n\n```python\nfrom google.adk.middleware import Middleware\nfrom ag_ui.core.capabilities import AGUIToolset\n\nmiddleware = Middleware(\n name=\"ag_ui_middleware\",\n capabilities={\n \"agentic_chat\": True,\n \"backend_tool_rendering\": True,\n \"human_in_the_loop\": True,\n \"shared_state\": True\n }\n)\n```\n\n### Claude Agent SDK Integration\n\nThe 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.\n\n```python\nfrom ag_ui_claude_sdk import ClaudeAgentAdapter\n\nadapter = ClaudeAgentAdapter(\n name=\"my_agent\",\n options={\"model\": \"claude-haiku-4-5\"},\n capabilities={\n \"agentic_chat\": True,\n \"backend_tool_rendering\": True,\n \"human_in_the_loop\": True,\n \"agentic_generative_ui\": True,\n \"tool_based_generative_ui\": True,\n \"shared_state\": True,\n \"predictive_state_updates\": True\n }\n)\n```\n\n## Capability Versioning\n\nThe 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.\n\nWhen 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.\n\n| Compatibility Level | Description |\n|--------------------|-------------|\n| Full Match | Both implementations declare identical versions |\n| Minor Compatible | Client version is greater than or equal to server version |\n| Major Compatible | Both versions share the same major number |\n| Incompatible | Versions have conflicting major numbers |\n\n## Error Handling\n\nThe 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.\n\nError 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.\n\n## Best Practices\n\nWhen working with the Capabilities System, several best practices ensure robust and maintainable implementations.\n\n**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.\n\n**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.\n\n**Capability Fallback**: Implement fallback behavior for unsupported capabilities. Rather than failing entirely, design agents to operate in degraded mode when certain capabilities are unavailable.\n\n**Capability Testing**: Test capability negotiation thoroughly, including edge cases where partial capability sets are provided or where version mismatches occur.\n\n## Summary\n\nThe 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.\n\n---\n\n\n\n## TypeScript SDK\n\n### 相关页面\n\n相关主题：[Python SDK](#python-sdk), [Event Specification](#events)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n- [sdks/typescript/packages/cli/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/cli/README.md)\n- [integrations/langchain/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langchain/typescript/package.json)\n- [integrations/langgraph/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/package.json)\n- [integrations/vercel-ai-sdk/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/vercel-ai-sdk/typescript/package.json)\n- [middlewares/a2a-middleware/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/middlewares/a2a-middleware/package.json)\n \n\n# TypeScript SDK\n\nThe **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.\n\n## Architecture Overview\n\nThe TypeScript SDK follows a modular architecture with core packages and framework-specific integrations.\n\n```mermaid\ngraph TD\n A[Application Code] --> B[@ag-ui/core]\n A --> C[@ag-ui/client]\n B --> D[EventSchemas]\n B --> E[EventType]\n C --> F[Agent Client]\n C --> G[Middleware]\n F --> H[HTTP Transport]\n F --> I[WebSocket Transport]\n H --> J[LangChain]\n H --> K[LangGraph]\n H --> L[Vercel AI SDK]\n G --> M[a2a-middleware]\n G --> N[Custom Middleware]\n```\n\n## Package Structure\n\n| Package | Purpose | Version | Key Dependencies |\n|---------|---------|---------|-------------------|\n| `@ag-ui/core` | Type definitions, schemas, event types | >=0.0.42 | zod |\n| `@ag-ui/client` | HTTP agent, streaming, state management | >=0.0.42 | rxjs |\n| `@ag-ui/cli` | Project scaffolding tool | - | - |\n| `@ag-ui/langgraph` | LangGraph integration | 0.0.32 | @langchain/core, @langchain/langgraph-sdk |\n| `@ag-ui/vercel-ai-sdk` | Vercel AI SDK integration | - | ai, zod |\n| `@ag-ui/a2a-middleware` | A2A protocol bridge | 0.0.2 | @a2a-js/sdk, ai |\n\n## Core Package (@ag-ui/core)\n\nThe `@ag-ui/core` package delivers the foundational type system and runtime validation for AG-UI protocol implementations.\n\n### Typed Data Models\n\nThe core package provides TypeScript interfaces for all AG-UI data models:\n\n```typescript\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\n// Validate an incoming event\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n### Supported Data Models\n\n| Model | Description |\n|-------|-------------|\n| `Message` | User and assistant message representation |\n| `Tool` | Tool definition with parameters |\n| `Context` | Conversation context data |\n| `RunAgentInput` | Input for agent execution |\n| `State` | Application state structure |\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n### Event System\n\nThe core package defines 16 core event kinds covering the complete agent lifecycle:\n\n| Event Category | Events |\n|----------------|--------|\n| Assistant Messages | `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END`, `AUDIO_MESSAGE_CONTENT` |\n| Tool Calls | `TOOL_CALLS_START`, `TOOL_CALLS_END`, `TOOL_CALL_RESULT` |\n| State Updates | `STATE_SNAPSHOT`, `STATE_DELTA` |\n| Run Lifecycle | `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR` |\n| Content Types | `INSTRUCTION`, `CHAT_OVERFLOW`, `BINARY_MESSAGE_CONTENT` |\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n### Runtime Validation\n\nAll event payloads are validated at runtime using Zod schemas, ensuring malformed payloads are caught early in the development process.\n\n## Client Package (@ag-ui/client)\n\nThe `@ag-ui/client` package provides the runtime client for connecting applications to AG-UI protocol servers.\n\n### Installation\n\n```bash\nnpm install @ag-ui/client\npnpm add @ag-ui/client\nyarn add @ag-ui/client\n```\n\n### HTTP Agent\n\nThe HTTP agent handles communication with AG-UI backend servers:\n\n```typescript\nimport { HttpAgent } from \"@ag-ui/client\";\n\nconst agent = new HttpAgent({\n url: \"http://localhost:8000/\",\n apiKey: process.env.AG_UI_API_KEY,\n});\n```\n\n#### Configuration Options\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `url` | `string` | Yes | - | Base URL of the AG-UI server |\n| `apiKey` | `string` | No | `undefined` | API key for authentication |\n| `timeout` | `number` | No | `30000` | Request timeout in milliseconds |\n| `headers` | `Record` | No | `{}` | Custom headers |\n\n### Event Streaming\n\nThe client supports full event streaming using RxJS observables:\n\n```typescript\nimport { createAgent } from \"@ag-ui/client\";\n\nconst agent = createAgent({\n url: \"http://localhost:8000/\",\n});\n\nagent.events$.subscribe((event) => {\n console.log(\"Received event:\", event.type);\n});\n```\n\n## Middleware System\n\nThe TypeScript SDK implements a middleware system that allows intercepting and transforming requests and responses.\n\n```mermaid\ngraph LR\n A[Request] --> B[Middleware 1]\n B --> C[Middleware 2]\n C --> D[Middleware N]\n D --> E[Agent]\n E --> F[Response]\n F --> G[Response Middleware]\n```\n\n### Built-in Middleware\n\n| Middleware | Purpose | Package |\n|------------|---------|---------|\n| `a2a-middleware` | Bridge to A2A protocol | `@ag-ui/a2a-middleware` |\n| Custom Middleware | User-defined transformations | `@ag-ui/client` |\n\n### Creating Custom Middleware\n\n```typescript\nimport { createMiddleware } from \"@ag-ui/client\";\n\nconst loggingMiddleware = createMiddleware({\n name: \"logger\",\n onRequest: async (request, env) => {\n console.log(\"Request:\", request);\n return request;\n },\n onResponse: async (response, env) => {\n console.log(\"Response:\", response);\n return response;\n },\n});\n```\n\n## Framework Integrations\n\nThe TypeScript SDK provides pre-built integrations for popular agent frameworks:\n\n### LangChain Integration\n\n```json\n{\n \"dependencies\": {\n \"@ag-ui/core\": \">=0.0.42\",\n \"@ag-ui/client\": \">=0.0.42\",\n \"@langchain/core\": \"^1.1.40\",\n \"@langchain/langgraph-sdk\": \"^1.8.8\",\n \"langchain\": \">=1.2.0\"\n }\n}\n```\n\n资料来源：[integrations/langgraph/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/package.json)\n\n### Vercel AI SDK Integration\n\n```json\n{\n \"dependencies\": {\n \"@ag-ui/core\": \">=0.0.42\",\n \"@ag-ui/client\": \">=0.0.42\",\n \"ai\": \"^4.3.16\",\n \"zod\": \"^3.22.4\"\n }\n}\n```\n\n资料来源：[integrations/vercel-ai-sdk/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/vercel-ai-sdk/typescript/package.json)\n\n### A2A Middleware\n\nThe A2A (Agent-to-Agent) middleware enables interoperability with A2A protocol-compliant agents:\n\n```json\n{\n \"dependencies\": {\n \"@a2a-js/sdk\": \"^0.2.2\",\n \"ai\": \"^4.3.16\",\n \"zod\": \"^3.22.4\"\n },\n \"peerDependencies\": {\n \"@ag-ui/client\": \">=0.0.40\",\n \"rxjs\": \"7.8.1\"\n }\n}\n```\n\n资料来源：[middlewares/a2a-middleware/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/middlewares/a2a-middleware/package.json)\n\n## CLI Tool (@ag-ui/cli)\n\nThe AG-UI CLI provides project scaffolding capabilities:\n\n```bash\nnpx create-ag-ui-app@latest my-agent-app\nnpx create-ag-ui-app@latest --help\n```\n\n资料来源：[sdks/typescript/packages/cli/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/cli/README.md)\n\n## Quick Start\n\n### 1. Install Core Dependencies\n\n```bash\nnpm install @ag-ui/core @ag-ui/client\n```\n\n### 2. Create an Agent Client\n\n```typescript\nimport { HttpAgent } from \"@ag-ui/client\";\nimport { EventType } from \"@ag-ui/core\";\n\nconst agent = new HttpAgent({\n url: process.env.AG_UI_BASE_URL || \"http://127.0.0.1:8000\",\n apiKey: process.env.AG_UI_API_KEY,\n});\n\n// Subscribe to events\nagent.events$.subscribe((event) => {\n switch (event.type) {\n case EventType.RUN_STARTED:\n console.log(\"Run started:\", event.runId);\n break;\n case EventType.TEXT_MESSAGE_CONTENT:\n console.log(\"Message delta:\", event.delta);\n break;\n case EventType.RUN_FINISHED:\n console.log(\"Run finished:\", event.runId);\n break;\n }\n});\n```\n\n### 3. Send a Message\n\n```typescript\nawait agent.send({\n type: \"USER_MESSAGE\",\n messageId: \"msg_001\",\n content: \"Hello, agent!\",\n});\n```\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AG_UI_BASE_URL` | Base URL of the AG-UI server | `http://127.0.0.1:8000` |\n| `AG_UI_API_KEY` | API key for authentication | `undefined` |\n| `DEBUG` | Enable debug logging | `false` |\n\n## Testing\n\nThe SDK includes comprehensive test coverage using Vitest:\n\n```bash\n# Run all tests\npnpm test\n\n# Run with coverage\npnpm test:coverage\n\n# Watch mode\npnpm test:watch\n\n# Validate package exports\npnpm test:exports\n```\n\n## Documentation\n\n- Concepts & Architecture: [docs.ag-ui.com/concepts/architecture](https://docs.ag-ui.com/concepts/architecture)\n- Full API Reference: [docs.ag-ui.com/sdk/js/core](https://docs.ag-ui.com/sdk/js/core/overview)\n- Contributing Guide: [docs.ag-ui.com/development/contributing](https://docs.ag-ui.com/development/contributing)\n\n## License\n\nMIT © 2025 AG-UI Protocol Contributors\n\n---\n\n\n\n## Python SDK\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#typescript-sdk), [LangGraph Integration](#langgraph-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/README.md)\n- [sdks/python/ag_ui/__init__.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/core/events.py)\n- [sdks/python/ag_ui/core/events.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/core/events.py)\n- [sdks/python/ag_ui/core/types.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/core/types.py)\n- [sdks/python/ag_ui/encoder/encoder.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/encoder/encoder.py)\n- [docs/sdk/python/core/overview.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/python/core/overview.mdx)\n \n\n# Python SDK\n\nThe 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).\n\n## Overview\n\nThe Python SDK is designed as a lightweight, framework-agnostic foundation that offers:\n\n- **Core event models** - Type-safe event definitions matching the AG-UI protocol specification\n- **Runtime schema validation** - Pydantic-based schemas for early validation of payloads\n- **Event encoding** - Utilities for encoding events into SSE format\n- **State management** - Typed state models for bidirectional state synchronization\n\nThe 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.\n\n## Architecture\n\nThe Python SDK follows a modular architecture with distinct layers:\n\n```mermaid\ngraph TD\n A[Application Layer] --> B[SDK Core]\n B --> C[Event Models]\n B --> D[Type Definitions]\n B --> E[Encoder]\n C --> F[ag_ui.core.events]\n D --> G[ag_ui.core.types]\n E --> H[ag_ui.encoder.encoder]\n F --> I[Runtime Validation]\n G --> I\n H --> J[SSE Output]\n J --> K[Frontend Client]\n```\n\n## Package Structure\n\n| Module | Purpose |\n|--------|---------|\n| `ag_ui.core.events` | Event class definitions and factories for all AG-UI event types |\n| `ag_ui.core.types` | Core type definitions including `Message`, `Tool`, `Context`, `RunAgentInput`, and `State` |\n| `ag_ui.encoder.encoder` | Event encoding utilities for SSE serialization |\n\n## Event System\n\nThe SDK defines 16 core event kinds covering the complete AG-UI protocol lifecycle:\n\n### Event Categories\n\n| Category | Events | Purpose |\n|----------|--------|---------|\n| **Run Lifecycle** | `RUN_STARTED`, `RUN_FINISHED` | Mark the beginning and end of an agent run |\n| **Text Messages** | `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END` | Stream text responses to the client |\n| **Tool Calls** | `TOOL_CALL_START`, `TOOL_CALL_ARGUMENTS`, `TOOL_CALL_END` | Execute backend tools |\n| **Tool Results** | `TOOL_CALL_RESULT` | Return tool execution results |\n| **State Updates** | `STATE_SNAPSHOT`, `STATE_DELTA` | Synchronize shared state with frontend |\n| **UI Triggers** | `PATCH_ASSET`, `CUSTOM_EVENT`, `AGENT_TOOL_CALLS` | Trigger frontend UI updates |\n\n### Event Validation\n\nEvents are validated at runtime using Pydantic schemas. This ensures malformed payloads are caught early and provides clear error messages for debugging.\n\n```python\nfrom ag_ui.core.events import EventSchemas, EventType\n\n# Validate an incoming event\nvalidated_event = EventSchemas.parse({\n \"type\": EventType.TEXT_MESSAGE_CONTENT,\n \"messageId\": \"msg_123\",\n \"delta\": \"Hello, world!\"\n})\n```\n\n## Core Types\n\nThe SDK provides strongly-typed data models for AG-UI concepts:\n\n| Type | Description |\n|------|-------------|\n| `Message` | Represents a conversation message with role and content |\n| `Tool` | Tool definition including name, description, and parameters |\n| `Context` | Execution context including thread_id and run_id |\n| `RunAgentInput` | Input payload for initiating an agent run |\n| `State` | Shared application state with type-safe access |\n\n## Event Encoding\n\nThe encoder module handles serialization of AG-UI events into Server-Sent Events format:\n\n```mermaid\nsequenceDiagram\n participant App as Application\n participant SDK as Python SDK\n participant Encoder as Event Encoder\n participant Client as Frontend\n\n App->>SDK: Create event object\n SDK->>Encoder: Encode to SSE format\n Encoder->>Client: data: {\"type\": \"...\", ...}\\n\\n\n Client->>Client: Parse and render\n```\n\nThe encoder ensures proper SSE formatting with:\n- JSON serialization of event data\n- Double newline termination as per SSE spec\n- Support for event type naming\n\n## Integration Patterns\n\nThe Python SDK is used as the foundation for framework-specific integrations:\n\n### Direct Usage\n\n```python\nfrom ag_ui import AGUIServer, Agent\n\nagent = Agent(name=\"my_agent\")\nserver = AGUIServer(agent=agent)\n\n# Stream events to client\nasync for event in agent.run(input_data):\n await server.send(event)\n```\n\n### Integration Ecosystem\n\n| Integration | Package | Description |\n|-------------|---------|-------------|\n| Langroid | `langroid` | Multi-agent framework with AG-UI support |\n| Claude Agent SDK | `ag_ui_claude_sdk` | Anthropic Claude integration |\n| ADK Middleware | `ag_ui_adk` | Google Agent Development Kit adapter |\n| Microsoft Agent Framework | `ag_ui_microsoft` | Azure AI Agent Service integration |\n| Pydantic AI | `pydantic_ai` | Pydantic-based agent framework |\n\n## Installation\n\n```bash\npip install ag-ui\n# or with uv\nuv pip install ag-ui\n```\n\n## Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `AG_UI_BASE_URL` | Base URL of the AG-UI server | `http://127.0.0.1:8000` |\n| `AG_UI_API_KEY` | API key for authentication | None |\n\n## Testing\n\nThe SDK includes a comprehensive test suite with mock server support:\n\n```bash\n# Run tests\npytest\n\n# With coverage\npytest --cov=src/ag_ui\n\n# Specific test file\npytest tests/test_events.py\n```\n\n## Documentation\n\nAdditional documentation is available at:\n- Concepts & architecture: [`docs/concepts`](https://docs.ag-ui.com/concepts/architecture)\n- Python SDK reference: [`docs/sdk/python/core`](https://docs.ag-ui.com/sdk/python/core/overview)\n- Full API reference: [`docs/events`](https://docs.ag-ui.com/concepts/events)\n\n## Contributing\n\nBug reports and pull requests are welcome. Please read the [contributing guide](https://docs.ag-ui.com/development/contributing) before submitting changes.\n\n## License\n\nMIT © 2025 AG-UI Protocol Contributors\n\n---\n\n\n\n## Community SDKs\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#typescript-sdk), [Python SDK](#python-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/community/dart/example/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/dart/example/README.md)\n- [sdks/community/ruby/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/ruby/README.md)\n- [sdks/community/c++/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/c++/README.md)\n- [sdks/community/java/packages/client/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/client/README.md)\n- [sdks/community/java/clients/ok-http/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/clients/ok-http/README.md)\n- [integrations/langroid/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/README.md)\n- [integrations/langroid/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/typescript/README.md)\n \n\n# Community SDKs\n\nThe 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.\n\n## Overview\n\nCommunity 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:\n\n- Event encoding and decoding following the AG-UI event schema\n- HTTP/WebSocket communication with AG-UI servers\n- State synchronization between agent and client\n- Tool call handling and response streaming\n\n资料来源：[sdks/community/ruby/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/ruby/README.md)\n\n## Supported Languages\n\nThe AG-UI community has contributed SDK implementations for the following programming languages:\n\n| Language | Package Name | Status | Key Features |\n|----------|--------------|--------|--------------|\n| Kotlin | `@ag-ui/kotlin` | Active | JVM-compatible, coroutines support |\n| Go | `@ag-ui/go` | Active | Lightweight, concurrent-friendly |\n| Dart | `@ag-ui/dart` | Active | Flutter/dart ecosystem support |\n| Java | `com.ag-ui.community` | Active | Enterprise-grade, OkHttp client |\n| Ruby | `ag_ui` | Active | Ruby idiomatic API |\n| Rust | `ag-ui-client` | Active | Memory-safe, high performance |\n| C++ | `agui` | Active | Cross-platform, minimal dependencies |\n\n## Architecture Pattern\n\nAll community SDKs follow a consistent architectural pattern for AG-UI integration:\n\n```mermaid\ngraph TD\n A[AG-UI Client/Frontend] <--> |SSE/WebSocket| B[Community SDK Server]\n B --> C[Language-Specific Agent Implementation]\n C --> D[Agent Logic/Tools]\n B --> E[State Management]\n E --> A\n \n F[Event Encoder] --> B\n G[Event Decoder] --> B\n```\n\n### Component Responsibilities\n\n| Component | Purpose |\n|-----------|---------|\n| HTTP Client | Handles communication with AG-UI server endpoints |\n| Event Encoder | Serializes events to AG-UI protocol format |\n| Event Decoder | Deserializes incoming events from clients |\n| State Manager | Maintains shared state synchronization |\n| Tool Handler | Processes and responds to tool calls |\n\n资料来源：[integrations/langroid/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/README.md)\n\n## Dart SDK\n\nThe Dart SDK enables Flutter and Dart applications to interact with AG-UI protocol servers. It provides both synchronous and asynchronous communication patterns.\n\n### Environment Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AG_UI_BASE_URL` | Base URL of the AG-UI server | `http://127.0.0.1:8000` |\n| `AG_UI_API_KEY` | API key for authentication | None |\n| `DEBUG` | Enable debug logging | `false` |\n\n### Basic Usage\n\n```dart\nimport 'package:ag_ui_dart/ag_ui_dart.dart';\n\n// Create an HTTP Agent\nfinal agent = HttpAgent(\n url: 'http://localhost:8080/api/agent/run',\n agentId: 'my-agent',\n);\n\n// Subscribe to events\nagent.subscribe((event) {\n print('Received event: ${event.type}');\n});\n\n// Send user message\nawait agent.sendMessage('Hello, agent!');\n```\n\n资料来源：[sdks/community/dart/example/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/dart/example/README.md)\n\n## Ruby SDK\n\nThe Ruby SDK provides idiomatic Ruby integration for the AG-UI protocol, suitable for Ruby on Rails applications or standalone Ruby agents.\n\n### Installation\n\n```bash\ncd sdks/community/ruby\nbundle install\n```\n\n### Running Examples\n\n```bash\n# Navigate to example directory\ncd sdks/community/ruby/example/simple-use\n\n# Install dependencies\nbundle install\n\n# Run the example\nbundle exec ruby main.rb\n```\n\n### Testing\n\n```bash\ncd sdks/community/ruby\nrake test\n```\n\n### Documentation\n\nGenerate YARD documentation:\n\n```bash\ncd sdks/community/ruby\nrake doc\n```\n\n资料来源：[sdks/community/ruby/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/ruby/README.md)\n\n## C++ SDK\n\nThe C++ SDK provides a header-only, dependency-light implementation suitable for embedded systems and performance-critical applications.\n\n### Build Dependencies\n\n| Platform | Required Packages |\n|----------|-------------------|\n| macOS | cmake, pkg-config, nlohmann-json3, libcurl |\n| Ubuntu/Debian | cmake, g++, pkg-config, nlohmann-json3-dev, libcurl4-openssl-dev |\n| Google Test | libgtest-dev (optional, for testing) |\n\n### Building the SDK\n\n```bash\n# Clone and navigate to C++ SDK directory\ngit clone https://github.com/ag-ui-protocol/ag-ui.git\ncd ag-ui/sdks/community/c++\n\n# Create build directory\nmkdir build && cd build\n\n# Configure with tests enabled\ncmake -DBUILD_TESTS=ON ..\n\n# Build\nmake -j4\n```\n\n### Basic Usage\n\n```cpp\n#include \"agent/http_agent.h\"\n\nusing namespace agui;\n\nint main() {\n auto agent = HttpAgent::builder()\n .withUrl(\"http://localhost:8080/api/agent/run\")\n .withAgentId(AgentId(\"my-agent\"))\n .build();\n \n // Create subscriber for events\n class MySubscriber : public IAgentSubscriber {\n AgentStateMutation onTextMessageContent(\n const TextMessageContentEvent& event,\n const std::string& buffer,\n const AgentSubscriberParams& params) override {\n std::cout << event.delta;\n return AgentStateMutation::CONTINUE;\n }\n };\n \n agent->subscribe(std::make_shared());\n return 0;\n}\n```\n\n资料来源：[sdks/community/c++/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/c++/README.md)\n\n## Java SDK\n\nThe Java SDK provides enterprise-grade AG-UI protocol support with two main components: the core client and an OkHttp-based HTTP client.\n\n### Maven Dependency\n\n```xml\n\n com.ag-ui.community\n java-client\n 0.0.1\n\n```\n\n### OkHttp Client\n\nFor applications using OkHttp:\n\n```xml\n\n com.ag-ui.community\n java-ok-http\n 4.12.0\n\n```\n\n### Key Components\n\n| Component | Description |\n|-----------|-------------|\n| `AbstractAgent` | Base class for agent implementations |\n| `HttpClient` | OkHttp-based HTTP communication |\n| Event handlers | Process AG-UI streaming events |\n\n资料来源：[sdks/community/java/packages/client/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/client/README.md)\n\n资料来源：[sdks/community/java/clients/ok-http/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/clients/ok-http/README.md)\n\n## Kotlin SDK\n\nThe Kotlin SDK provides AG-UI protocol support for JVM applications with idiomatic Kotlin patterns including coroutines support and DSL-style builders.\n\n### Overview\n\nThe Kotlin SDK offers:\n\n- Coroutines-based asynchronous communication\n- Type-safe builders for agent configuration\n- Seamless interoperability with Java\n\n资料来源：[docs/sdk/kotlin/overview.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/kotlin/overview.mdx)\n\n## Go SDK\n\nThe Go SDK provides lightweight AG-UI protocol integration optimized for concurrent operations and minimal memory footprint.\n\n### Features\n\n- Goroutine-friendly concurrent event processing\n- Channel-based event streaming\n- Minimal dependencies\n- High performance for production workloads\n\n资料来源：[docs/sdk/go/overview.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/go/overview.mdx)\n\n## Rust SDK\n\nThe Rust SDK (`ag-ui-client`) offers memory-safe, high-performance AG-UI protocol support suitable for systems programming and performance-critical applications.\n\n### Key Features\n\n- Zero-cost abstractions\n- Async runtime support\n- Memory safety guarantees\n- Small binary footprint\n\n## Integration with Langroid\n\nThe Langroid integration demonstrates how community SDKs can bridge different agent frameworks with the AG-UI protocol.\n\n```mermaid\ngraph LR\n A[TypeScript Frontend] <--> B[Langroid TypeScript Client]\n B <--> C[Langroid Python Server]\n C --> D[Python Agent Implementation]\n \n E[Python Tools] --> D\n F[AG-UI Tools] --> B\n```\n\n### Langroid Python Integration\n\n```bash\n# Install dependencies\ncd python\npip install -e .\ncd examples\npip install -e .\n```\n\n### Langroid TypeScript Client\n\n```typescript\nimport { LangroidHttpAgent } from \"@ag-ui/langroid\";\n\nconst agent = new LangroidHttpAgent({\n url: \"http://localhost:8000/\",\n});\n```\n\n资料来源：[integrations/langroid/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/README.md)\n\n资料来源：[integrations/langroid/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/typescript/README.md)\n\n## Contributing\n\nCommunity SDK contributions are welcome. The project maintains contribution guidelines that all SDK contributors should follow.\n\n### Contribution Process\n\n1. Create a new directory under `sdks/community//`\n2. Implement the AG-UI event protocol specification\n3. Include README.md with installation and usage instructions\n4. Add tests for core functionality\n5. Submit a pull request for review\n\n### Quality Standards\n\n| Requirement | Description |\n|-------------|-------------|\n| Documentation | Clear README with setup and usage examples |\n| Testing | Unit tests for core components |\n| Type Safety | Strong typing where applicable |\n| Error Handling | Graceful error management |\n\n资料来源：[sdks/community/ruby/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/ruby/README.md)\n\n## License\n\nAll community SDKs are released under the MIT License. See the main AG-UI repository for complete license information.\n\n---\n\n*Last updated: Based on repository state as of latest commit.*\n\n---\n\n\n\n## LangGraph Integration\n\n### 相关页面\n\n相关主题：[Python SDK](#python-sdk), [TypeScript SDK](#typescript-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [integrations/langgraph/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/README.md)\n- [integrations/langgraph/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/package.json)\n- [integrations/langgraph/typescript/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/examples/README.md)\n- [integrations/langgraph/typescript/examples/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/examples/package.json)\n- [integrations/langgraph/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/python/README.md)\n- [docs/integrations.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/integrations.mdx)\n \n\n# LangGraph Integration\n\nThe `@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.\n\n## Overview\n\nLangGraph is a library for building stateful, multi-actor applications with Large Language Models (LLMs). The AG-UI LangGraph integration extends these capabilities by providing:\n\n- Bidirectional state synchronization between graph nodes and frontend interfaces\n- Real-time streaming event support for assistant messages, tool calls, and state updates\n- Human-in-the-loop workflow support through interrupt handling\n- Step tracking for real-time node execution progress monitoring\n- Full compatibility with LangGraph Cloud and local graph deployments\n\n资料来源：[integrations/langgraph/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/README.md)\n\n## Architecture\n\nThe integration follows a layered architecture that separates concerns between the agent runtime, state management, event streaming, and frontend communication.\n\n```mermaid\ngraph TD\n subgraph Frontend[\"Frontend Client\"]\n A[AG-UI Client]\n B[CopilotKit]\n C[Custom UI]\n end\n\n subgraph LangGraphIntegration[\"@ag-ui/langgraph\"]\n D[LangGraphAgent]\n E[State Streaming Middleware]\n F[Event Emitters]\n end\n\n subgraph LangGraph[\"LangGraph Runtime\"]\n G[Graph Definition]\n H[Graph Nodes]\n I[State Store]\n end\n\n A --> D\n B --> D\n C --> D\n D --> E\n E --> F\n F --> A\n G --> H\n H --> I\n I --> E\n```\n\n### Core Components\n\n| Component | Description | Package |\n|-----------|-------------|---------|\n| `LangGraphAgent` | Main agent class for connecting to LangGraph | `@ag-ui/langgraph` |\n| `StateStreamingMiddleware` | Middleware for state synchronization | `@ag-ui/langgraph` |\n| Event Emitters | Streams AG-UI protocol events to clients | `@ag-ui/core` |\n| Graph Store | LangGraph state persistence | `@langchain/langgraph-sdk` |\n\n资料来源：[integrations/langgraph/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/README.md)\n\n## Features\n\n### Cloud & Local Support\n\nThe integration operates seamlessly across two deployment modes:\n\n**Local Mode**: Connect directly to TypeScript or Python graph instances running locally. This mode provides full control over the graph execution and state management.\n\n**Cloud Mode**: Connect to remote LangGraph Cloud deployments via the LangGraph SDK. This mode leverages LangGraph's cloud infrastructure for scalability and reliability.\n\n```mermaid\ngraph LR\n subgraph Deployment[\"Deployment Options\"]\n L[Local Deployment]\n C[Cloud Deployment]\n end\n\n L -->|Direct Connection| AG[@ag-ui/langgraph]\n C -->|LangGraph SDK| AG\n\n AG -->|AG-UI Events| FE[Frontend]\n```\n\n资料来源：[integrations/langgraph/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/README.md)\n\n### State Management\n\nThe integration provides bidirectional state synchronization between the LangGraph state store and the AG-UI protocol:\n\n- **Read State**: Middleware reads graph state at configurable intervals or triggers\n- **Write State**: Frontend can update shared state through AG-UI state update events\n- **Conflict Resolution**: Last-write-wins semantics with optional optimistic updates\n\n```mermaid\nsequenceDiagram\n participant FE as Frontend\n participant MW as State Middleware\n participant GS as Graph State\n participant LG as LangGraph\n\n FE->>MW: subscribeToState()\n MW->>GS: getState()\n GS-->>MW: currentState\n MW-->>FE: stateUpdate event\n\n LG->>GS: updateState()\n GS-->>LG: stateUpdated\n LG->>MW: notifyChange()\n MW->>FE: stateUpdate event\n```\n\n资料来源：[integrations/langgraph/typescript/src/middlewares/state-streaming.ts](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/src/middlewares/state-streaming.ts)\n\n### Interrupt Handling\n\nHuman-in-the-loop workflows are supported through LangGraph's interrupt mechanism. When an interrupt occurs, the integration:\n\n1. Pauses graph execution at designated checkpoints\n2. Streams current state and pending actions to the frontend\n3. Waits for human approval/rejection/input\n4. Resumes execution with the provided feedback\n\n### Step Tracking\n\nReal-time progress updates track node execution through the graph:\n\n```typescript\ninterface StepUpdate {\n stepId: string;\n nodeName: string;\n status: 'pending' | 'running' | 'completed' | 'error';\n metadata?: Record;\n}\n```\n\n## Installation\n\n### TypeScript\n\n```bash\nnpm install @ag-ui/langgraph\npnpm add @ag-ui/langgraph\nyarn add @ag-ui/langgraph\n```\n\n**Peer Dependencies**:\n\n| Package | Version Requirement |\n|---------|---------------------|\n| `@ag-ui/core` | `>=0.0.42` |\n| `@ag-ui/client` | `>=0.0.42` |\n| `rxjs` | `7.8.1` |\n\n资料来源：[integrations/langgraph/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/package.json)\n\n### Python\n\n```bash\npip install ag-ui-langgraph\n```\n\n## Usage\n\n### TypeScript Example\n\n```typescript\nimport { LangGraphAgent } from \"@ag-ui/langgraph\";\n\n// Create an AG-UI compatible agent\nconst agent = new LangGraphAgent({\n graphId: \"my-graph\",\n deploymentUrl: \"https://your-langgraph-deployment.com\",\n langsmithApiKey: \"your-api-key\",\n});\n\n// Run with streaming\nconst result = await agent.runAgent({\n messages: [{ role: \"user\", content: \"Start the workflow\" }],\n});\n\n// Subscribe to state updates\nagent.subscribeToState((state) => {\n console.log(\"State updated:\", state);\n});\n```\n\n资料来源：[integrations/langgraph/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/README.md)\n\n### Python Example\n\n```python\nfrom ag_ui_langgraph import LangGraphAgent, AgentInput\n\nagent = LangGraphAgent(\n graph_id=\"my-graph\",\n deployment_url=\"https://your-langgraph-deployment.com\"\n)\n\nasync for event in agent.run_agent(AgentInput(\n messages=[{\"role\": \"user\", \"content\": \"Hello\"}]\n)):\n print(event)\n```\n\n资料来源：[integrations/langgraph/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/python/README.md)\n\n## Configuration Options\n\n### LangGraphAgent Configuration\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `graphId` | `string` | Yes | Identifier for the LangGraph graph |\n| `deploymentUrl` | `string` | No | LangGraph Cloud deployment URL (local if omitted) |\n| `langsmithApiKey` | `string` | No | API key for LangSmith observability |\n| `threadId` | `string` | No | Thread identifier for conversation state |\n| `stateMiddleware` | `StateMiddleware` | No | Custom state synchronization middleware |\n\n### State Streaming Middleware\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `pollInterval` | `number` | `1000` | Interval in ms for polling state changes |\n| `debounceMs` | `number` | `300` | Debounce delay for rapid state updates |\n| `includeMetadata` | `boolean` | `true` | Include node metadata in state updates |\n| `filterNodes` | `string[]` | `[]` | Only stream state for specific nodes |\n\n## Available Agents\n\nThe integration includes TypeScript examples demonstrating various agent patterns:\n\n### 1. Agentic Chat (`agentic_chat`)\n\nA simple agentic chat flow using LangGraph following the ReAct design pattern. Handles tool binding, system prompts, and model responses.\n\n### 2. Agentic Generative UI (`agentic_generative_ui`)\n\nDemonstrates agentic generative UI capabilities. Creates task steps and simulates their execution while streaming updates to the frontend.\n\n### 3. Human in the Loop (`human_in_the_loop`)\n\nImplements human-in-the-loop functionality where users can interact with and modify the agent's proposed steps before execution.\n\n### 4. Predictive State Updates (`predictive_state_updates`)\n\nShows predictive state updates for document writing with streaming tool calls to the frontend.\n\n### 5. Shared State (`shared_state`)\n\nDemonstrates shared state management between the agent and CopilotKit, focusing on recipe creation and modification.\n\n资料来源：[integrations/langgraph/typescript/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/examples/README.md)\n\n## Running the Examples\n\n### TypeScript Examples\n\n```bash\ncd integrations/langgraph/typescript/examples\n\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Start with LangGraph CLI\npnpx @langchain/langgraph-cli@1.1.13 dev\n```\n\n### Python Examples\n\n```bash\ncd integrations/langgraph/python/examples\n\n# Create .env file\ncp .env.example .env\n\n# Add your API keys\n# OPENAI_API_KEY=your-key\n\n# Install dependencies\npip install -e .\n\n# Run the server\npoetry run python -m server\n```\n\nThe server will start on `http://0.0.0.0:8003`.\n\n资料来源：[integrations/langgraph/typescript/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/examples/README.md)\n\n## Development\n\n### Build Commands\n\n| Command | Description |\n|---------|-------------|\n| `npm run build` | Compile TypeScript to JavaScript |\n| `npm run dev` | Watch mode for development |\n| `npm run typecheck` | Run TypeScript type checking |\n| `npm run test` | Run test suite |\n| `npm run test:coverage` | Run tests with coverage report |\n\n### Testing\n\n```bash\n# Run all tests\nnpm run test\n\n# Watch mode for development\nnpm run test:watch\n\n# Coverage report\nnpm run test:coverage\n\n# Export validation\nnpm run test:exports\n```\n\n## Dependencies\n\nThe integration depends on the following packages:\n\n| Package | Purpose |\n|---------|---------|\n| `@langchain/core` | Core LangChain functionality |\n| `@langchain/langgraph-sdk` | LangGraph SDK for cloud deployments |\n| `langchain` | LangChain integration |\n| `partial-json` | JSON parsing for partial responses |\n| `rxjs` | Reactive extensions for event streaming |\n\n资料来源：[integrations/langgraph/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/package.json)\n\n## Related Integrations\n\nFor other agent framework integrations, see the main integrations documentation:\n\n- **ADK Middleware**: Google Agent Development Kit integration\n- **PydanticAI**: PydanticAI agent integration\n- **Claude Agent SDK**: Anthropic Claude agent integration\n- **Langroid**: Multi-agent framework integration\n- **CrewAI**: CrewAI agent integration\n- **Mastra**: Mastra agent integration\n- **Agno**: Agno agent integration\n- **LlamaIndex**: LlamaIndex agent integration\n- **A2A Middleware**: Agent-to-Agent protocol middleware\n\n资料来源：[docs/integrations.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/integrations.mdx)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：ag-ui-protocol/ag-ui\n\n摘要：发现 13 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature]: Update Zod to ^4.0.0。\n\n## 1. 安装坑 · 来源证据：[Feature]: Update Zod to ^4.0.0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Update Zod to ^4.0.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_864feb35f0a7491399ed9e6f32d716d0 | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Java dependencies not found\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Java dependencies not found\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_76cfe35c206349ceb926d2253bc2cf03 | https://github.com/ag-ui-protocol/ag-ui/issues/930 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53c2f6a0605444afbd53e56d090a6295 | https://github.com/ag-ui-protocol/ag-ui/issues/1454 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 失败模式：installation: [Feature]: Update Zod to ^4.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Feature]: Update Zod to ^4.0.0\n- 对用户的影响：Developers may fail before the first successful local run: [Feature]: Update Zod to ^4.0.0\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_334526f2cd6ed9dc89c052647aa8d0eb | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | [Feature]: Update Zod to ^4.0.0\n\n## 5. 配置坑 · 失败模式：configuration: Java dependencies not found\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Java dependencies not found\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Java dependencies not found\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_cc82631789b14e6fa478fc47a467a6bd | https://github.com/ag-ui-protocol/ag-ui/issues/930 | Java dependencies not found\n\n## 6. 配置坑 · 失败模式：configuration: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- 建议检查：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\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 7. 配置坑 · 来源证据：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6674fe14155d4baeb366f4ac441fd962 | https://github.com/ag-ui-protocol/ag-ui/issues/1719 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | README/documentation is current enough for a first validation pass.\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | no_demo; severity=medium\n\n## 12. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | issue_or_pr_quality=unknown\n\n## 13. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | release_recency=unknown\n\n\n",
"markdown_key": "ag-ui",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:979392131",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/ag-ui-protocol/ag-ui"
},
{
"evidence_id": "art_40d43e18810e4fc4973533d757f33e48",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/ag-ui-protocol/ag-ui#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "ag-ui 说明书",
"toc": [
"https://github.com/ag-ui-protocol/ag-ui 项目说明书",
"目录",
"Introduction to AG-UI",
"Overview",
"Architecture",
"Event System",
"SDKs and Language Support",
"Tool Integration",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "5a00cde367d6bc881d83730280cceb219d54cc14",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"package.json",
"README.md",
"docs/package-lock.json",
"docs/talk-to-us.mdx",
"docs/integrations.mdx",
"docs/logo-alt.js",
"docs/pnpm-lock.yaml",
"docs/package.json",
"docs/README.md",
"docs/docs.json",
"docs/agentic-protocols.mdx",
"docs/ag_ui.md",
"docs/introduction.mdx",
"docs/concepts/middleware.mdx",
"docs/concepts/generative-ui-specs.mdx",
"docs/concepts/events.mdx",
"docs/concepts/interrupts.mdx",
"docs/concepts/serialization.mdx",
"docs/concepts/state.mdx",
"docs/concepts/capabilities.mdx",
"docs/concepts/architecture.mdx",
"docs/concepts/reasoning.mdx",
"docs/concepts/tools.mdx",
"docs/concepts/agents.mdx",
"docs/concepts/messages.mdx",
"docs/quickstart/clients.mdx",
"docs/quickstart/middleware.mdx",
"docs/quickstart/applications.mdx",
"docs/quickstart/introduction.mdx",
"docs/quickstart/server.mdx",
"docs/snippets/snippet-intro.mdx",
"docs/tutorials/cursor.mdx",
"docs/tutorials/debugging.mdx",
"docs/drafts/meta-events.mdx",
"docs/drafts/generative-ui.mdx",
"docs/drafts/overview.mdx",
"docs/development/roadmap.mdx",
"docs/development/contributing.mdx",
"docs/development/updates.mdx"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": [],
"semantic_rework": {
"status": "fallback_patched",
"identity": "agent_ui_protocol",
"source": "semantic_truth_gate"
}
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# ag-ui - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 ag-ui 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npx create-ag-ui-app my-agent-app` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`, `CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`, `CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：2076\n- 重要文件覆盖：40/2076\n- 证据索引条目：75\n- 角色 / Skill 条目：80\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 ag-ui 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 ag-ui 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 ag-ui 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 80 个角色 / Skill / 项目文档条目。\n\n- **Agent User Interaction Protocol Documentation**（project_doc）：Agent User Interaction Protocol Documentation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/README.md`\n- **General Guidelines for working with Nx**（project_doc）：General Guidelines for working with Nx 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **CLAUDE.md**（project_doc）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **AG-UI: The Agent-User Interaction Protocol**（project_doc）：AG-UI: The Agent-User Interaction Protocol 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **AG-UI CLI Example**（project_doc）：A command-line chat interface demonstrating the AG-UI client with a Mastra agent. This example shows how to build an interactive CLI application that streams agent responses and tool calls in real-time. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`apps/client-cli-example/README.md`\n- **AG-UI Protocol Dojo**（project_doc）：A modern, interactive viewer for exploring CopilotKit agent demos with a clean, responsive UI and dark/light theme support. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`apps/dojo/README.md`\n- **CopilotKit Demo Smoke Tests**（project_doc）：This repository houses Playwright-based smoke tests that run on a 6-hour schedule to make sure CopilotKit demo apps remain live and functional. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`apps/dojo/e2e/README.md`\n- **@ag-ui/a2a**（project_doc）：A TypeScript integration that connects AG-UI agents with remote services that expose the A2A protocol https://a2a.dev/ . It converts AG-UI conversations into A2A payloads, forwards them through the official A2A SDK, and replays the responses back into AG-UI event streams. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/a2a/typescript/README.md`\n- **CLAUDE.md**（project_doc）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/adk-middleware/python/CLAUDE.md`\n- **ADK Middleware for AG-UI Protocol**（project_doc）：This Python middleware enables Google ADK https://google.github.io/adk-docs/ agents to be used with the AG-UI Protocol, providing a bridge between the two frameworks. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/adk-middleware/python/README.md`\n- **ADK Middleware Examples**（project_doc）：This directory contains example implementations of the ADK middleware with FastAPI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/adk-middleware/python/examples/README.md`\n- **ADK Middleware for AG-UI Protocol**（project_doc）：This Python middleware enables Google ADK https://google.github.io/adk-docs/ agents to be used with the AG-UI Protocol, providing a bridge between the two frameworks. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/adk-middleware/typescript/README.md`\n- **AG2 AG-UI Example**（project_doc）：AG2 formerly AutoGen agent exposed via the AG-UI https://docs.ag2.ai/latest/docs/user-guide/ag-ui/ protocol for the Dojo. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/ag2/python/examples/README.md`\n- **@ag-ui/ag2**（project_doc）：AG-UI client for AG2 https://ag2.ai/ formerly AutoGen servers that expose the AG-UI protocol via AGUIStream . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/ag2/typescript/README.md`\n- **Install**（project_doc）：Open Agent Spec < AG‑UI Python ================================= 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/agent-spec/python/README.md`\n- **Open Agent Spec AG-UI Examples**（project_doc）：Open Agent Spec AG-UI Examples ================================ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/agent-spec/python/examples/README.md`\n- **Agno Finance Agent**（project_doc）：An Agno Agent with Finance tools for AG-UI that researches stock prices, analyst recommendations, and stock fundamentals. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/agno/python/examples/README.md`\n- **@ag-ui/agno**（project_doc）：Implementation of the AG-UI protocol for Agno. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/agno/typescript/README.md`\n- **AWS Strands Integration for AG-UI**（project_doc）：This package exposes a lightweight wrapper that lets any strands.Agent speak the AG-UI protocol. It mirrors the developer experience of the other integrations: give us a Strands agent instance, plug it into StrandsAgent , and wire it to FastAPI via create strands app or add strands fastapi endpoint . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/aws-strands/python/README.md`\n- **AWS Strands Example Server**（project_doc）：Demo FastAPI server that wires the Strands Agents SDK into the AG-UI protocol with support for multiple model providers OpenAI, Anthropic, Gemini . Each route mounts a ready-made agent that showcases different UI patterns vanilla chat, backend tool rendering, shared state, and generative UI . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/aws-strands/python/examples/README.md`\n- **Strands Integration TypeScript**（project_doc）：TypeScript client for the Strands integration using OpenAI models. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/aws-strands/typescript/README.md`\n- **ag-ui-claude-agent-sdk**（project_doc）：Implementation of the AG-UI protocol for the Anthropic Claude Agent SDK Python . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/claude-agent-sdk/python/README.md`\n- **Claude Agent SDK Examples**（project_doc）：bash Install dependencies cd ../ pip install -e . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/claude-agent-sdk/python/examples/README.md`\n- **@ag-ui/claude-agent-sdk**（project_doc）：Implementation of the AG-UI protocol for the Anthropic Claude Agent SDK TypeScript . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/claude-agent-sdk/typescript/README.md`\n- **AG-UI Genkit Integration Go**（project_doc）：Implementation of the AG-UI protocol for Firebase Genkit in Go. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/community/genkit/go/README.md`\n- **Genkit AG-UI Example Server**（project_doc）：This example demonstrates how to build an AG-UI compatible server using Firebase Genkit and Go. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/community/genkit/go/examples/README.md`\n- **@ag-ui/spring-ai**（project_doc）：Implementation of the AG-UI protocol for Spring AI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/community/spring-ai/typescript/README.md`\n- **ag-ui-crewai**（project_doc）：Implementation of the AG-UI protocol for CrewAI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/crew-ai/python/README.md`\n- **@ag-ui/crewai**（project_doc）：Implementation of the AG-UI protocol for CrewAI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/crew-ai/typescript/README.md`\n- **@ag-ui/langchain**（project_doc）：Implementation of the AG-UI protocol for LangChain. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/langchain/typescript/README.md`\n- **ag-ui-langgraph**（project_doc）：Implementation of the AG-UI protocol for LangGraph. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/langgraph/python/README.md`\n- **LangGraph examples**（project_doc）：First, make sure to create a new .env file from the .env.example and include the required keys. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/langgraph/python/examples/README.md`\n- **@ag-ui/langgraph**（project_doc）：Implementation of the AG-UI protocol for LangGraph. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/langgraph/typescript/README.md`\n- **LangGraph TypeScript Examples**（project_doc）：This directory contains TypeScript versions of the LangGraph examples, providing the same functionality as the Python examples but implemented in TypeScript. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/langgraph/typescript/examples/README.md`\n- **Langroid Integration for AG-UI**（project_doc）：Complete integration of Langroid with the AG-UI protocol, providing Python and TypeScript implementations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/langroid/README.md`\n- **ag-ui-langroid**（project_doc）：Implementation of the AG-UI protocol for Langroid. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/langroid/python/README.md`\n- **Readme**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/langroid/python/examples/README.md`\n- **@ag-ui/langroid**（project_doc）：TypeScript client integration for Langroid agents with AG-UI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/langroid/typescript/README.md`\n- **LlamaIndex Python AG-UI Integration**（project_doc）：LlamaIndex Python AG-UI Integration 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/llama-index/python/examples/README.md`\n- **@ag-ui/llamaindex**（project_doc）：Implementation of the AG-UI protocol for LlamaIndex. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/llama-index/typescript/README.md`\n- **@ag-ui/mastra**（project_doc）：Implementation of the AG-UI protocol for Mastra. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/mastra/typescript/README.md`\n- **Microsoft Agent Framework AG-UI Integration .NET**（project_doc）：Microsoft Agent Framework AG-UI Integration .NET 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/microsoft-agent-framework/dotnet/examples/README.md`\n- **Microsoft Agent Framework AG-UI Integration**（project_doc）：Microsoft Agent Framework AG-UI Integration 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/microsoft-agent-framework/python/examples/README.md`\n- **Pydantic AI AG-UI Examples**（project_doc）：This directory contains example usage of the AG-UI adapter for Pydantic AI. It provides a FastAPI application that demonstrates how to use the Pydantic AI agent with the AG-UI protocol. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/pydantic-ai/python/examples/README.md`\n- **Pydantic AI**（project_doc）：Implementation of the AG-UI protocol for Pydantic AI https://ai.pydantic.dev/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/pydantic-ai/typescript/README.md`\n- **Readme**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/server-starter-all-features/python/examples/README.md`\n- **Server Starter All Features**（project_doc）：This is a starter kit for demonstrating each feature of AG-UI by sending static events to the frontend. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/server-starter-all-features/typescript/README.md`\n- **Readme**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/server-starter/python/examples/README.md`\n- **Server Starter**（project_doc）：This starter kit demonstrates sending the minimal set of events that are needed to stream data from the agent to the frontend. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/server-starter/typescript/README.md`\n- **@ag-ui/vercel-ai-sdk**（project_doc）：Implementation of the AG-UI protocol for Vercel AI SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/vercel-ai-sdk/typescript/README.md`\n- **ag ui watsonx**（project_doc）：Python AG-UI adapter for IBM watsonx orchestrate agents. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/watsonx/python/README.md`\n- **@ag-ui/watsonx**（project_doc）：AG-UI integration for IBM watsonx orchestrate https://www.ibm.com/products/watsonx-orchestrate agents. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`integrations/watsonx/typescript/README.md`\n- **Middleware Starter**（project_doc）：This starter kit demonstrates how to set up a middleware server that can be used to proxy events from the agent to the frontend. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`middlewares/a2a-middleware/README.md`\n- **Readme**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`middlewares/a2a-middleware/examples/README.md`\n- **@ag-ui/mcp-apps-middleware**（project_doc）：MCP Apps middleware for AG-UI that enables UI-enabled tools from MCP Model Context Protocol servers. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`middlewares/mcp-apps-middleware/README.md`\n- **Middleware Starter**（project_doc）：This starter kit demonstrates how to set up a middleware server that can be used to proxy events from the agent to the frontend. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`middlewares/middleware-starter/README.md`\n- **AG-UI C++ SDK**（project_doc）：! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! C++17 https://img.shields.io/badge/C++-17-blue.svg https://en.cppreference.com/w/cpp/17 ! CMake https://img.shields.io/badge/CMake-3.10+-064F8C.svg https://cmake.org/ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/c++/README.md`\n- **ag-ui-dart**（project_doc）：Dart SDK for the Agent-User Interaction AG-UI Protocol . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/dart/README.md`\n- **AG-UI Dart Example: Tool Based Generative UI**（project_doc）：AG-UI Dart Example: Tool Based Generative UI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/dart/example/README.md`\n- **CLAUDE.md**（project_doc）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/CLAUDE.md`\n- **AG-UI**（project_doc）：Agent User Interaction Protocol for Java 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/README.md`\n- **AG-UI Ok-Http Client**（project_doc）：! Java https://img.shields.io/badge/Java-17-orange?logo=openjdk&logoColor=white ! Maven https://img.shields.io/badge/Maven-4.12.0-C71A36?logo=apachemaven&logoColor=white 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/clients/ok-http/README.md`\n- **Getting Started**（project_doc）：This is a Next.js https://nextjs.org project bootstrapped with create-next-app https://nextjs.org/docs/app/api-reference/cli/create-next-app . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/examples/copilot-app/README.md`\n- **AG-UI Spring-AI**（project_doc）：! Java https://img.shields.io/badge/Java-17-orange?logo=openjdk&logoColor=white ! Maven https://img.shields.io/badge/Maven-1.0.1-C71A36?logo=apachemaven&logoColor=white --- 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/integrations/spring-ai/README.md`\n- **Readme**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/packages/README.md`\n- **AG-UI Client**（project_doc）：! Java https://img.shields.io/badge/Java-17-orange?logo=openjdk&logoColor=white ! Maven https://img.shields.io/badge/Maven-0.0.1-C71A36?logo=apachemaven&logoColor=white 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/packages/client/README.md`\n- **AG-UI Core**（project_doc）：! Java https://img.shields.io/badge/Java-17-orange?logo=openjdk&logoColor=white ! Maven https://img.shields.io/badge/Maven-0.0.1-C71A36?logo=apachemaven&logoColor=white 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/packages/core/README.md`\n- **AG-UI HTTP**（project_doc）：! Java https://img.shields.io/badge/Java-17-orange?logo=openjdk&logoColor=white ! Maven https://img.shields.io/badge/Maven-0.0.1-C71A36?logo=apachemaven&logoColor=white 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/packages/http/README.md`\n- **AG-UI Server**（project_doc）：! Java https://img.shields.io/badge/Java-17-orange?logo=openjdk&logoColor=white ! Maven https://img.shields.io/badge/Maven-0.0.1-C71A36?logo=apachemaven&logoColor=white 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/packages/server/README.md`\n- **AG-UI Spring**（project_doc）：! Java https://img.shields.io/badge/Java-17-orange?logo=openjdk&logoColor=white ! Maven https://img.shields.io/badge/Maven-0.0.1-C71A36?logo=apachemaven&logoColor=white --- 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/servers/spring/README.md`\n- **AG-UI Json**（project_doc）：! Java https://img.shields.io/badge/Java-17-orange?logo=openjdk&logoColor=white ! Maven https://img.shields.io/badge/Maven-0.0.1-C71A36?logo=apachemaven&logoColor=white --- 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/java/utils/json/README.md`\n- **AG-UI Kotlin SDK**（project_doc）：! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! Kotlin https://img.shields.io/badge/kotlin-2.1.21-blue.svg?logo=kotlin http://kotlinlang.org ! Platform https://img.shields.io/badge/platform-Android%20%7C%20iOS%20%7C%20JVM-lightgrey https://kotlinlang.org/docs/multiplatform.html ! API https://img.shields.io/badge/API-26%2B-brightgreen.svg?style=flat https://and… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/kotlin/README.md`\n- **AG-UI Android Views Sample**（project_doc）：Android View-based chat client that consumes the shared Kotlin Multiplatform core chatapp-shared while keeping the UI in the traditional XML/ViewBinding stack. The screens remain Java-friendly, but the business logic, agent storage, and streaming behaviour now come directly from the shared Kotlin module used by the Compose and SwiftUI samples. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/kotlin/examples/chatapp-java/README.md`\n- **ChatApp Shared Core**（project_doc）：A Kotlin Multiplatform module that exposes the non-UI logic reused by the chat application samples. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/kotlin/examples/chatapp-shared/README.md`\n- **AG-UI Kotlin SDK SwiftUI Sample Client**（project_doc）：AG-UI Kotlin SDK SwiftUI Sample Client 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/kotlin/examples/chatapp-swiftui/README.md`\n- **ChatApp Wear OS Sample**（project_doc）：A standalone Wear OS sample that reuses the chatapp-shared Kotlin multiplatform core to deliver an AG-UI chat experience on a watch. The app demonstrates how to consume the shared networking, state, and tool-confirmation layers while rendering a Wear-optimized interface with androidx.wear.compose:compose-material3 . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/kotlin/examples/chatapp-wearos/README.md`\n- **AG-UI Kotlin SDK Compose Multiplatform Client**（project_doc）：AG-UI Kotlin SDK Compose Multiplatform Client 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/kotlin/examples/chatapp/README.md`\n- **iOS App for AG-UI Kotlin SDK Chat Client**（project_doc）：iOS App for AG-UI Kotlin SDK Chat Client 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/kotlin/examples/chatapp/iosApp/README.md`\n- **AG-UI Kotlin SDK**（project_doc）：A Kotlin Multiplatform implementation of the AG-UI Agent User Interaction Protocol, supporting JVM, Android, and iOS platforms. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/kotlin/library/README.md`\n- **ag-ui-protocol**（project_doc）：Ruby SDK for the Agent-User Interaction AG-UI Protocol . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`sdks/community/ruby/README.md`\n\n## 证据索引\n\n- 共索引 75 条证据。\n\n- **Agent User Interaction Protocol Documentation**（documentation）：Agent User Interaction Protocol Documentation 证据：`docs/README.md`\n- **General Guidelines for working with Nx**（documentation）：General Guidelines for working with Nx 证据：`AGENTS.md`\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`CLAUDE.md`\n- **AG-UI: The Agent-User Interaction Protocol**（documentation）：AG-UI: The Agent-User Interaction Protocol 证据：`README.md`\n- **AG-UI CLI Example**（documentation）：A command-line chat interface demonstrating the AG-UI client with a Mastra agent. This example shows how to build an interactive CLI application that streams agent responses and tool calls in real-time. 证据：`apps/client-cli-example/README.md`\n- **AG-UI Protocol Dojo**（documentation）：A modern, interactive viewer for exploring CopilotKit agent demos with a clean, responsive UI and dark/light theme support. 证据：`apps/dojo/README.md`\n- **CopilotKit Demo Smoke Tests**（documentation）：This repository houses Playwright-based smoke tests that run on a 6-hour schedule to make sure CopilotKit demo apps remain live and functional. 证据：`apps/dojo/e2e/README.md`\n- **@ag-ui/a2a**（documentation）：A TypeScript integration that connects AG-UI agents with remote services that expose the A2A protocol https://a2a.dev/ . It converts AG-UI conversations into A2A payloads, forwards them through the official A2A SDK, and replays the responses back into AG-UI event streams. 证据：`integrations/a2a/typescript/README.md`\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`integrations/adk-middleware/python/CLAUDE.md`\n- **ADK Middleware for AG-UI Protocol**（documentation）：This Python middleware enables Google ADK https://google.github.io/adk-docs/ agents to be used with the AG-UI Protocol, providing a bridge between the two frameworks. 证据：`integrations/adk-middleware/python/README.md`\n- **ADK Middleware Examples**（documentation）：This directory contains example implementations of the ADK middleware with FastAPI. 证据：`integrations/adk-middleware/python/examples/README.md`\n- **ADK Middleware for AG-UI Protocol**（documentation）：This Python middleware enables Google ADK https://google.github.io/adk-docs/ agents to be used with the AG-UI Protocol, providing a bridge between the two frameworks. 证据：`integrations/adk-middleware/typescript/README.md`\n- **AG2 AG-UI Example**（documentation）：AG2 formerly AutoGen agent exposed via the AG-UI https://docs.ag2.ai/latest/docs/user-guide/ag-ui/ protocol for the Dojo. 证据：`integrations/ag2/python/examples/README.md`\n- **@ag-ui/ag2**（documentation）：AG-UI client for AG2 https://ag2.ai/ formerly AutoGen servers that expose the AG-UI protocol via AGUIStream . 证据：`integrations/ag2/typescript/README.md`\n- **Install**（documentation）：Open Agent Spec < AG‑UI Python ================================= 证据：`integrations/agent-spec/python/README.md`\n- **Open Agent Spec AG-UI Examples**（documentation）：Open Agent Spec AG-UI Examples ================================ 证据：`integrations/agent-spec/python/examples/README.md`\n- **Agno Finance Agent**（documentation）：An Agno Agent with Finance tools for AG-UI that researches stock prices, analyst recommendations, and stock fundamentals. 证据：`integrations/agno/python/examples/README.md`\n- **@ag-ui/agno**（documentation）：Implementation of the AG-UI protocol for Agno. 证据：`integrations/agno/typescript/README.md`\n- **AWS Strands Integration for AG-UI**（documentation）：This package exposes a lightweight wrapper that lets any strands.Agent speak the AG-UI protocol. It mirrors the developer experience of the other integrations: give us a Strands agent instance, plug it into StrandsAgent , and wire it to FastAPI via create strands app or add strands fastapi endpoint . 证据：`integrations/aws-strands/python/README.md`\n- **AWS Strands Example Server**（documentation）：Demo FastAPI server that wires the Strands Agents SDK into the AG-UI protocol with support for multiple model providers OpenAI, Anthropic, Gemini . Each route mounts a ready-made agent that showcases different UI patterns vanilla chat, backend tool rendering, shared state, and generative UI . 证据：`integrations/aws-strands/python/examples/README.md`\n- **Strands Integration TypeScript**（documentation）：TypeScript client for the Strands integration using OpenAI models. 证据：`integrations/aws-strands/typescript/README.md`\n- **ag-ui-claude-agent-sdk**（documentation）：Implementation of the AG-UI protocol for the Anthropic Claude Agent SDK Python . 证据：`integrations/claude-agent-sdk/python/README.md`\n- **Claude Agent SDK Examples**（documentation）：bash Install dependencies cd ../ pip install -e . 证据：`integrations/claude-agent-sdk/python/examples/README.md`\n- **@ag-ui/claude-agent-sdk**（documentation）：Implementation of the AG-UI protocol for the Anthropic Claude Agent SDK TypeScript . 证据：`integrations/claude-agent-sdk/typescript/README.md`\n- **AG-UI Genkit Integration Go**（documentation）：Implementation of the AG-UI protocol for Firebase Genkit in Go. 证据：`integrations/community/genkit/go/README.md`\n- **Genkit AG-UI Example Server**（documentation）：This example demonstrates how to build an AG-UI compatible server using Firebase Genkit and Go. 证据：`integrations/community/genkit/go/examples/README.md`\n- **@ag-ui/spring-ai**（documentation）：Implementation of the AG-UI protocol for Spring AI. 证据：`integrations/community/spring-ai/typescript/README.md`\n- **ag-ui-crewai**（documentation）：Implementation of the AG-UI protocol for CrewAI. 证据：`integrations/crew-ai/python/README.md`\n- **@ag-ui/crewai**（documentation）：Implementation of the AG-UI protocol for CrewAI. 证据：`integrations/crew-ai/typescript/README.md`\n- **@ag-ui/langchain**（documentation）：Implementation of the AG-UI protocol for LangChain. 证据：`integrations/langchain/typescript/README.md`\n- **ag-ui-langgraph**（documentation）：Implementation of the AG-UI protocol for LangGraph. 证据：`integrations/langgraph/python/README.md`\n- **LangGraph examples**（documentation）：First, make sure to create a new .env file from the .env.example and include the required keys. 证据：`integrations/langgraph/python/examples/README.md`\n- **@ag-ui/langgraph**（documentation）：Implementation of the AG-UI protocol for LangGraph. 证据：`integrations/langgraph/typescript/README.md`\n- **LangGraph TypeScript Examples**（documentation）：This directory contains TypeScript versions of the LangGraph examples, providing the same functionality as the Python examples but implemented in TypeScript. 证据：`integrations/langgraph/typescript/examples/README.md`\n- **Langroid Integration for AG-UI**（documentation）：Complete integration of Langroid with the AG-UI protocol, providing Python and TypeScript implementations. 证据：`integrations/langroid/README.md`\n- **ag-ui-langroid**（documentation）：Implementation of the AG-UI protocol for Langroid. 证据：`integrations/langroid/python/README.md`\n- **@ag-ui/langroid**（documentation）：TypeScript client integration for Langroid agents with AG-UI. 证据：`integrations/langroid/typescript/README.md`\n- **LlamaIndex Python AG-UI Integration**（documentation）：LlamaIndex Python AG-UI Integration 证据：`integrations/llama-index/python/examples/README.md`\n- **@ag-ui/llamaindex**（documentation）：Implementation of the AG-UI protocol for LlamaIndex. 证据：`integrations/llama-index/typescript/README.md`\n- **@ag-ui/mastra**（documentation）：Implementation of the AG-UI protocol for Mastra. 证据：`integrations/mastra/typescript/README.md`\n- **Microsoft Agent Framework AG-UI Integration .NET**（documentation）：Microsoft Agent Framework AG-UI Integration .NET 证据：`integrations/microsoft-agent-framework/dotnet/examples/README.md`\n- **Microsoft Agent Framework AG-UI Integration**（documentation）：Microsoft Agent Framework AG-UI Integration 证据：`integrations/microsoft-agent-framework/python/examples/README.md`\n- **Pydantic AI AG-UI Examples**（documentation）：This directory contains example usage of the AG-UI adapter for Pydantic AI. It provides a FastAPI application that demonstrates how to use the Pydantic AI agent with the AG-UI protocol. 证据：`integrations/pydantic-ai/python/examples/README.md`\n- **Pydantic AI**（documentation）：Implementation of the AG-UI protocol for Pydantic AI https://ai.pydantic.dev/ . 证据：`integrations/pydantic-ai/typescript/README.md`\n- **Server Starter All Features**（documentation）：This is a starter kit for demonstrating each feature of AG-UI by sending static events to the frontend. 证据：`integrations/server-starter-all-features/typescript/README.md`\n- **Server Starter**（documentation）：This starter kit demonstrates sending the minimal set of events that are needed to stream data from the agent to the frontend. 证据：`integrations/server-starter/typescript/README.md`\n- **@ag-ui/vercel-ai-sdk**（documentation）：Implementation of the AG-UI protocol for Vercel AI SDK. 证据：`integrations/vercel-ai-sdk/typescript/README.md`\n- **ag ui watsonx**（documentation）：Python AG-UI adapter for IBM watsonx orchestrate agents. 证据：`integrations/watsonx/python/README.md`\n- **@ag-ui/watsonx**（documentation）：AG-UI integration for IBM watsonx orchestrate https://www.ibm.com/products/watsonx-orchestrate agents. 证据：`integrations/watsonx/typescript/README.md`\n- **Middleware Starter**（documentation）：This starter kit demonstrates how to set up a middleware server that can be used to proxy events from the agent to the frontend. 证据：`middlewares/a2a-middleware/README.md`\n- **@ag-ui/mcp-apps-middleware**（documentation）：MCP Apps middleware for AG-UI that enables UI-enabled tools from MCP Model Context Protocol servers. 证据：`middlewares/mcp-apps-middleware/README.md`\n- **Middleware Starter**（documentation）：This starter kit demonstrates how to set up a middleware server that can be used to proxy events from the agent to the frontend. 证据：`middlewares/middleware-starter/README.md`\n- **AG-UI C++ SDK**（documentation）：! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg https://opensource.org/licenses/MIT ! C++17 https://img.shields.io/badge/C++-17-blue.svg https://en.cppreference.com/w/cpp/17 ! CMake https://img.shields.io/badge/CMake-3.10+-064F8C.svg https://cmake.org/ 证据：`sdks/community/c++/README.md`\n- **ag-ui-dart**（documentation）：Dart SDK for the Agent-User Interaction AG-UI Protocol . 证据：`sdks/community/dart/README.md`\n- **AG-UI Dart Example: Tool Based Generative UI**（documentation）：AG-UI Dart Example: Tool Based Generative UI 证据：`sdks/community/dart/example/README.md`\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`sdks/community/java/CLAUDE.md`\n- **AG-UI**（documentation）：Agent User Interaction Protocol for Java 证据：`sdks/community/java/README.md`\n- **AG-UI Ok-Http Client**（documentation）：! Java https://img.shields.io/badge/Java-17-orange?logo=openjdk&logoColor=white ! Maven https://img.shields.io/badge/Maven-4.12.0-C71A36?logo=apachemaven&logoColor=white 证据：`sdks/community/java/clients/ok-http/README.md`\n- **Getting Started**（documentation）：This is a Next.js https://nextjs.org project bootstrapped with create-next-app https://nextjs.org/docs/app/api-reference/cli/create-next-app . 证据：`sdks/community/java/examples/copilot-app/README.md`\n- **AG-UI Spring-AI**（documentation）：! Java https://img.shields.io/badge/Java-17-orange?logo=openjdk&logoColor=white ! Maven https://img.shields.io/badge/Maven-1.0.1-C71A36?logo=apachemaven&logoColor=white --- 证据：`sdks/community/java/integrations/spring-ai/README.md`\n- 其余 15 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `AGENTS.md`, `CLAUDE.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `AGENTS.md`, `CLAUDE.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Introduction to AG-UI**：importance `high`\n - source_paths: README.md, docs/introduction.mdx, docs/concepts/architecture.mdx\n- **System Architecture**：importance `high`\n - source_paths: docs/concepts/architecture.mdx, docs/ag_ui.md, docs/concepts/capabilities.mdx\n- **The Agent Protocol Stack**：importance `medium`\n - source_paths: docs/agentic-protocols.mdx, docs/integrations.mdx, docs/concepts/tools.mdx\n- **Event Specification**：importance `high`\n - source_paths: sdks/typescript/packages/core/src/events.ts, sdks/typescript/packages/core/src/event-factories.ts, sdks/python/ag_ui/core/events.py, docs/concepts/events.mdx\n- **Types & Messages**：importance `high`\n - source_paths: sdks/typescript/packages/core/src/types.ts, sdks/typescript/packages/proto/src/generated/types.ts, sdks/python/ag_ui/core/types.py, docs/concepts/messages.mdx, docs/concepts/serialization.mdx\n- **Capabilities System**：importance `medium`\n - source_paths: sdks/typescript/packages/core/src/capabilities.ts, sdks/python/ag_ui/core/capabilities.py, docs/concepts/capabilities.mdx, docs/concepts/generative-ui-specs.mdx\n- **TypeScript SDK**：importance `high`\n - source_paths: sdks/typescript/packages/core/README.md, sdks/typescript/packages/client/README.md, sdks/typescript/packages/client/src/agent/agent.ts, sdks/typescript/packages/client/src/agent/http.ts, sdks/typescript/packages/client/src/middleware/middleware.ts\n- **Python SDK**：importance `high`\n - source_paths: sdks/python/README.md, sdks/python/ag_ui/__init__.py, sdks/python/ag_ui/core/events.py, sdks/python/ag_ui/core/types.py, sdks/python/ag_ui/encoder/encoder.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `5a00cde367d6bc881d83730280cceb219d54cc14`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docs/package-lock.json`, `docs/talk-to-us.mdx`, `docs/integrations.mdx`, `docs/logo-alt.js`, `docs/pnpm-lock.yaml`, `docs/package.json`, `docs/README.md`, `docs/docs.json`, `docs/agentic-protocols.mdx`, `docs/ag_ui.md`, `docs/introduction.mdx`, `docs/concepts/middleware.mdx`, `docs/concepts/generative-ui-specs.mdx`, `docs/concepts/events.mdx`, `docs/concepts/interrupts.mdx`, `docs/concepts/serialization.mdx`, `docs/concepts/state.mdx`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：[Feature]: Update Zod to ^4.0.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Update Zod to ^4.0.0\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_864feb35f0a7491399ed9e6f32d716d0 | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Java dependencies not found\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Java dependencies not found\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_76cfe35c206349ceb926d2253bc2cf03 | https://github.com/ag-ui-protocol/ag-ui/issues/930 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_53c2f6a0605444afbd53e56d090a6295 | https://github.com/ag-ui-protocol/ag-ui/issues/1454 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 失败模式：installation: [Feature]: Update Zod to ^4.0.0\n\n- Trigger: Developers should check this installation risk before relying on the project: [Feature]: Update Zod to ^4.0.0\n- Host AI rule: 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.\n- Why it matters: Developers may fail before the first successful local run: [Feature]: Update Zod to ^4.0.0\n- Evidence: failure_mode_cluster:github_issue | fmev_334526f2cd6ed9dc89c052647aa8d0eb | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | [Feature]: Update Zod to ^4.0.0\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 失败模式：configuration: Java dependencies not found\n\n- Trigger: Developers should check this configuration risk before relying on the project: Java dependencies not found\n- Host AI rule: 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.\n- Why it matters: Developers may misconfigure credentials, environment, or host setup: Java dependencies not found\n- Evidence: failure_mode_cluster:github_issue | fmev_cc82631789b14e6fa478fc47a467a6bd | https://github.com/ag-ui-protocol/ag-ui/issues/930 | Java dependencies not found\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 失败模式：configuration: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n\n- Trigger: Developers should check this configuration risk before relying on the project: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- Host AI rule: 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\n- Why it matters: Developers may misconfigure credentials, environment, or host setup: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- Evidence: 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\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_6674fe14155d4baeb366f4ac441fd962 | https://github.com/ag-ui-protocol/ag-ui/issues/1719 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：ag-ui-protocol/ag-ui\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：[Feature]: Update Zod to ^4.0.0（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Java dependencies not found（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 失败模式：installation: [Feature]: Update Zod to ^4.0.0（medium）：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.\n- 失败模式：configuration: Java dependencies not found（medium）：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.\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/ag-ui-protocol/ag-ui 项目说明书\n\n生成时间：2026-05-18 03:33:32 UTC\n\n## 目录\n\n- [Introduction to AG-UI](#intro)\n- [System Architecture](#architecture)\n- [The Agent Protocol Stack](#protocol-stack)\n- [Event Specification](#events)\n- [Types & Messages](#types-messages)\n- [Capabilities System](#capabilities)\n- [TypeScript SDK](#typescript-sdk)\n- [Python SDK](#python-sdk)\n- [Community SDKs](#community-sdks)\n- [LangGraph Integration](#langgraph-integration)\n\n\n\n## Introduction to AG-UI\n\n### 相关页面\n\n相关主题：[The Agent Protocol Stack](#protocol-stack), [Event Specification](#events)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n- [sdks/typescript/packages/cli/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/cli/README.md)\n- [sdks/community/ruby/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/ruby/README.md)\n- [sdks/community/dart/example/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/dart/example/README.md)\n- [sdks/community/c++/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/c++/README.md)\n- [integrations/adk-middleware/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/adk-middleware/python/README.md)\n- [integrations/langroid/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/README.md)\n- [integrations/pydantic-ai/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/pydantic-ai/typescript/README.md)\n- [integrations/ag2/python/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/ag2/python/examples/README.md)\n \n\n# Introduction to AG-UI\n\n**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.\n\n## Overview\n\nAG-UI provides a standardized way for agents to stream events to clients, supporting features like:\n\n- Real-time text message streaming\n- Tool execution and results rendering\n- State synchronization between agent and client\n- Run lifecycle management\n- Multi-step agentic workflows\n\n资料来源：[sdks/typescript/packages/core/README.md:1-5]()\n\n## Architecture\n\nAG-UI follows a client-server architecture where the agent backend streams events to the client using Server-Sent Events (SSE).\n\n```mermaid\ngraph TD\n A[Agent Backend] -->|SSE Events| B[AG-UI Protocol]\n B --> C[Client Applications]\n D[State Updates] <--> B\n E[Tool Calls] <--> B\n C -->|User Input| A\n```\n\n### Core Components\n\n| Component | Description |\n|-----------|-------------|\n| **Event Stream** | Server-Sent Events (SSE) for real-time streaming |\n| **State Management** | Bidirectional state synchronization |\n| **Tool System** | Agent tools exposed to clients and vice versa |\n| **Run Lifecycle** | Management of agent execution runs |\n\n资料来源：[sdks/typescript/packages/core/README.md:10-18]()\n\n## Event System\n\nThe AG-UI protocol defines 16 core event kinds covering the full agent interaction lifecycle.\n\n### Event Categories\n\n| Category | Events | Purpose |\n|----------|--------|---------|\n| **Messages** | `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END` | Stream text responses |\n| **Lifecycle** | `RUN_STARTED`, `RUN_FINISHED` | Track agent execution |\n| **State** | `STATE_SNAPSHOT`, `STATE_DELTA` | Synchronize application state |\n| **Tools** | `TOOL_CALL_START`, `TOOL_CALL_END`, `TOOL_CALL_RESULT` | Execute and display tool results |\n\n资料来源：[sdks/typescript/packages/core/README.md:14-15]()\n\n### Runtime Validation\n\nEvents are validated using schemas that catch malformed payloads early:\n\n```ts\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n资料来源：[sdks/typescript/packages/core/README.md:29-35]()\n\n## SDKs and Language Support\n\nAG-UI provides official and community SDKs for multiple programming languages:\n\n### Official SDKs\n\n| SDK | Language | Status | Purpose |\n|-----|----------|--------|---------|\n| `@ag-ui/core` | TypeScript | Official | Type definitions & runtime schemas |\n| `create-ag-ui-app` | TypeScript | Official | CLI scaffolding tool |\n\n### Community SDKs\n\n| SDK | Language | Package |\n|-----|----------|---------|\n| Ruby SDK | Ruby | Community maintained |\n| Dart SDK | Dart | Community maintained |\n| C++ SDK | C++ | Community maintained |\n| Java SDK | Java | Community maintained |\n| Kotlin SDK | Kotlin | Community maintained |\n| Go SDK | Go | Community maintained |\n\n资料来源：[sdks/typescript/packages/core/README.md:1-50]()\n\n资料来源：[sdks/community/c++/README.md:1-100]()\n\n资料来源：[sdks/community/java/packages/client/README.md:1-20]()\n\n## Tool Integration\n\nAG-UI supports bidirectional tool access where agents can call client-side tools and clients can execute server-side tools.\n\n```python\n# Example: Agent accessing client-side tools (ADK Middleware)\ntools=[\n AGUIToolset(tool_filter=lambda tool, readonly_context=None: tool.name.endswith('Goodbye'))\n]\n```\n\n资料来源：[integrations/adk-middleware/python/README.md:1-50]()\n\n### Tool Naming Convention\n\nTools can be filtered by naming patterns, allowing agents to selectively expose or access tools based on their suffixes or prefixes.\n\n资料来源：[integrations/adk-middleware/python/README.md:45-47]()\n\n## Framework Integrations\n\nAG-UI integrates with multiple AI agent frameworks:\n\n| Framework | Type | Documentation |\n|-----------|------|---------------|\n| **LangGraph** | Python | Scaffolding via CLI |\n| **CrewAI** | Python | Scaffolding via CLI |\n| **Mastra** | TypeScript | Scaffolding via CLI |\n| **Agno** | Python | Scaffolding via CLI |\n| **LlamaIndex** | Python | Scaffolding via CLI |\n| **Pydantic AI** | Python/TypeScript | Integration package |\n| **ADK (Google)** | Python/TypeScript | Middleware integration |\n| **Langroid** | Python/TypeScript | Full integration |\n| **Genkit** | Go | Community integration |\n| **AG2 (AutoGen)** | Python | Example integration |\n\n资料来源：[sdks/typescript/packages/cli/README.md:30-40]()\n\n资料来源：[integrations/langroid/README.md:1-30]()\n\n资料来源：[integrations/pydantic-ai/typescript/README.md:1-50]()\n\n## Getting Started\n\n### Quick Start with CLI\n\n```bash\nnpx create-ag-ui-app@latest\n```\n\nThe CLI provides an interactive setup wizard supporting:\n- CopilotKit/Next.js for web applications\n- CLI clients for terminal-based interactions\n- Automatic dependency installation and project structure setup\n\n资料来源：[sdks/typescript/packages/cli/README.md:1-40]()\n\n### Environment Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AG_UI_BASE_URL` | Base URL of the AG-UI server | `http://127.0.0.1:8000` |\n| `AG_UI_API_KEY` | API key for authentication | None |\n| `DEBUG` | Enable debug logging | `false` |\n\n资料来源：[sdks/community/dart/example/README.md:50-60]()\n\n## Protocol Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant AGUI as AG-UI Protocol\n participant Agent as Agent Backend\n \n Client->>Agent: Send user message\n Agent->>AGUI: Emit RUN_STARTED\n Agent->>AGUI: Emit TEXT_MESSAGE_START\n Agent->>AGUI: Emit TEXT_MESSAGE_CONTENT (streaming)\n Note over Agent,AGUI: Tool execution if needed\n Agent->>AGUI: Emit STATE_DELTA\n Agent->>AGUI: Emit TEXT_MESSAGE_END\n Agent->>AGUI: Emit RUN_FINISHED\n AGUI->>Client: Stream events via SSE\n```\n\n## Documentation Resources\n\n| Resource | Link |\n|----------|------|\n| Concepts & Architecture | [docs/concepts](https://docs.ag-ui.com/concepts/architecture) |\n| API Reference | [docs/events](https://docs.ag-ui.com/concepts/events) |\n| Ruby SDK Docs | `rake doc` in `sdks/community/ruby` |\n| Contributing Guide | [CONTRIBUTING.md](https://docs.ag-ui.com/development/contributing) |\n\n资料来源：[sdks/typescript/packages/core/README.md:40-45]()\n\n资料来源：[sdks/community/ruby/README.md:1-30]()\n\n## License\n\nAG-UI Protocol is licensed under the **MIT License** © 2025 AG-UI Protocol Contributors.\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Event Specification](#events), [TypeScript SDK](#typescript-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n- [sdks/typescript/packages/cli/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/cli/README.md)\n- [sdks/community/c++/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/c++/README.md)\n- [integrations/adk-middleware/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/adk-middleware/python/README.md)\n- [integrations/claude-agent-sdk/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/typescript/README.md)\n- [sdks/community/java/packages/client/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/client/README.md)\n- [sdks/community/java/packages/server/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/server/README.md)\n- [integrations/langroid/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/README.md)\n- [integrations/pydantic-ai/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/pydantic-ai/typescript/README.md)\n \n\n# System Architecture\n\nThe 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.\n\n## Overview\n\nAG-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.\n\n资料来源：[sdks/typescript/packages/core/README.md]()\n\n### Core Design Principles\n\nThe system architecture is built on several foundational principles that guide its implementation across all supported languages and frameworks:\n\n**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.\n\n**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.\n\n**Runtime Validation**: Schemas are implemented to catch malformed payloads early, ensuring data integrity throughout the communication pipeline.\n\n## High-Level Architecture\n\nThe AG-UI system consists of several interconnected layers that work together to provide a complete agent-user interaction framework.\n\n```mermaid\ngraph TD\n subgraph Client[\"Client Layer\"]\n FE[Frontend Client]\n Tools[Client Tools]\n State[State Management]\n end\n \n subgraph Protocol[\"Protocol Layer\"]\n Events[Event Schemas]\n Types[Type Definitions]\n Validation[Runtime Validation]\n end\n \n subgraph Agent[\"Agent Layer\"]\n LLM[LLM Agent]\n ServerTools[Server Tools]\n SubAgents[Sub-Agents]\n end\n \n subgraph Transport[\"Transport Layer\"]\n HTTP[HTTP/WebSocket]\n SSE[Server-Sent Events]\n end\n \n FE --> Protocol\n Tools --> Protocol\n Protocol --> Transport\n Transport --> Agent\n ServerTools --> LLM\n SubAgents --> LLM\n State <--> Agent\n```\n\n资料来源：[sdks/typescript/packages/core/README.md]()\n\n## Core Components\n\n### Protocol Layer\n\nThe protocol layer forms the backbone of the AG-UI system, providing the type definitions and event schemas that all other components depend upon.\n\n#### Event Schemas\n\nThe `@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.\n\n资料来源：[sdks/typescript/packages/core/README.md]()\n\n| Event Category | Description | Key Events |\n|----------------|-------------|------------|\n| Message Events | Text and content streaming | TEXT_MESSAGE_START, TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END |\n| Tool Events | Tool invocation and results | TOOL_CALL_START, TOOL_CALL_ARGS, TOOL_CALL_END |\n| State Events | State synchronization | STATE_UPDATE, STATE_SNAPSHOT |\n| Lifecycle Events | Run management | RUN_STARTED, RUN_FINISHED, MESSAGES_SNAPSHOT |\n\n#### Event Validation\n\nRuntime validation is provided through schema parsing, allowing incoming events to be validated against their expected structure:\n\n```typescript\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n### Agent Layer\n\nThe agent layer encompasses the server-side implementations that process user requests and generate responses.\n\n#### TypeScript Agent Implementation\n\nThe 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.\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md]()\n\n#### Python Agent Integration\n\nPython-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.\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n\n#### Java Agent Components\n\nThe Java SDK provides both client and server implementations:\n\n- **AbstractAgent**: Base class for agent implementations\n- **LocalAgent**: Concrete implementation for local agent execution\n\n资料来源：[sdks/community/java/packages/server/README.md]()\n\n### Client Layer\n\nThe client layer handles frontend interactions, tool exposure, and state management.\n\n#### Client Tools\n\nClients can expose tools to agents through a toolset mechanism. Tools are filtered and exposed based on configuration, allowing selective tool availability:\n\n```python\nAGUIToolset(tool_filter=lambda tool, readonly_context=None: tool.name.endswith('Goodbye'))\n```\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n\n#### State Management\n\nState synchronization between client and server enables collaborative workflows. The bidirectional state sync mechanism ensures that both frontend and backend maintain consistent state views.\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md]()\n\n## SDK Architecture by Language\n\n### TypeScript SDK\n\nThe TypeScript SDK is organized into multiple packages that can be used independently or together:\n\n```mermaid\ngraph LR\n subgraph TypeScript_SDK[\"TypeScript SDK\"]\n Core[\"@ag-ui/core\"] --> CLI[\"@ag-ui/cli\"]\n Core --> Client[\"Client Libraries\"]\n Core --> Server[\"Server Libraries\"]\n CLI --> Integrations[\"Framework Integrations\"]\n end\n```\n\n| Package | Purpose |\n|---------|---------|\n| @ag-ui/core | Type definitions and event schemas |\n| @ag-ui/cli | Command-line tools for development |\n| @ag-ui/client | Client-side event handling |\n| @ag-ui/server | Server-side agent implementation |\n\n资料来源：[sdks/typescript/packages/core/README.md]()\n资料来源：[sdks/typescript/packages/cli/README.md]()\n\n### Python SDK\n\nThe Python ecosystem supports multiple agent frameworks through middleware adapters:\n\n| Integration | Framework | Features |\n|-------------|-----------|----------|\n| ADK Middleware | Google ADK | Tool support, state sync |\n| Pydantic AI | Pydantic AI | Agentic chat, backend tools |\n| Langroid | Langroid | Multi-agent orchestration |\n| AG2 | AutoGen | Agent collaboration |\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n资料来源：[integrations/pydantic-ai/typescript/README.md]()\n\n### Multi-Language Support\n\nThe AG-UI protocol maintains consistent implementations across multiple programming languages, each following the same architectural patterns:\n\n| Language | Client | Server | Status |\n|----------|--------|--------|--------|\n| TypeScript | ✅ | ✅ | Primary |\n| Python | ✅ | ✅ | Primary |\n| Java | ✅ | ✅ | Community |\n| Ruby | ✅ | - | Community |\n| Dart | ✅ | - | Community |\n| C++ | ✅ | - | Community |\n| Go | - | ✅ | Community |\n\n资料来源：[sdks/community/java/packages/client/README.md]()\n资料来源：[sdks/community/c++/README.md]()\n\n## Communication Flow\n\n### Event Streaming Model\n\nThe 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.\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Protocol\n participant Agent\n participant LLM\n \n Client->>Agent: POST /agent/run (RunAgentInput)\n Agent->>LLM: Query LLM\n LLM-->>Agent: Streaming Response\n Agent->>Protocol: Emit Events\n Protocol->>Client: Stream Events\n \n Note over Client,LLM: Real-time event emission during inference\n```\n\n### Tool Call Flow\n\nTool invocations follow a specific sequence that enables both server-side and client-side tool execution:\n\n```mermaid\ngraph TD\n Start[LLM Requests Tool] --> Filter{Check Tool Type}\n Filter -->|Server Tool| ServerExec[Execute Server Tool]\n Filter -->|Client Tool| ClientExec[Execute Client Tool]\n \n ServerExec --> ServerResult[Return Result]\n ClientExec --> Pause[Pause Stream]\n Pause --> Execute[Client Executes Tool]\n Execute --> Resume[Resume Stream]\n Resume --> FinalResult[Final Response]\n \n ServerResult --> FinalResult\n```\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md]()\n\n### State Synchronization\n\nState management in AG-UI supports bidirectional synchronization between client and server:\n\n```mermaid\ngraph LR\n subgraph Client_State\n CS1[State View]\n CS2[State Mutation]\n end\n \n subgraph Server_State\n SS1[Canonical State]\n SS2[State Processing]\n end\n \n CS1 <-->|STATE_UPDATE| SS1\n CS2 -->|Mutation Event| SS2\n SS2 -->|State Confirmation| CS1\n```\n\n## Framework Integrations\n\n### Claude Agent SDK Integration\n\nThe Claude Agent SDK adapter provides comprehensive AG-UI protocol support for Anthropic Claude models:\n\n```typescript\nimport { ClaudeAgentAdapter } from \"@ag-ui/claude-agent-sdk\";\n\nconst adapter = new ClaudeAgentAdapter({\n agentId: \"my_agent\",\n model: \"claude-haiku-4-5\",\n systemPrompt: \"You are helpful\",\n});\n\nconst events$ = adapter.run(input);\n```\n\nKey features include full lifecycle management, interrupt support, dynamic frontend tool exposure, streaming tool arguments, and automatic event cleanup.\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md]()\n\n### ADK Middleware\n\nThe ADK middleware integrates Google Agent Development Kit with AG-UI, providing:\n\n- **271 comprehensive tests** covering all protocol features\n- Tool support with automatic exposure to frontend clients\n- State synchronization between frontend and backend\n- Sub-agent orchestration capabilities\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n\n### Langroid Integration\n\nLangroid provides a multi-agent orchestration system with AG-UI support:\n\n```mermaid\ngraph TD\n subgraph Langroid_System\n Orchestrator[Orchestrator Agent]\n Sub1[Specialist Agent 1]\n Sub2[Specialist Agent 2]\n Tools[Tool Registry]\n end\n \n Orchestrator --> Sub1\n Orchestrator --> Sub2\n Sub1 --> Tools\n Sub2 --> Tools\n```\n\nThe integration includes both Python server implementations and TypeScript client libraries for frontend communication.\n\n资料来源：[integrations/langroid/README.md]()\n\n## Development Tools\n\n### CLI Tools\n\nThe AG-UI CLI provides development utilities for creating and managing AG-UI applications:\n\n```bash\nnpx create-ag-ui-app@latest --help\n```\n\n资料来源：[sdks/typescript/packages/cli/README.md]()\n\n### Testing Infrastructure\n\nComprehensive testing is available across all SDK implementations. For example, the ADK Middleware includes 271 tests that verify protocol compliance and feature functionality:\n\n```bash\n# Run tests with coverage\npytest --cov=src/adk_middleware\n```\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n\n## Architecture Patterns\n\n### Builder Pattern for Agents\n\nMany SDK implementations use the builder pattern for agent configuration:\n\n```cpp\n#include \"agent/http_agent.h\"\n\nauto agent = HttpAgent::builder()\n .withUrl(\"http://localhost:8080/api/agent/run\")\n .withAgentId(AgentId(\"my-agent\"))\n .build();\n```\n\nThis pattern provides a fluent interface for configuring agent properties while maintaining immutability of the final agent instance.\n\n资料来源：[sdks/community/c++/README.md]()\n\n### Observable Pattern for Events\n\nThe TypeScript SDK and integrations use RxJS Observables for event streaming, allowing clients to subscribe to event streams with familiar patterns:\n\n```typescript\nevents$.subscribe({\n next: (event) => sendEvent(event),\n complete: () => res.end(),\n});\n```\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md]()\n\n## Security Considerations\n\n### API Key Management\n\nThe protocol supports API key authentication for securing agent endpoints:\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| AG_UI_BASE_URL | Base URL of the AG-UI server | http://127.0.0.1:8000 |\n| AG_UI_API_KEY | API key for authentication | None |\n| DEBUG | Enable debug logging | false |\n\n资料来源：[sdks/community/dart/example/README.md]()\n\n### Tool Exposure Control\n\nTools can be selectively exposed to agents using filter functions, preventing unauthorized access to sensitive client-side capabilities:\n\n```python\nAGUIToolset(tool_filter=lambda tool, readonly_context=None: tool.name.endswith('Goodbye'))\n```\n\n资料来源：[integrations/adk-middleware/python/README.md]()\n\n## Summary\n\nThe AG-UI Protocol architecture provides a robust, framework-agnostic foundation for building agent-user interaction systems. Its key architectural elements include:\n\n- **Event-driven communication** with 16 core event kinds for comprehensive state management\n- **Multi-language SDK support** spanning TypeScript, Python, Java, Ruby, Dart, C++, and Go\n- **Framework integrations** for ADK, Pydantic AI, Langroid, Claude Agent SDK, and AG2\n- **Runtime validation** ensuring data integrity across the communication pipeline\n- **Flexible tool exposure** mechanisms for controlled tool access\n- **Bidirectional state synchronization** enabling collaborative workflows\n\nThe architecture's modular design allows developers to use individual components independently or together, providing maximum flexibility for different use cases and technical requirements.\n\n---\n\n\n\n## The Agent Protocol Stack\n\n### 相关页面\n\n相关主题：[Introduction to AG-UI](#intro), [Event Specification](#events)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n- [integrations/claude-agent-sdk/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/typescript/README.md)\n- [integrations/claude-agent-sdk/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/python/README.md)\n- [sdks/community/genkit/go/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/community/genkit/go/examples/README.md)\n- [integrations/server-starter-all-features/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/server-starter-all-features/typescript/README.md)\n- [sdks/community/java/packages/server/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/server/README.md)\n- [sdks/community/java/packages/client/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/client/README.md)\n \n\n# The Agent Protocol Stack\n\nThe 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.\n\n## Overview\n\nThe AG-UI Protocol defines how agents communicate with frontend applications through a streaming event-based mechanism. The protocol stack encompasses:\n\n| Layer | Description |\n|-------|-------------|\n| **Core Definitions** | TypeScript definitions and runtime schemas for all protocol types |\n| **Event System** | 16+ core event kinds for streaming interactions |\n| **SDK Implementations** | Language-specific SDKs (TypeScript, Python, Ruby, Go, Java, Kotlin, Dart) |\n| **Framework Adapters** | Integrations with agent frameworks (Claude, Langroid, ADK, Pydantic AI, etc.) |\n| **Reference Implementations** | Server starters demonstrating protocol features |\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n## Architecture\n\nThe protocol stack follows a layered architecture where each layer builds upon the previous one:\n\n```mermaid\ngraph TD\n A[Frontend Application] <-->|Streaming Events| B[Protocol Layer]\n B <-->|Event Translation| C[Framework Adapter]\n C <-->|Agent SDK Calls| D[Agent Runtime]\n \n E[Core Schemas] --> B\n F[Type Definitions] --> E\n \n G[TypeScript SDK] --> F\n H[Python SDK] --> F\n I[Go SDK] --> F\n J[Ruby SDK] --> F\n K[Java SDK] --> F\n L[Dart SDK] --> F\n \n M[Claude Adapter] --> C\n N[Langroid Adapter] --> C\n O[ADK Adapter] --> C\n P[Pydantic AI Adapter] --> C\n```\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/typescript/README.md)\n\n## Core Event System\n\nThe event system is the foundation of the protocol, enabling real-time streaming communication between agents and frontends.\n\n### Event Categories\n\n| Category | Events | Purpose |\n|----------|--------|---------|\n| **Message Lifecycle** | `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END` | Stream text responses |\n| **Tool Execution** | `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END` | Backend tool invocation |\n| **State Management** | `STATE_UPDATE`, `STATE_SNAPSHOT` | Synchronize shared state |\n| **Run Lifecycle** | `RUN_STARTED`, `RUN_FINISHED` | Track agent execution |\n| **UI Generation** | `VIEW_UPDATE`, `COMPONENT_DEFINITION` | Generate dynamic UIs |\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n### Event Flow Example\n\n```mermaid\nsequenceDiagram\n participant User\n participant Frontend\n participant Protocol\n participant Agent\n \n User->>Frontend: Send message\n Frontend->>Protocol: HTTP POST /agent/chat\n Protocol->>Agent: Forward request\n Agent->>Protocol: Emit TEXT_MESSAGE_START\n Agent->>Protocol: Emit TEXT_MESSAGE_CONTENT (streaming)\n Agent->>Protocol: Emit TOOL_CALL_START\n Agent->>Protocol: Emit TOOL_CALL_ARGS\n Agent->>Protocol: Emit TOOL_CALL_END\n Agent->>Protocol: Emit TEXT_MESSAGE_END\n Protocol->>Frontend: SSE Stream\n Frontend->>User: Render updates\n```\n\n资料来源：[integrations/server-starter-all-features/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/server-starter-all-features/typescript/README.md)\n\n## Language SDKs\n\nThe protocol is implemented across multiple programming languages, each providing native bindings for the event system.\n\n### Available SDKs\n\n| Language | Package | Status | Key Features |\n|----------|---------|--------|--------------|\n| TypeScript | `@ag-ui/core` | Stable | Full event definitions, runtime validation |\n| Python | `ag-ui` | Stable | FastAPI integration, async support |\n| Ruby | `ag-ui` | Community | Simple usage example |\n| Go | `ag-ui-go` | Community | Genkit integration |\n| Java | `com.ag-ui.community` | Community | Server and Client packages |\n| Kotlin | `ag-ui-kotlin` | Community | JVM compatibility |\n| Dart | `ag_ui` | Community | Flutter-ready |\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n### TypeScript Core SDK\n\nThe TypeScript SDK provides the foundational definitions used by all other SDKs:\n\n```typescript\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n**Features:**\n- Strongly-typed data models (Message, Tool, Context, State)\n- Runtime validation using JSON schemas\n- Framework-agnostic (Node.js, browsers, any JS runtime)\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n## Framework Adapters\n\nFramework adapters translate between agent frameworks and the AG-UI protocol, enabling plug-and-play integration.\n\n### Supported Integrations\n\n| Framework | Language | Features Supported |\n|-----------|----------|-------------------|\n| Claude Agent SDK | TypeScript, Python | Tool calling, state sync, interrupts |\n| Langroid | Python, TypeScript | Agentic chat, backend tools, shared state |\n| ADK (Agent Development Kit) | Python, TypeScript | All 7 features |\n| Pydantic AI | Python, TypeScript | Agentic chat, frontend tools |\n| Microsoft Agent Framework | Python | All 7 features |\n| AG2 (AutoGen) | Python | Agentic chat, backend tools |\n| Agent Spec | Python | All 4 dojo features |\n\n资料来源：[integrations/claude-agent-sdk/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/python/README.md)\n\n### Claude Agent SDK Adapter\n\nThe Claude adapter provides comprehensive lifecycle management:\n\n```typescript\nimport { ClaudeAgentAdapter } from \"@ag-ui/claude-agent-sdk\";\n\nconst adapter = new ClaudeAgentAdapter({\n agentId: \"my_agent\",\n model: \"claude-haiku-4-5\",\n systemPrompt: \"You are helpful\",\n});\n\nconst events$ = adapter.run(input);\nevents$.subscribe({\n next: (event) => sendEvent(event),\n complete: () => res.end(),\n});\n```\n\n**Key Capabilities:**\n- Full lifecycle management (message extraction, option building, SDK querying)\n- Interrupt support via `adapter.interrupt()`\n- Dynamic frontend tools via MCP server\n- Frontend tool halting for human-in-the-loop\n- Streaming tool arguments\n- Bidirectional state synchronization\n- Context injection into prompts\n\n资料来源：[integrations/claude-agent-sdk/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/typescript/README.md)\n\n### Go Genkit Integration\n\nThe Go integration demonstrates server implementation using Genkit:\n\n```go\ntype MyAgent struct{}\n\nfunc (a *MyAgent) Run(ctx context.Context, input agents.RunAgentInput, eventsCh chan<- events.Event) error {\n // Emit TEXT_MESSAGE_START\n messageID := \"msg-1\"\n eventsCh <- events.NewTextMessageStartEvent(messageID, events.WithRole(\"assistant\"))\n \n // Emit content chunks\n eventsCh <- events.NewTextMessageContentEvent(messageID, \"Hello from my agent!\")\n \n // Emit TEXT_MESSAGE_END\n eventsCh <- events.NewTextMessageEndEvent(messageID)\n \n return nil\n}\n```\n\n资料来源：[sdks/community/genkit/go/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/community/genkit/go/examples/README.md)\n\n## Protocol Features\n\nThe AG-UI Protocol implements seven core features enabling rich agent-user interactions.\n\n### Feature Matrix\n\n| Feature | Description | Events Used |\n|---------|-------------|-------------|\n| **Agentic Chat** | Basic conversational interaction | TEXT_MESSAGE_*, TOOL_CALL_* |\n| **Backend Tool Rendering** | Server-executed tool calls with UI display | TOOL_CALL_*, VIEW_UPDATE |\n| **Human in the Loop** | User approval workflows | TOOL_CALL_START (pause), USER_APPROVAL |\n| **Agentic Generative UI** | Dynamic step-by-step task progress | STATE_UPDATE, VIEW_UPDATE |\n| **Tool-based Generative UI** | Custom UI components from tools | COMPONENT_DEFINITION |\n| **Shared State** | Bidirectional state synchronization | STATE_UPDATE, STATE_SNAPSHOT |\n| **Predictive State Updates** | Optimistic UI updates during tools | STATE_UPDATE (optimistic) |\n\n资料来源：[integrations/server-starter-all-features/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/server-starter-all-features/typescript/README.md)\n\n### State Management\n\nThe protocol supports bidirectional state synchronization between agents and frontends:\n\n```mermaid\ngraph LR\n A[Agent Runtime] <-->|STATE_UPDATE| B[Protocol Layer]\n B <-->|STATE_SNAPSHOT| C[Frontend State]\n \n D[User Action] -->|Update| C\n C -->|Sync| B\n B -->|Inject Context| A\n```\n\nState updates flow both directions, enabling:\n- Agents to update UI state\n- Frontends to modify agent context\n- Optimistic updates during long-running operations\n\n资料来源：[integrations/claude-agent-sdk/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/claude-agent-sdk/python/README.md)\n\n## Data Models\n\n### Core Types\n\n| Model | Fields | Purpose |\n|-------|--------|---------|\n| `Message` | id, role, content, toolCalls | Chat messages |\n| `Tool` | name, description, parameters | Tool definitions |\n| `Context` | variables, metadata | Execution context |\n| `State` | data, version | Application state |\n| `RunAgentInput` | messages, context, tools, state | Agent input |\n| `Event` | type, payload, timestamp | Streaming events |\n\n### Event Schema Example\n\n```typescript\ninterface TextMessageContentEvent {\n type: \"TEXT_MESSAGE_CONTENT\";\n messageId: string;\n delta: string;\n index?: number;\n}\n```\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n## Client-Server Architecture\n\nThe protocol follows a client-server model with the server implementing the agent logic.\n\n### Java SDK Architecture\n\n```mermaid\nclassDiagram\n class LocalAgent {\n +Run(input, events)\n }\n class AbstractAgent {\n +Name() string\n +Description() string\n +Run(ctx, input, events)\n }\n \n LocalAgent --|> AbstractAgent\n```\n\n**Server Package (`java-server`):**\n- Contains `LocalAgent` abstract implementation\n- Handles event emission and stream management\n\n**Client Package (`java-client`):**\n- Contains `AbstractAgent` base class\n- Defines agent interface contracts\n\n资料来源：[sdks/community/java/packages/server/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/server/README.md)\n\n### Dependency Configuration\n\nFor Java projects:\n\n```xml\n\n com.ag-ui.community\n java-server\n 0.0.1\n\n```\n\n```xml\n\n com.ag-ui.community\n java-client\n 0.0.1\n\n```\n\n资料来源：[sdks/community/java/packages/server/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/server/README.md)\n\n## Quick Start\n\n### TypeScript\n\n```bash\nnpm install @ag-ui/core\n```\n\n```typescript\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n### Python\n\n```bash\npip install ag-ui\n```\n\n```python\nfrom ag_ui import ClaudeAgentAdapter, add_claude_fastapi_endpoint\n\nadapter = ClaudeAgentAdapter(name=\"my_agent\", options={\"model\": \"claude-haiku-4-5\"})\nadd_claude_fastapi_endpoint(app=app, adapter=adapter, path=\"/my_agent\")\n```\n\n### Go\n\n```go\npackage main\n\nimport (\n \"github.com/ag-ui-protocol/ag-ui/sdks/community/genkit/go/examples/internal/agents\"\n \"github.com/ag-ui-protocol/ag-ui/sdks/community/go/pkg/core/events\"\n)\n\ntype MyAgent struct{}\n\nfunc (a *MyAgent) Run(ctx context.Context, input agents.RunAgentInput, eventsCh chan<- events.Event) error {\n // Implementation\n return nil\n}\n```\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n## See Also\n\n- [AG-UI Protocol Documentation](https://docs.ag-ui.com/introduction)\n- [Concepts & Architecture](https://docs.ag-ui.com/concepts/architecture)\n- [Events Reference](https://docs.ag-ui.com/concepts/events)\n- [Contributing Guide](https://github.com/ag-ui-protocol/ag-ui/blob/main/CONTRIBUTING.md)\n\n---\n\n\n\n## Event Specification\n\n### 相关页面\n\n相关主题：[Types & Messages](#types-messages), [Capabilities System](#capabilities), [TypeScript SDK](#typescript-sdk)\n\n\nRelated Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java)\n- [sdks/community/java/packages/core/src/main/java/com/agui/core/event/StateDeltaEvent.java](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/core/src/main/java/com/agui/core/event/StateDeltaEvent.java)\n- [sdks/community/java/packages/core/src/main/java/com/agui/core/event/RunErrorEvent.java](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/core/src/main/java/com/agui/core/event/RunErrorEvent.java)\n- [sdks/community/java/packages/core/src/main/java/com/agui/core/event/RawEvent.java](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/core/src/main/java/com/agui/core/event/RawEvent.java)\n- [integrations/community/genkit/go/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/community/genkit/go/README.md)\n \n\n# Event Specification\n\nThe 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.\n\n## Overview\n\nAG-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.\n\nThe event system is designed around three core principles:\n\n1. **Typed Events** – Every event has a well-defined `type` string identifier that clients use to route handling logic.\n2. **Streaming-First** – Events are emitted incrementally, allowing clients to render partial results (e.g., streaming text) in real-time.\n3. **Stateless Payloads** – Events carry all necessary context; clients are responsible for aggregating state across event sequences.\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java:1-80]()\n\n## Event Type Categories\n\nThe AG-UI Protocol defines six logical categories of events. Each category addresses a distinct aspect of agent-client interaction.\n\n```mermaid\ngraph TD\n A[AG-UI Events] --> B[Text Messages]\n A --> C[Thinking Messages]\n A --> D[Tool Calls]\n A --> E[Thinking Process]\n A --> F[State Management]\n A --> G[Execution Lifecycle]\n \n B --> B1[TEXT_MESSAGE_START]\n B --> B2[TEXT_MESSAGE_CONTENT]\n B --> B3[TEXT_MESSAGE_END]\n B --> B4[TEXT_MESSAGE_CHUNK]\n \n D --> D1[TOOL_CALL_START]\n D --> D2[TOOL_CALL_ARGS]\n D --> D3[TOOL_CALL_RESULT]\n D --> D4[TOOL_CALL_END]\n \n E --> E1[THINKING_MESSAGE_START]\n E --> E2[THINKING_MESSAGE_CONTENT]\n E --> E3[THINKING_MESSAGE_END]\n \n F --> F1[STATE_DELTA]\n F --> F2[STATE_SNAPSHOT]\n \n G --> G1[RUN_STARTED]\n G --> G2[RUN_FINISHED]\n G --> G3[RUN_ERROR]\n```\n\n### Text Message Events\n\nText message events handle streaming textual output from the agent. These events support both incremental content delivery and complete message reconstruction on the client side.\n\n| Event Type | Purpose |\n|------------|---------|\n| `TEXT_MESSAGE_START` | Signals the beginning of a new text message stream, includes `messageId` and metadata |\n| `TEXT_MESSAGE_CONTENT` | Carries incremental text delta content |\n| `TEXT_MESSAGE_CHUNK` | Alternative chunk format for raw text segments |\n| `TEXT_MESSAGE_END` | Signals completion of the text message stream |\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java:27-36]()\n\n### Tool Call Events\n\nTool 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.\n\n| Event Type | Purpose |\n|------------|---------|\n| `TOOL_CALL_START` | Indicates initiation of a tool call with tool name and call ID |\n| `TOOL_CALL_ARGS` | Streams tool arguments as JSON chunks arrive |\n| `TOOL_CALL_RESULT` | Delivers the tool execution result back to the agent |\n| `TOOL_CALL_END` | Signals completion of the tool call sequence |\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java](integrations/community/genkit/go/README.md)\n\n### State Management Events\n\nState events provide two complementary mechanisms for client-side state synchronization.\n\n| Event Type | Purpose |\n|------------|---------|\n| `STATE_DELTA` | Represents incremental changes to application state |\n| `STATE_SNAPSHOT` | Provides a complete state snapshot for initial synchronization |\n\nThe `StateDeltaEvent` class encapsulates state changes without carrying the full application state:\n\n```java\npublic class StateDeltaEvent extends BaseEvent {\n public StateDeltaEvent() {\n super(EventType.STATE_DELTA);\n }\n}\n```\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/event/StateDeltaEvent.java:1-40]()\n\n### Execution Lifecycle Events\n\nLifecycle events mark significant milestones in the run execution pipeline.\n\n| Event Type | Purpose |\n|------------|---------|\n| `RUN_STARTED` | Signals that a new agent run has begun |\n| `RUN_FINISHED` | Indicates successful completion of the run |\n| `RUN_ERROR` | Reports an error that occurred during execution |\n\nThe `RunErrorEvent` captures error information for client-side error handling:\n\n```java\npublic class RunErrorEvent extends BaseEvent {\n private String error;\n \n public RunErrorEvent() {\n super(EventType.RUN_ERROR);\n }\n \n public void setError(final String error) {\n this.error = error;\n }\n \n public String getError() {\n return this.error;\n }\n}\n```\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/event/RunErrorEvent.java:1-55]()\n\n### Raw Events\n\nFor extensibility and backward compatibility, the protocol includes a generic `RAW` event type that can carry arbitrary event data:\n\n```java\npublic class RawEvent extends BaseEvent {\n public RawEvent() {\n super(EventType.RAW);\n }\n}\n```\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/event/RawEvent.java:1-35]()\n\n## Event Schema Structure\n\nEvery AG-UI event inherits from a common `BaseEvent` that provides standard fields required for all event types.\n\n### Base Event Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `type` | `string` | The event type identifier (e.g., `TEXT_MESSAGE_START`) |\n| `timestamp` | `number` | Unix timestamp when the event was generated |\n| `messageId` | `string` | Unique identifier for message grouping (when applicable) |\n| `runId` | `string` | Identifier of the current run execution (when applicable) |\n| `threadId` | `string` | Identifier of the conversation thread (when applicable) |\n| `rawEvent` | `object` | Raw event payload data |\n\n### Event Payload Examples\n\n**Text Message Content Event:**\n```json\n{\n \"type\": \"TEXT_MESSAGE_CONTENT\",\n \"messageId\": \"msg_abc123\",\n \"runId\": \"run_xyz789\",\n \"threadId\": \"thread_main\",\n \"delta\": \"Hello, how can I assist\",\n \"timestamp\": 1704067200000\n}\n```\n\n**Tool Call Start Event:**\n```json\n{\n \"type\": \"TOOL_CALL_START\",\n \"toolCallId\": \"tool_123\",\n \"toolName\": \"get_weather\",\n \"timestamp\": 1704067200500\n}\n```\n\n**State Delta Event:**\n```json\n{\n \"type\": \"STATE_DELTA\",\n \"state\": {\n \"weather\": {\n \"city\": \"San Francisco\",\n \"temperature\": 18\n }\n },\n \"timestamp\": 1704067201000\n}\n```\n\n## Event Flow Architecture\n\nThe following diagram illustrates the typical event flow in an AG-UI enabled application:\n\n```mermaid\nsequenceDiagram\n participant FE as Frontend Client\n participant AG as AG-UI Gateway\n participant AR as Agent Runtime\n \n FE->>AG: POST /run (RunAgentInput)\n AG->>AR: Invoke agent with input\n AR->>AG: Emit TEXT_MESSAGE_START\n AG->>FE: SSE stream: TEXT_MESSAGE_START\n loop Streaming Content\n AR->>AG: Emit TEXT_MESSAGE_CONTENT\n AG->>FE: SSE stream: TEXT_MESSAGE_CONTENT\n end\n AR->>AG: Emit TOOL_CALL_START\n AG->>FE: SSE stream: TOOL_CALL_START\n Note over FE: Execute tool locally\n FE->>AG: Submit TOOL_CALL_RESULT\n AR->>AG: Emit RUN_FINISHED\n AG->>FE: SSE stream: RUN_FINISHED\n```\n\n## Genkit Integration Example\n\nThe Genkit integration demonstrates how event types map to framework-specific content:\n\n| Genkit Content | AG-UI Event |\n|----------------|-------------|\n| Text content (first chunk) | `TEXT_MESSAGE_START` + `TEXT_MESSAGE_CHUNK` |\n| Text content (subsequent) | `TEXT_MESSAGE_CHUNK` |\n| Tool request | `TOOL_CALL_START` + `TOOL_CALL_ARGS` |\n| Tool response | `TOOL_CALL_RESULT` |\n\n资料来源：[integrations/community/genkit/go/README.md](integrations/community/genkit/go/README.md)\n\n```go\n// Event type handling in Genkit adapter\nswitch event.Type {\ncase events.EventTypeTextMessageStart:\n // Handle text message start\ncase events.EventTypeTextMessageChunk:\n // Handle text chunk\ncase events.EventTypeToolCallStart:\n // Handle tool call start\ncase events.EventTypeToolCallArgs:\n // Handle tool call arguments\ncase events.EventTypeToolCallResult:\n // Handle tool call result\n}\n```\n\n## Best Practices\n\n### Event Ordering\n\nEvents must be emitted in a deterministic order to ensure consistent client behavior:\n\n1. `RUN_STARTED` – Always first\n2. `STATE_SNAPSHOT` – If initial state is needed\n3. Message-related events (`TEXT_MESSAGE_START`, content, end)\n4. Tool call events (`TOOL_CALL_START`, args, result, end)\n5. State updates (`STATE_DELTA`)\n6. `RUN_FINISHED` or `RUN_ERROR` – Always last\n\n### Error Handling\n\nWhen errors occur during event streaming:\n\n- Emit `RUN_ERROR` with descriptive error message\n- Include error context in the event payload\n- Do not emit `RUN_FINISHED` after an error\n\n### Idempotency\n\nClients should handle duplicate events gracefully by using `messageId` and `runId` for deduplication when reconnecting or retrying requests.\n\n## Summary\n\nThe 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:\n\n- Real-time streaming of text and tool content\n- Synchronized state management across client and server\n- Structured error handling and recovery\n- Framework-agnostic integrations through consistent event contracts\n\nAll event types are defined as enumerations in the core SDK packages and extend a common `BaseEvent` class to ensure type safety and runtime validation.\n\n---\n\n\n\n## Types & Messages\n\n### 相关页面\n\n相关主题：[Event Specification](#events), [Capabilities System](#capabilities)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/src/types.ts](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/src/types.ts)\n- [sdks/typescript/packages/proto/src/generated/types.ts](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/proto/src/generated/types.ts)\n- [sdks/python/ag_ui/core/types.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/core/types.py)\n- [docs/concepts/messages.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/concepts/messages.mdx)\n- [docs/concepts/serialization.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/concepts/serialization.mdx)\n- [sdks/typescript/packages/core/src/events.ts](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/src/events.ts)\n \n\n# Types & Messages\n\n## Overview\n\nThe 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.\n\n**Core responsibilities of the Types & Messages system:**\n\n- Define strongly-typed data models for messages, tools, context, and state\n- Provide runtime validation through schema-based parsing\n- Support streaming events for real-time agent communication\n- Enable framework-agnostic implementation across TypeScript, Python, and other languages\n\n资料来源：[sdks/typescript/packages/core/README.md:1-15]()\n\n## Type System Architecture\n\n```mermaid\ngraph TD\n A[AG-UI Types] --> B[Core Data Models]\n A --> C[Event Types]\n A --> D[Streaming Events]\n \n B --> B1[Message]\n B --> B2[Tool]\n B --> B3[Context]\n B --> B4[State]\n B --> B5[RunAgentInput]\n \n C --> C1[TextMessage Events]\n C --> C2[Thinking Events]\n C --> C3[Tool Call Events]\n C --> C4[State Update Events]\n C --> C5[Lifecycle Events]\n \n D --> D1[Server-Sent Events]\n D --> D2[JSON Payloads]\n D --> D3[Binary/Proto]\n```\n\n## Core Data Models\n\n### Message Types\n\nMessages represent the fundamental unit of communication in the AG-UI protocol. They are strongly typed and support various content types.\n\n资料来源：[sdks/typescript/packages/core/src/types.ts:1-50]()\n\n#### Message Structure\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `id` | `string` | Yes | Unique identifier for the message |\n| `role` | `MessageRole` | Yes | Sender role (user, assistant, system, tool) |\n| `content` | `string` | Yes | Message content |\n| `type` | `string` | No | Message type discriminator |\n| `name` | `string` | No | Optional name for the sender |\n| `toolCallId` | `string` | No | Tool call ID for tool messages |\n| `toolName` | `string` | No | Name of the tool being called |\n| `metadata` | `Record` | No | Additional message metadata |\n\n#### Message Roles\n\n| Role | Description |\n|------|-------------|\n| `user` | Human user message |\n| `assistant` | AI agent response |\n| `system` | System-level instructions |\n| `tool` | Tool execution result |\n\n### Tool Types\n\nTools enable agents to perform actions and access external functionality.\n\n资料来源：[sdks/typescript/packages/core/src/types.ts:80-120]()\n\n#### Tool Definition\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `id` | `string` | Yes | Unique tool identifier |\n| `name` | `string` | Yes | Tool name for invocation |\n| `description` | `string` | Yes | Human-readable description |\n| `inputSchema` | `object` | Yes | JSON Schema for tool inputs |\n| `type` | `string` | No | Tool type (default: \"function\") |\n\n### State Types\n\nState represents the application state that can be shared and synchronized between agent and frontend.\n\n资料来源：[sdks/typescript/packages/core/src/types.ts:150-200]()\n\n#### State Structure\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `stateId` | `string` | Yes | Unique state identifier |\n| `data` | `Record` | Yes | State data payload |\n| `version` | `number` | No | State version for conflict resolution |\n| `timestamp` | `number` | No | Last update timestamp |\n\n### Run Agent Input\n\nThe `RunAgentInput` type defines the input schema for starting an agent run.\n\n资料来源：[sdks/typescript/packages/core/src/types.ts:250-300]()\n\n#### RunAgentInput Fields\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `messages` | `Message[]` | Yes | Conversation history |\n| `tools` | `Tool[]` | No | Available tools |\n| `context` | `Context` | No | Execution context |\n| `systemPrompt` | `string` | No | System-level instructions |\n| `temperature` | `number` | No | Sampling temperature |\n| `maxTokens` | `number` | No | Maximum response tokens |\n\n## Event Types\n\nThe AG-UI protocol defines 16 core event types organized into logical categories for streaming communication.\n\n资料来源：[sdks/community/java/packages/core/src/main/java/com/agui/core/type/EventType.java:1-50]()\n\n```mermaid\ngraph LR\n subgraph Text Messages\n T1[TEXT_MESSAGE_START]\n T2[TEXT_MESSAGE_CONTENT]\n T3[TEXT_MESSAGE_END]\n T4[TEXT_MESSAGE_CHUNK]\n end\n \n subgraph Thinking\n T5[THINKING_MESSAGE_START]\n T6[THINKING_MESSAGE_CONTENT]\n T7[THINKING_MESSAGE_END]\n end\n \n subgraph Tool Calls\n T8[TOOL_CALL_START]\n T9[TOOL_CALL_ARGUMENTS]\n T10[TOOL_CALL_END]\n end\n \n subgraph State\n T11[STATE_UPDATE]\n T12[STATE_SNAPSHOT]\n end\n \n subgraph Lifecycle\n T13[RUN_STARTED]\n T14[RUN_FINISHED]\n T15[ERROR]\n end\n```\n\n### Text Message Events\n\n| Event Type | Description |\n|------------|-------------|\n| `TEXT_MESSAGE_START` | Signals the beginning of a text message stream |\n| `TEXT_MESSAGE_CONTENT` | Represents incremental text message content |\n| `TEXT_MESSAGE_END` | Signals the completion of a text message stream |\n| `TEXT_MESSAGE_CHUNK` | Represents a chunk of text message data |\n\n资料来源：[sdks/typescript/packages/core/src/events.ts:10-30]()\n\n### Thinking Events\n\n| Event Type | Description |\n|------------|-------------|\n| `THINKING_MESSAGE_START` | Signals the beginning of a thinking process |\n| `THINKING_MESSAGE_CONTENT` | Contains intermediate thinking content |\n| `THINKING_MESSAGE_END` | Signals the completion of thinking |\n\nThese events enable displaying AI reasoning processes to users in real-time.\n\n### Tool Call Events\n\n| Event Type | Description |\n|------------|-------------|\n| `TOOL_CALL_START` | Initiates a tool invocation |\n| `TOOL_CALL_ARGUMENTS` | Streams tool arguments incrementally |\n| `TOOL_CALL_END` | Completes a tool call |\n| `TOOL_CALL_RESULT` | Contains the tool execution result |\n\n资料来源：[sdks/typescript/packages/core/src/events.ts:50-80]()\n\n### State Management Events\n\n| Event Type | Description |\n|------------|-------------|\n| `STATE_UPDATE` | Represents a partial state change |\n| `STATE_SNAPSHOT` | Contains the complete current state |\n| `STATE_DIFF` | Represents state differences |\n\n### Execution Lifecycle Events\n\n| Event Type | Description |\n|------------|-------------|\n| `RUN_STARTED` | Signals the start of an agent run |\n| `RUN_FINISHED` | Signals the completion of a run |\n| `STEP_STARTED` | Signals the beginning of a step |\n| `STEP_FINISHED` | Signals the completion of a step |\n| `ERROR` | Contains error information |\n\n## Event Schema Validation\n\nThe AG-UI core package provides runtime validation through the `EventSchemas` class, which uses schema parsing to catch malformed payloads early.\n\n资料来源：[sdks/typescript/packages/core/README.md:30-40]()\n\n```typescript\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\n// Validate an incoming event\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n### Event Payload Structure\n\nAll events follow a consistent structure:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `type` | `string` | Event type identifier |\n| `data` | `object` | Event-specific payload |\n| `timestamp` | `number` | Event timestamp (optional) |\n| `runId` | `string` | Associated run identifier (optional) |\n\n## Protocol Buffer Definitions\n\nFor high-performance scenarios, the AG-UI protocol includes Protocol Buffer definitions that provide binary serialization.\n\n资料来源：[sdks/typescript/packages/proto/src/generated/types.ts:1-100]()\n\nThe protobuf types maintain parity with the JSON types but offer advantages in bandwidth-constrained environments:\n\n- **Smaller payload sizes** - Binary encoding reduces message overhead\n- **Faster parsing** - Native binary parsing vs JSON string processing\n- **Language interoperability** - Generated code for multiple languages\n\n### Proto Message Mapping\n\n| JSON Type | Proto Message | Notes |\n|-----------|---------------|-------|\n| `Message` | `Message` | Full parity |\n| `Tool` | `ToolDefinition` | Input schema as `google.protobuf.Struct` |\n| `State` | `AgentState` | Version field for conflict resolution |\n| `Event` | `StreamEvent` | Union type for all event types |\n\n## Serialization\n\nThe AG-UI protocol supports multiple serialization formats to accommodate different transport mechanisms and client requirements.\n\n资料来源：[docs/concepts/serialization.mdx:1-30]()\n\n### Supported Formats\n\n| Format | Use Case | Performance |\n|--------|----------|--------------|\n| JSON | REST APIs, Browser clients | Good |\n| Server-Sent Events (SSE) | Streaming responses | Excellent |\n| Protocol Buffers | High-throughput systems | Best |\n| Binary | Minimal payload sizes | Best |\n\n### JSON Schema\n\nThe TypeScript SDK exports JSON schemas that can be used for:\n\n- **Client-side validation** - Validate incoming events\n- **Documentation generation** - Auto-generate API docs\n- **Code generation** - Create typed clients from schemas\n\n## Python Type System\n\nThe Python SDK provides equivalent type definitions through Pydantic models, ensuring type safety and validation in Python-based agent implementations.\n\n资料来源：[sdks/python/ag_ui/core/types.py:1-80]()\n\n```python\nfrom ag_ui.core.types import Message, Tool, State, RunAgentInput\nfrom ag_ui.core.events import EventType, BaseEvent\n```\n\n### Python Type Mapping\n\n| Python Type | TypeScript Equivalent | Validation |\n|-------------|---------------------|------------|\n| `Message` | `Message` | Pydantic validators |\n| `Tool` | `Tool` | JSON Schema validation |\n| `State` | `State` | Version checking |\n| `RunAgentInput` | `RunAgentInput` | Required field validation |\n\n## Event Streaming Architecture\n\n```mermaid\nsequenceDiagram\n participant Client\n participant AGUICore\n participant Agent\n participant Tools\n \n Client->>AGUICore: Connect to stream\n Agent->>AGUICore: Emit TEXT_MESSAGE_START\n AGUICore->>Client: Stream event\n Agent->>AGUICore: Emit TEXT_MESSAGE_CONTENT\n AGUICore->>Client: Stream event (delta)\n Agent->>AGUICore: Emit TOOL_CALL_START\n AGUICore->>Client: Stream event\n Tools->>Agent: Execute tool\n Agent->>AGUICore: Emit TOOL_CALL_RESULT\n AGUICore->>Client: Stream event\n Agent->>AGUICore: Emit RUN_FINISHED\n AGUICore->>Client: Stream event\n```\n\n## Usage Patterns\n\n### Creating a Message\n\n```typescript\nimport { Message, MessageRole } from \"@ag-ui/core\";\n\nconst userMessage: Message = {\n id: \"msg_unique_123\",\n role: MessageRole.User,\n content: \"What's the weather in San Francisco?\",\n};\n```\n\n### Defining a Tool\n\n```typescript\nimport { Tool } from \"@ag-ui/core\";\n\nconst weatherTool: Tool = {\n id: \"tool_weather\",\n name: \"get_weather\",\n description: \"Get current weather for a location\",\n inputSchema: {\n type: \"object\",\n properties: {\n location: { type: \"string\" },\n unit: { type: \"string\", enum: [\"celsius\", \"fahrenheit\"] },\n },\n required: [\"location\"],\n },\n};\n```\n\n### Processing Events\n\n```typescript\nimport { EventType } from \"@ag-ui/core\";\n\nfunction handleEvent(event: BaseEvent) {\n switch (event.type) {\n case EventType.TEXT_MESSAGE_CONTENT:\n console.log(\"Received text:\", event.delta);\n break;\n case EventType.TOOL_CALL_START:\n console.log(\"Tool called:\", event.toolName);\n break;\n case EventType.STATE_UPDATE:\n console.log(\"State updated:\", event.state);\n break;\n }\n}\n```\n\n## Framework Integration\n\nThe type system is designed to be framework-agnostic and integrates with:\n\n- **LangChain** - Via `@ag-ui/langchain` integration\n- **LangGraph** - Via `@ag-ui/langgraph` integration\n- **PydanticAI** - Via `@ag-ui/pydantic-ai` integration\n- **ADK Middleware** - Via `adk-middleware` integration\n- **Langroid** - Via `@ag-ui/langroid` integration\n\nEach integration maps its native types to the AG-UI type system, ensuring consistent behavior across different agent frameworks.\n\n---\n\n\n\n## Capabilities System\n\n### 相关页面\n\n相关主题：[Event Specification](#events), [TypeScript SDK](#typescript-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/src/capabilities.ts](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/src/capabilities.ts)\n- [sdks/python/ag_ui/core/capabilities.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/core/capabilities.py)\n- [docs/concepts/capabilities.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/concepts/capabilities.mdx)\n- [docs/concepts/generative-ui-specs.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/concepts/generative-ui-specs.mdx)\n \n\n# Capabilities System\n\nThe 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.\n\n## Overview\n\nThe 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.\n\nThe 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.\n\n## Architecture\n\nThe 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.\n\n```mermaid\ngraph TD\n A[Client Application] --> B[AG-UI Client SDK]\n B --> C[Capabilities Manager]\n C --> D[Capability Definitions]\n C --> E[Capability Negotiation Engine]\n \n F[Server Application] --> G[AG-UI Server SDK]\n G --> H[Capabilities Validator]\n H --> D\n \n E <-->|Capability Exchange| H\n \n I[Core Capability Schemas] --> D\n J[Custom Capability Extensions] --> D\n```\n\n## Core Capability Categories\n\nThe 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.\n\n### Agentic Chat Capabilities\n\nAgentic 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.\n\nThe 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.\n\n### Backend Tool Rendering Capabilities\n\nBackend 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.\n\nTools 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.\n\n### Human-in-the-Loop Capabilities\n\nHuman-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.\n\nWhen 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.\n\n### Agentic Generative UI Capabilities\n\nAgentic 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.\n\nThis 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.\n\n### Tool-Based Generative UI Capabilities\n\nTool-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.\n\n### Shared State Capabilities\n\nShared 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.\n\nThe 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.\n\n### Predictive State Updates Capabilities\n\nPredictive 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.\n\n## Capability Definition Schema\n\nThe 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.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | string | Unique identifier for the capability |\n| `version` | string | Semantic version of the capability implementation |\n| `enabled` | boolean | Whether the capability is currently active |\n| `parameters` | object | Capability-specific configuration parameters |\n| `dependencies` | string[] | Other capabilities required for this capability |\n\n## Capability Negotiation Flow\n\nThe 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.\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant CapabilitiesManager\n \n Client->>CapabilitiesManager: Create ClientCapabilities\n CapabilitiesManager-->>Client: Capability Instance\n Client->>Server: Send INITIALIZE with capabilities\n Server->>CapabilitiesManager: Validate client capabilities\n CapabilitiesManager-->>Server: Validation result\n Server->>CapabilitiesManager: Create ServerCapabilities\n Server->>Client: Send INITIALIZE_COMPLETE with server capabilities\n Client->>CapabilitiesManager: Compare and merge capabilities\n CapabilitiesManager-->>Client: Negotiated capability set\n```\n\nThe 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.\n\n## TypeScript Implementation\n\nThe 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.\n\n```typescript\nimport { Capabilities, CapabilityType, negotiateCapabilities } from \"@ag-ui/core\";\n\n// Define client capabilities\nconst clientCapabilities: Capabilities = {\n agenticChat: { enabled: true, version: \"1.0.0\" },\n backendToolRendering: { enabled: true, version: \"1.0.0\" },\n humanInTheLoop: { enabled: true, version: \"1.0.0\" },\n agenticGenerativeUI: { enabled: true, version: \"1.0.0\" },\n toolBasedGenerativeUI: { enabled: false, version: \"1.0.0\" },\n sharedState: { enabled: true, version: \"1.0.0\" },\n predictiveStateUpdates: { enabled: false, version: \"1.0.0\" }\n};\n\n// Negotiate with server capabilities\nconst negotiated = negotiateCapabilities(clientCapabilities, serverCapabilities);\n```\n\nThe implementation provides runtime validation of capability configurations, ensuring that capability declarations conform to the expected schema before being used in negotiation.\n\n## Python Implementation\n\nThe 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.\n\n```python\nfrom ag_ui.core.capabilities import (\n Capabilities,\n CapabilityType,\n negotiate_capabilities,\n ClientCapabilities,\n ServerCapabilities\n)\n\n# Define server capabilities\nserver_capabilities = ServerCapabilities(\n agentic_chat=CapabilityStatus(enabled=True, version=\"1.0.0\"),\n backend_tool_rendering=CapabilityStatus(enabled=True, version=\"1.0.0\"),\n human_in_the_loop=CapabilityStatus(enabled=True, version=\"1.0.0\"),\n agentic_generative_ui=CapabilityStatus(enabled=True, version=\"1.0.0\"),\n tool_based_generative_ui=CapabilityStatus(enabled=False, version=\"1.0.0\"),\n shared_state=CapabilityStatus(enabled=True, version=\"1.0.0\"),\n predictive_state_updates=CapabilityStatus(enabled=True, version=\"1.0.0\")\n)\n\n# Negotiate with client capabilities\nnegotiated = negotiate_capabilities(client_capabilities, server_capabilities)\n```\n\nThe Python implementation integrates seamlessly with FastAPI and other async web frameworks, providing capability endpoints that handle the negotiation protocol.\n\n## Integration Examples\n\nDifferent agent frameworks integrate with the Capabilities System in various ways, depending on their architecture and requirements.\n\n### ADK Middleware Integration\n\nThe 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.\n\n```python\nfrom google.adk.middleware import Middleware\nfrom ag_ui.core.capabilities import AGUIToolset\n\nmiddleware = Middleware(\n name=\"ag_ui_middleware\",\n capabilities={\n \"agentic_chat\": True,\n \"backend_tool_rendering\": True,\n \"human_in_the_loop\": True,\n \"shared_state\": True\n }\n)\n```\n\n### Claude Agent SDK Integration\n\nThe 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.\n\n```python\nfrom ag_ui_claude_sdk import ClaudeAgentAdapter\n\nadapter = ClaudeAgentAdapter(\n name=\"my_agent\",\n options={\"model\": \"claude-haiku-4-5\"},\n capabilities={\n \"agentic_chat\": True,\n \"backend_tool_rendering\": True,\n \"human_in_the_loop\": True,\n \"agentic_generative_ui\": True,\n \"tool_based_generative_ui\": True,\n \"shared_state\": True,\n \"predictive_state_updates\": True\n }\n)\n```\n\n## Capability Versioning\n\nThe 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.\n\nWhen 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.\n\n| Compatibility Level | Description |\n|--------------------|-------------|\n| Full Match | Both implementations declare identical versions |\n| Minor Compatible | Client version is greater than or equal to server version |\n| Major Compatible | Both versions share the same major number |\n| Incompatible | Versions have conflicting major numbers |\n\n## Error Handling\n\nThe 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.\n\nError 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.\n\n## Best Practices\n\nWhen working with the Capabilities System, several best practices ensure robust and maintainable implementations.\n\n**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.\n\n**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.\n\n**Capability Fallback**: Implement fallback behavior for unsupported capabilities. Rather than failing entirely, design agents to operate in degraded mode when certain capabilities are unavailable.\n\n**Capability Testing**: Test capability negotiation thoroughly, including edge cases where partial capability sets are provided or where version mismatches occur.\n\n## Summary\n\nThe 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.\n\n---\n\n\n\n## TypeScript SDK\n\n### 相关页面\n\n相关主题：[Python SDK](#python-sdk), [Event Specification](#events)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n- [sdks/typescript/packages/cli/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/cli/README.md)\n- [integrations/langchain/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langchain/typescript/package.json)\n- [integrations/langgraph/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/package.json)\n- [integrations/vercel-ai-sdk/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/vercel-ai-sdk/typescript/package.json)\n- [middlewares/a2a-middleware/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/middlewares/a2a-middleware/package.json)\n \n\n# TypeScript SDK\n\nThe **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.\n\n## Architecture Overview\n\nThe TypeScript SDK follows a modular architecture with core packages and framework-specific integrations.\n\n```mermaid\ngraph TD\n A[Application Code] --> B[@ag-ui/core]\n A --> C[@ag-ui/client]\n B --> D[EventSchemas]\n B --> E[EventType]\n C --> F[Agent Client]\n C --> G[Middleware]\n F --> H[HTTP Transport]\n F --> I[WebSocket Transport]\n H --> J[LangChain]\n H --> K[LangGraph]\n H --> L[Vercel AI SDK]\n G --> M[a2a-middleware]\n G --> N[Custom Middleware]\n```\n\n## Package Structure\n\n| Package | Purpose | Version | Key Dependencies |\n|---------|---------|---------|-------------------|\n| `@ag-ui/core` | Type definitions, schemas, event types | >=0.0.42 | zod |\n| `@ag-ui/client` | HTTP agent, streaming, state management | >=0.0.42 | rxjs |\n| `@ag-ui/cli` | Project scaffolding tool | - | - |\n| `@ag-ui/langgraph` | LangGraph integration | 0.0.32 | @langchain/core, @langchain/langgraph-sdk |\n| `@ag-ui/vercel-ai-sdk` | Vercel AI SDK integration | - | ai, zod |\n| `@ag-ui/a2a-middleware` | A2A protocol bridge | 0.0.2 | @a2a-js/sdk, ai |\n\n## Core Package (@ag-ui/core)\n\nThe `@ag-ui/core` package delivers the foundational type system and runtime validation for AG-UI protocol implementations.\n\n### Typed Data Models\n\nThe core package provides TypeScript interfaces for all AG-UI data models:\n\n```typescript\nimport { EventSchemas, EventType } from \"@ag-ui/core\";\n\n// Validate an incoming event\nEventSchemas.parse({\n type: EventType.TEXT_MESSAGE_CONTENT,\n messageId: \"msg_123\",\n delta: \"Hello, world!\",\n});\n```\n\n### Supported Data Models\n\n| Model | Description |\n|-------|-------------|\n| `Message` | User and assistant message representation |\n| `Tool` | Tool definition with parameters |\n| `Context` | Conversation context data |\n| `RunAgentInput` | Input for agent execution |\n| `State` | Application state structure |\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n### Event System\n\nThe core package defines 16 core event kinds covering the complete agent lifecycle:\n\n| Event Category | Events |\n|----------------|--------|\n| Assistant Messages | `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END`, `AUDIO_MESSAGE_CONTENT` |\n| Tool Calls | `TOOL_CALLS_START`, `TOOL_CALLS_END`, `TOOL_CALL_RESULT` |\n| State Updates | `STATE_SNAPSHOT`, `STATE_DELTA` |\n| Run Lifecycle | `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR` |\n| Content Types | `INSTRUCTION`, `CHAT_OVERFLOW`, `BINARY_MESSAGE_CONTENT` |\n\n资料来源：[sdks/typescript/packages/core/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/core/README.md)\n\n### Runtime Validation\n\nAll event payloads are validated at runtime using Zod schemas, ensuring malformed payloads are caught early in the development process.\n\n## Client Package (@ag-ui/client)\n\nThe `@ag-ui/client` package provides the runtime client for connecting applications to AG-UI protocol servers.\n\n### Installation\n\n```bash\nnpm install @ag-ui/client\npnpm add @ag-ui/client\nyarn add @ag-ui/client\n```\n\n### HTTP Agent\n\nThe HTTP agent handles communication with AG-UI backend servers:\n\n```typescript\nimport { HttpAgent } from \"@ag-ui/client\";\n\nconst agent = new HttpAgent({\n url: \"http://localhost:8000/\",\n apiKey: process.env.AG_UI_API_KEY,\n});\n```\n\n#### Configuration Options\n\n| Option | Type | Required | Default | Description |\n|--------|------|----------|---------|-------------|\n| `url` | `string` | Yes | - | Base URL of the AG-UI server |\n| `apiKey` | `string` | No | `undefined` | API key for authentication |\n| `timeout` | `number` | No | `30000` | Request timeout in milliseconds |\n| `headers` | `Record` | No | `{}` | Custom headers |\n\n### Event Streaming\n\nThe client supports full event streaming using RxJS observables:\n\n```typescript\nimport { createAgent } from \"@ag-ui/client\";\n\nconst agent = createAgent({\n url: \"http://localhost:8000/\",\n});\n\nagent.events$.subscribe((event) => {\n console.log(\"Received event:\", event.type);\n});\n```\n\n## Middleware System\n\nThe TypeScript SDK implements a middleware system that allows intercepting and transforming requests and responses.\n\n```mermaid\ngraph LR\n A[Request] --> B[Middleware 1]\n B --> C[Middleware 2]\n C --> D[Middleware N]\n D --> E[Agent]\n E --> F[Response]\n F --> G[Response Middleware]\n```\n\n### Built-in Middleware\n\n| Middleware | Purpose | Package |\n|------------|---------|---------|\n| `a2a-middleware` | Bridge to A2A protocol | `@ag-ui/a2a-middleware` |\n| Custom Middleware | User-defined transformations | `@ag-ui/client` |\n\n### Creating Custom Middleware\n\n```typescript\nimport { createMiddleware } from \"@ag-ui/client\";\n\nconst loggingMiddleware = createMiddleware({\n name: \"logger\",\n onRequest: async (request, env) => {\n console.log(\"Request:\", request);\n return request;\n },\n onResponse: async (response, env) => {\n console.log(\"Response:\", response);\n return response;\n },\n});\n```\n\n## Framework Integrations\n\nThe TypeScript SDK provides pre-built integrations for popular agent frameworks:\n\n### LangChain Integration\n\n```json\n{\n \"dependencies\": {\n \"@ag-ui/core\": \">=0.0.42\",\n \"@ag-ui/client\": \">=0.0.42\",\n \"@langchain/core\": \"^1.1.40\",\n \"@langchain/langgraph-sdk\": \"^1.8.8\",\n \"langchain\": \">=1.2.0\"\n }\n}\n```\n\n资料来源：[integrations/langgraph/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/package.json)\n\n### Vercel AI SDK Integration\n\n```json\n{\n \"dependencies\": {\n \"@ag-ui/core\": \">=0.0.42\",\n \"@ag-ui/client\": \">=0.0.42\",\n \"ai\": \"^4.3.16\",\n \"zod\": \"^3.22.4\"\n }\n}\n```\n\n资料来源：[integrations/vercel-ai-sdk/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/vercel-ai-sdk/typescript/package.json)\n\n### A2A Middleware\n\nThe A2A (Agent-to-Agent) middleware enables interoperability with A2A protocol-compliant agents:\n\n```json\n{\n \"dependencies\": {\n \"@a2a-js/sdk\": \"^0.2.2\",\n \"ai\": \"^4.3.16\",\n \"zod\": \"^3.22.4\"\n },\n \"peerDependencies\": {\n \"@ag-ui/client\": \">=0.0.40\",\n \"rxjs\": \"7.8.1\"\n }\n}\n```\n\n资料来源：[middlewares/a2a-middleware/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/middlewares/a2a-middleware/package.json)\n\n## CLI Tool (@ag-ui/cli)\n\nThe AG-UI CLI provides project scaffolding capabilities:\n\n```bash\nnpx create-ag-ui-app@latest my-agent-app\nnpx create-ag-ui-app@latest --help\n```\n\n资料来源：[sdks/typescript/packages/cli/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/typescript/packages/cli/README.md)\n\n## Quick Start\n\n### 1. Install Core Dependencies\n\n```bash\nnpm install @ag-ui/core @ag-ui/client\n```\n\n### 2. Create an Agent Client\n\n```typescript\nimport { HttpAgent } from \"@ag-ui/client\";\nimport { EventType } from \"@ag-ui/core\";\n\nconst agent = new HttpAgent({\n url: process.env.AG_UI_BASE_URL || \"http://127.0.0.1:8000\",\n apiKey: process.env.AG_UI_API_KEY,\n});\n\n// Subscribe to events\nagent.events$.subscribe((event) => {\n switch (event.type) {\n case EventType.RUN_STARTED:\n console.log(\"Run started:\", event.runId);\n break;\n case EventType.TEXT_MESSAGE_CONTENT:\n console.log(\"Message delta:\", event.delta);\n break;\n case EventType.RUN_FINISHED:\n console.log(\"Run finished:\", event.runId);\n break;\n }\n});\n```\n\n### 3. Send a Message\n\n```typescript\nawait agent.send({\n type: \"USER_MESSAGE\",\n messageId: \"msg_001\",\n content: \"Hello, agent!\",\n});\n```\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AG_UI_BASE_URL` | Base URL of the AG-UI server | `http://127.0.0.1:8000` |\n| `AG_UI_API_KEY` | API key for authentication | `undefined` |\n| `DEBUG` | Enable debug logging | `false` |\n\n## Testing\n\nThe SDK includes comprehensive test coverage using Vitest:\n\n```bash\n# Run all tests\npnpm test\n\n# Run with coverage\npnpm test:coverage\n\n# Watch mode\npnpm test:watch\n\n# Validate package exports\npnpm test:exports\n```\n\n## Documentation\n\n- Concepts & Architecture: [docs.ag-ui.com/concepts/architecture](https://docs.ag-ui.com/concepts/architecture)\n- Full API Reference: [docs.ag-ui.com/sdk/js/core](https://docs.ag-ui.com/sdk/js/core/overview)\n- Contributing Guide: [docs.ag-ui.com/development/contributing](https://docs.ag-ui.com/development/contributing)\n\n## License\n\nMIT © 2025 AG-UI Protocol Contributors\n\n---\n\n\n\n## Python SDK\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#typescript-sdk), [LangGraph Integration](#langgraph-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/README.md)\n- [sdks/python/ag_ui/__init__.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/core/events.py)\n- [sdks/python/ag_ui/core/events.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/core/events.py)\n- [sdks/python/ag_ui/core/types.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/core/types.py)\n- [sdks/python/ag_ui/encoder/encoder.py](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/python/ag_ui/encoder/encoder.py)\n- [docs/sdk/python/core/overview.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/python/core/overview.mdx)\n \n\n# Python SDK\n\nThe 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).\n\n## Overview\n\nThe Python SDK is designed as a lightweight, framework-agnostic foundation that offers:\n\n- **Core event models** - Type-safe event definitions matching the AG-UI protocol specification\n- **Runtime schema validation** - Pydantic-based schemas for early validation of payloads\n- **Event encoding** - Utilities for encoding events into SSE format\n- **State management** - Typed state models for bidirectional state synchronization\n\nThe 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.\n\n## Architecture\n\nThe Python SDK follows a modular architecture with distinct layers:\n\n```mermaid\ngraph TD\n A[Application Layer] --> B[SDK Core]\n B --> C[Event Models]\n B --> D[Type Definitions]\n B --> E[Encoder]\n C --> F[ag_ui.core.events]\n D --> G[ag_ui.core.types]\n E --> H[ag_ui.encoder.encoder]\n F --> I[Runtime Validation]\n G --> I\n H --> J[SSE Output]\n J --> K[Frontend Client]\n```\n\n## Package Structure\n\n| Module | Purpose |\n|--------|---------|\n| `ag_ui.core.events` | Event class definitions and factories for all AG-UI event types |\n| `ag_ui.core.types` | Core type definitions including `Message`, `Tool`, `Context`, `RunAgentInput`, and `State` |\n| `ag_ui.encoder.encoder` | Event encoding utilities for SSE serialization |\n\n## Event System\n\nThe SDK defines 16 core event kinds covering the complete AG-UI protocol lifecycle:\n\n### Event Categories\n\n| Category | Events | Purpose |\n|----------|--------|---------|\n| **Run Lifecycle** | `RUN_STARTED`, `RUN_FINISHED` | Mark the beginning and end of an agent run |\n| **Text Messages** | `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END` | Stream text responses to the client |\n| **Tool Calls** | `TOOL_CALL_START`, `TOOL_CALL_ARGUMENTS`, `TOOL_CALL_END` | Execute backend tools |\n| **Tool Results** | `TOOL_CALL_RESULT` | Return tool execution results |\n| **State Updates** | `STATE_SNAPSHOT`, `STATE_DELTA` | Synchronize shared state with frontend |\n| **UI Triggers** | `PATCH_ASSET`, `CUSTOM_EVENT`, `AGENT_TOOL_CALLS` | Trigger frontend UI updates |\n\n### Event Validation\n\nEvents are validated at runtime using Pydantic schemas. This ensures malformed payloads are caught early and provides clear error messages for debugging.\n\n```python\nfrom ag_ui.core.events import EventSchemas, EventType\n\n# Validate an incoming event\nvalidated_event = EventSchemas.parse({\n \"type\": EventType.TEXT_MESSAGE_CONTENT,\n \"messageId\": \"msg_123\",\n \"delta\": \"Hello, world!\"\n})\n```\n\n## Core Types\n\nThe SDK provides strongly-typed data models for AG-UI concepts:\n\n| Type | Description |\n|------|-------------|\n| `Message` | Represents a conversation message with role and content |\n| `Tool` | Tool definition including name, description, and parameters |\n| `Context` | Execution context including thread_id and run_id |\n| `RunAgentInput` | Input payload for initiating an agent run |\n| `State` | Shared application state with type-safe access |\n\n## Event Encoding\n\nThe encoder module handles serialization of AG-UI events into Server-Sent Events format:\n\n```mermaid\nsequenceDiagram\n participant App as Application\n participant SDK as Python SDK\n participant Encoder as Event Encoder\n participant Client as Frontend\n\n App->>SDK: Create event object\n SDK->>Encoder: Encode to SSE format\n Encoder->>Client: data: {\"type\": \"...\", ...}\\n\\n\n Client->>Client: Parse and render\n```\n\nThe encoder ensures proper SSE formatting with:\n- JSON serialization of event data\n- Double newline termination as per SSE spec\n- Support for event type naming\n\n## Integration Patterns\n\nThe Python SDK is used as the foundation for framework-specific integrations:\n\n### Direct Usage\n\n```python\nfrom ag_ui import AGUIServer, Agent\n\nagent = Agent(name=\"my_agent\")\nserver = AGUIServer(agent=agent)\n\n# Stream events to client\nasync for event in agent.run(input_data):\n await server.send(event)\n```\n\n### Integration Ecosystem\n\n| Integration | Package | Description |\n|-------------|---------|-------------|\n| Langroid | `langroid` | Multi-agent framework with AG-UI support |\n| Claude Agent SDK | `ag_ui_claude_sdk` | Anthropic Claude integration |\n| ADK Middleware | `ag_ui_adk` | Google Agent Development Kit adapter |\n| Microsoft Agent Framework | `ag_ui_microsoft` | Azure AI Agent Service integration |\n| Pydantic AI | `pydantic_ai` | Pydantic-based agent framework |\n\n## Installation\n\n```bash\npip install ag-ui\n# or with uv\nuv pip install ag-ui\n```\n\n## Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `AG_UI_BASE_URL` | Base URL of the AG-UI server | `http://127.0.0.1:8000` |\n| `AG_UI_API_KEY` | API key for authentication | None |\n\n## Testing\n\nThe SDK includes a comprehensive test suite with mock server support:\n\n```bash\n# Run tests\npytest\n\n# With coverage\npytest --cov=src/ag_ui\n\n# Specific test file\npytest tests/test_events.py\n```\n\n## Documentation\n\nAdditional documentation is available at:\n- Concepts & architecture: [`docs/concepts`](https://docs.ag-ui.com/concepts/architecture)\n- Python SDK reference: [`docs/sdk/python/core`](https://docs.ag-ui.com/sdk/python/core/overview)\n- Full API reference: [`docs/events`](https://docs.ag-ui.com/concepts/events)\n\n## Contributing\n\nBug reports and pull requests are welcome. Please read the [contributing guide](https://docs.ag-ui.com/development/contributing) before submitting changes.\n\n## License\n\nMIT © 2025 AG-UI Protocol Contributors\n\n---\n\n\n\n## Community SDKs\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#typescript-sdk), [Python SDK](#python-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [sdks/community/dart/example/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/dart/example/README.md)\n- [sdks/community/ruby/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/ruby/README.md)\n- [sdks/community/c++/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/c++/README.md)\n- [sdks/community/java/packages/client/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/client/README.md)\n- [sdks/community/java/clients/ok-http/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/clients/ok-http/README.md)\n- [integrations/langroid/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/README.md)\n- [integrations/langroid/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/typescript/README.md)\n \n\n# Community SDKs\n\nThe 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.\n\n## Overview\n\nCommunity 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:\n\n- Event encoding and decoding following the AG-UI event schema\n- HTTP/WebSocket communication with AG-UI servers\n- State synchronization between agent and client\n- Tool call handling and response streaming\n\n资料来源：[sdks/community/ruby/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/ruby/README.md)\n\n## Supported Languages\n\nThe AG-UI community has contributed SDK implementations for the following programming languages:\n\n| Language | Package Name | Status | Key Features |\n|----------|--------------|--------|--------------|\n| Kotlin | `@ag-ui/kotlin` | Active | JVM-compatible, coroutines support |\n| Go | `@ag-ui/go` | Active | Lightweight, concurrent-friendly |\n| Dart | `@ag-ui/dart` | Active | Flutter/dart ecosystem support |\n| Java | `com.ag-ui.community` | Active | Enterprise-grade, OkHttp client |\n| Ruby | `ag_ui` | Active | Ruby idiomatic API |\n| Rust | `ag-ui-client` | Active | Memory-safe, high performance |\n| C++ | `agui` | Active | Cross-platform, minimal dependencies |\n\n## Architecture Pattern\n\nAll community SDKs follow a consistent architectural pattern for AG-UI integration:\n\n```mermaid\ngraph TD\n A[AG-UI Client/Frontend] <--> |SSE/WebSocket| B[Community SDK Server]\n B --> C[Language-Specific Agent Implementation]\n C --> D[Agent Logic/Tools]\n B --> E[State Management]\n E --> A\n \n F[Event Encoder] --> B\n G[Event Decoder] --> B\n```\n\n### Component Responsibilities\n\n| Component | Purpose |\n|-----------|---------|\n| HTTP Client | Handles communication with AG-UI server endpoints |\n| Event Encoder | Serializes events to AG-UI protocol format |\n| Event Decoder | Deserializes incoming events from clients |\n| State Manager | Maintains shared state synchronization |\n| Tool Handler | Processes and responds to tool calls |\n\n资料来源：[integrations/langroid/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/README.md)\n\n## Dart SDK\n\nThe Dart SDK enables Flutter and Dart applications to interact with AG-UI protocol servers. It provides both synchronous and asynchronous communication patterns.\n\n### Environment Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AG_UI_BASE_URL` | Base URL of the AG-UI server | `http://127.0.0.1:8000` |\n| `AG_UI_API_KEY` | API key for authentication | None |\n| `DEBUG` | Enable debug logging | `false` |\n\n### Basic Usage\n\n```dart\nimport 'package:ag_ui_dart/ag_ui_dart.dart';\n\n// Create an HTTP Agent\nfinal agent = HttpAgent(\n url: 'http://localhost:8080/api/agent/run',\n agentId: 'my-agent',\n);\n\n// Subscribe to events\nagent.subscribe((event) {\n print('Received event: ${event.type}');\n});\n\n// Send user message\nawait agent.sendMessage('Hello, agent!');\n```\n\n资料来源：[sdks/community/dart/example/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/dart/example/README.md)\n\n## Ruby SDK\n\nThe Ruby SDK provides idiomatic Ruby integration for the AG-UI protocol, suitable for Ruby on Rails applications or standalone Ruby agents.\n\n### Installation\n\n```bash\ncd sdks/community/ruby\nbundle install\n```\n\n### Running Examples\n\n```bash\n# Navigate to example directory\ncd sdks/community/ruby/example/simple-use\n\n# Install dependencies\nbundle install\n\n# Run the example\nbundle exec ruby main.rb\n```\n\n### Testing\n\n```bash\ncd sdks/community/ruby\nrake test\n```\n\n### Documentation\n\nGenerate YARD documentation:\n\n```bash\ncd sdks/community/ruby\nrake doc\n```\n\n资料来源：[sdks/community/ruby/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/ruby/README.md)\n\n## C++ SDK\n\nThe C++ SDK provides a header-only, dependency-light implementation suitable for embedded systems and performance-critical applications.\n\n### Build Dependencies\n\n| Platform | Required Packages |\n|----------|-------------------|\n| macOS | cmake, pkg-config, nlohmann-json3, libcurl |\n| Ubuntu/Debian | cmake, g++, pkg-config, nlohmann-json3-dev, libcurl4-openssl-dev |\n| Google Test | libgtest-dev (optional, for testing) |\n\n### Building the SDK\n\n```bash\n# Clone and navigate to C++ SDK directory\ngit clone https://github.com/ag-ui-protocol/ag-ui.git\ncd ag-ui/sdks/community/c++\n\n# Create build directory\nmkdir build && cd build\n\n# Configure with tests enabled\ncmake -DBUILD_TESTS=ON ..\n\n# Build\nmake -j4\n```\n\n### Basic Usage\n\n```cpp\n#include \"agent/http_agent.h\"\n\nusing namespace agui;\n\nint main() {\n auto agent = HttpAgent::builder()\n .withUrl(\"http://localhost:8080/api/agent/run\")\n .withAgentId(AgentId(\"my-agent\"))\n .build();\n \n // Create subscriber for events\n class MySubscriber : public IAgentSubscriber {\n AgentStateMutation onTextMessageContent(\n const TextMessageContentEvent& event,\n const std::string& buffer,\n const AgentSubscriberParams& params) override {\n std::cout << event.delta;\n return AgentStateMutation::CONTINUE;\n }\n };\n \n agent->subscribe(std::make_shared());\n return 0;\n}\n```\n\n资料来源：[sdks/community/c++/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/c++/README.md)\n\n## Java SDK\n\nThe Java SDK provides enterprise-grade AG-UI protocol support with two main components: the core client and an OkHttp-based HTTP client.\n\n### Maven Dependency\n\n```xml\n\n com.ag-ui.community\n java-client\n 0.0.1\n\n```\n\n### OkHttp Client\n\nFor applications using OkHttp:\n\n```xml\n\n com.ag-ui.community\n java-ok-http\n 4.12.0\n\n```\n\n### Key Components\n\n| Component | Description |\n|-----------|-------------|\n| `AbstractAgent` | Base class for agent implementations |\n| `HttpClient` | OkHttp-based HTTP communication |\n| Event handlers | Process AG-UI streaming events |\n\n资料来源：[sdks/community/java/packages/client/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/packages/client/README.md)\n\n资料来源：[sdks/community/java/clients/ok-http/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/java/clients/ok-http/README.md)\n\n## Kotlin SDK\n\nThe Kotlin SDK provides AG-UI protocol support for JVM applications with idiomatic Kotlin patterns including coroutines support and DSL-style builders.\n\n### Overview\n\nThe Kotlin SDK offers:\n\n- Coroutines-based asynchronous communication\n- Type-safe builders for agent configuration\n- Seamless interoperability with Java\n\n资料来源：[docs/sdk/kotlin/overview.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/kotlin/overview.mdx)\n\n## Go SDK\n\nThe Go SDK provides lightweight AG-UI protocol integration optimized for concurrent operations and minimal memory footprint.\n\n### Features\n\n- Goroutine-friendly concurrent event processing\n- Channel-based event streaming\n- Minimal dependencies\n- High performance for production workloads\n\n资料来源：[docs/sdk/go/overview.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/sdk/go/overview.mdx)\n\n## Rust SDK\n\nThe Rust SDK (`ag-ui-client`) offers memory-safe, high-performance AG-UI protocol support suitable for systems programming and performance-critical applications.\n\n### Key Features\n\n- Zero-cost abstractions\n- Async runtime support\n- Memory safety guarantees\n- Small binary footprint\n\n## Integration with Langroid\n\nThe Langroid integration demonstrates how community SDKs can bridge different agent frameworks with the AG-UI protocol.\n\n```mermaid\ngraph LR\n A[TypeScript Frontend] <--> B[Langroid TypeScript Client]\n B <--> C[Langroid Python Server]\n C --> D[Python Agent Implementation]\n \n E[Python Tools] --> D\n F[AG-UI Tools] --> B\n```\n\n### Langroid Python Integration\n\n```bash\n# Install dependencies\ncd python\npip install -e .\ncd examples\npip install -e .\n```\n\n### Langroid TypeScript Client\n\n```typescript\nimport { LangroidHttpAgent } from \"@ag-ui/langroid\";\n\nconst agent = new LangroidHttpAgent({\n url: \"http://localhost:8000/\",\n});\n```\n\n资料来源：[integrations/langroid/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/README.md)\n\n资料来源：[integrations/langroid/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langroid/typescript/README.md)\n\n## Contributing\n\nCommunity SDK contributions are welcome. The project maintains contribution guidelines that all SDK contributors should follow.\n\n### Contribution Process\n\n1. Create a new directory under `sdks/community//`\n2. Implement the AG-UI event protocol specification\n3. Include README.md with installation and usage instructions\n4. Add tests for core functionality\n5. Submit a pull request for review\n\n### Quality Standards\n\n| Requirement | Description |\n|-------------|-------------|\n| Documentation | Clear README with setup and usage examples |\n| Testing | Unit tests for core components |\n| Type Safety | Strong typing where applicable |\n| Error Handling | Graceful error management |\n\n资料来源：[sdks/community/ruby/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/ruby/README.md)\n\n## License\n\nAll community SDKs are released under the MIT License. See the main AG-UI repository for complete license information.\n\n---\n\n*Last updated: Based on repository state as of latest commit.*\n\n---\n\n\n\n## LangGraph Integration\n\n### 相关页面\n\n相关主题：[Python SDK](#python-sdk), [TypeScript SDK](#typescript-sdk)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [integrations/langgraph/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/README.md)\n- [integrations/langgraph/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/package.json)\n- [integrations/langgraph/typescript/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/examples/README.md)\n- [integrations/langgraph/typescript/examples/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/examples/package.json)\n- [integrations/langgraph/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/python/README.md)\n- [docs/integrations.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/integrations.mdx)\n \n\n# LangGraph Integration\n\nThe `@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.\n\n## Overview\n\nLangGraph is a library for building stateful, multi-actor applications with Large Language Models (LLMs). The AG-UI LangGraph integration extends these capabilities by providing:\n\n- Bidirectional state synchronization between graph nodes and frontend interfaces\n- Real-time streaming event support for assistant messages, tool calls, and state updates\n- Human-in-the-loop workflow support through interrupt handling\n- Step tracking for real-time node execution progress monitoring\n- Full compatibility with LangGraph Cloud and local graph deployments\n\n资料来源：[integrations/langgraph/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/README.md)\n\n## Architecture\n\nThe integration follows a layered architecture that separates concerns between the agent runtime, state management, event streaming, and frontend communication.\n\n```mermaid\ngraph TD\n subgraph Frontend[\"Frontend Client\"]\n A[AG-UI Client]\n B[CopilotKit]\n C[Custom UI]\n end\n\n subgraph LangGraphIntegration[\"@ag-ui/langgraph\"]\n D[LangGraphAgent]\n E[State Streaming Middleware]\n F[Event Emitters]\n end\n\n subgraph LangGraph[\"LangGraph Runtime\"]\n G[Graph Definition]\n H[Graph Nodes]\n I[State Store]\n end\n\n A --> D\n B --> D\n C --> D\n D --> E\n E --> F\n F --> A\n G --> H\n H --> I\n I --> E\n```\n\n### Core Components\n\n| Component | Description | Package |\n|-----------|-------------|---------|\n| `LangGraphAgent` | Main agent class for connecting to LangGraph | `@ag-ui/langgraph` |\n| `StateStreamingMiddleware` | Middleware for state synchronization | `@ag-ui/langgraph` |\n| Event Emitters | Streams AG-UI protocol events to clients | `@ag-ui/core` |\n| Graph Store | LangGraph state persistence | `@langchain/langgraph-sdk` |\n\n资料来源：[integrations/langgraph/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/README.md)\n\n## Features\n\n### Cloud & Local Support\n\nThe integration operates seamlessly across two deployment modes:\n\n**Local Mode**: Connect directly to TypeScript or Python graph instances running locally. This mode provides full control over the graph execution and state management.\n\n**Cloud Mode**: Connect to remote LangGraph Cloud deployments via the LangGraph SDK. This mode leverages LangGraph's cloud infrastructure for scalability and reliability.\n\n```mermaid\ngraph LR\n subgraph Deployment[\"Deployment Options\"]\n L[Local Deployment]\n C[Cloud Deployment]\n end\n\n L -->|Direct Connection| AG[@ag-ui/langgraph]\n C -->|LangGraph SDK| AG\n\n AG -->|AG-UI Events| FE[Frontend]\n```\n\n资料来源：[integrations/langgraph/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/README.md)\n\n### State Management\n\nThe integration provides bidirectional state synchronization between the LangGraph state store and the AG-UI protocol:\n\n- **Read State**: Middleware reads graph state at configurable intervals or triggers\n- **Write State**: Frontend can update shared state through AG-UI state update events\n- **Conflict Resolution**: Last-write-wins semantics with optional optimistic updates\n\n```mermaid\nsequenceDiagram\n participant FE as Frontend\n participant MW as State Middleware\n participant GS as Graph State\n participant LG as LangGraph\n\n FE->>MW: subscribeToState()\n MW->>GS: getState()\n GS-->>MW: currentState\n MW-->>FE: stateUpdate event\n\n LG->>GS: updateState()\n GS-->>LG: stateUpdated\n LG->>MW: notifyChange()\n MW->>FE: stateUpdate event\n```\n\n资料来源：[integrations/langgraph/typescript/src/middlewares/state-streaming.ts](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/src/middlewares/state-streaming.ts)\n\n### Interrupt Handling\n\nHuman-in-the-loop workflows are supported through LangGraph's interrupt mechanism. When an interrupt occurs, the integration:\n\n1. Pauses graph execution at designated checkpoints\n2. Streams current state and pending actions to the frontend\n3. Waits for human approval/rejection/input\n4. Resumes execution with the provided feedback\n\n### Step Tracking\n\nReal-time progress updates track node execution through the graph:\n\n```typescript\ninterface StepUpdate {\n stepId: string;\n nodeName: string;\n status: 'pending' | 'running' | 'completed' | 'error';\n metadata?: Record;\n}\n```\n\n## Installation\n\n### TypeScript\n\n```bash\nnpm install @ag-ui/langgraph\npnpm add @ag-ui/langgraph\nyarn add @ag-ui/langgraph\n```\n\n**Peer Dependencies**:\n\n| Package | Version Requirement |\n|---------|---------------------|\n| `@ag-ui/core` | `>=0.0.42` |\n| `@ag-ui/client` | `>=0.0.42` |\n| `rxjs` | `7.8.1` |\n\n资料来源：[integrations/langgraph/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/package.json)\n\n### Python\n\n```bash\npip install ag-ui-langgraph\n```\n\n## Usage\n\n### TypeScript Example\n\n```typescript\nimport { LangGraphAgent } from \"@ag-ui/langgraph\";\n\n// Create an AG-UI compatible agent\nconst agent = new LangGraphAgent({\n graphId: \"my-graph\",\n deploymentUrl: \"https://your-langgraph-deployment.com\",\n langsmithApiKey: \"your-api-key\",\n});\n\n// Run with streaming\nconst result = await agent.runAgent({\n messages: [{ role: \"user\", content: \"Start the workflow\" }],\n});\n\n// Subscribe to state updates\nagent.subscribeToState((state) => {\n console.log(\"State updated:\", state);\n});\n```\n\n资料来源：[integrations/langgraph/typescript/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/README.md)\n\n### Python Example\n\n```python\nfrom ag_ui_langgraph import LangGraphAgent, AgentInput\n\nagent = LangGraphAgent(\n graph_id=\"my-graph\",\n deployment_url=\"https://your-langgraph-deployment.com\"\n)\n\nasync for event in agent.run_agent(AgentInput(\n messages=[{\"role\": \"user\", \"content\": \"Hello\"}]\n)):\n print(event)\n```\n\n资料来源：[integrations/langgraph/python/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/python/README.md)\n\n## Configuration Options\n\n### LangGraphAgent Configuration\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `graphId` | `string` | Yes | Identifier for the LangGraph graph |\n| `deploymentUrl` | `string` | No | LangGraph Cloud deployment URL (local if omitted) |\n| `langsmithApiKey` | `string` | No | API key for LangSmith observability |\n| `threadId` | `string` | No | Thread identifier for conversation state |\n| `stateMiddleware` | `StateMiddleware` | No | Custom state synchronization middleware |\n\n### State Streaming Middleware\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `pollInterval` | `number` | `1000` | Interval in ms for polling state changes |\n| `debounceMs` | `number` | `300` | Debounce delay for rapid state updates |\n| `includeMetadata` | `boolean` | `true` | Include node metadata in state updates |\n| `filterNodes` | `string[]` | `[]` | Only stream state for specific nodes |\n\n## Available Agents\n\nThe integration includes TypeScript examples demonstrating various agent patterns:\n\n### 1. Agentic Chat (`agentic_chat`)\n\nA simple agentic chat flow using LangGraph following the ReAct design pattern. Handles tool binding, system prompts, and model responses.\n\n### 2. Agentic Generative UI (`agentic_generative_ui`)\n\nDemonstrates agentic generative UI capabilities. Creates task steps and simulates their execution while streaming updates to the frontend.\n\n### 3. Human in the Loop (`human_in_the_loop`)\n\nImplements human-in-the-loop functionality where users can interact with and modify the agent's proposed steps before execution.\n\n### 4. Predictive State Updates (`predictive_state_updates`)\n\nShows predictive state updates for document writing with streaming tool calls to the frontend.\n\n### 5. Shared State (`shared_state`)\n\nDemonstrates shared state management between the agent and CopilotKit, focusing on recipe creation and modification.\n\n资料来源：[integrations/langgraph/typescript/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/examples/README.md)\n\n## Running the Examples\n\n### TypeScript Examples\n\n```bash\ncd integrations/langgraph/typescript/examples\n\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Start with LangGraph CLI\npnpx @langchain/langgraph-cli@1.1.13 dev\n```\n\n### Python Examples\n\n```bash\ncd integrations/langgraph/python/examples\n\n# Create .env file\ncp .env.example .env\n\n# Add your API keys\n# OPENAI_API_KEY=your-key\n\n# Install dependencies\npip install -e .\n\n# Run the server\npoetry run python -m server\n```\n\nThe server will start on `http://0.0.0.0:8003`.\n\n资料来源：[integrations/langgraph/typescript/examples/README.md](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/examples/README.md)\n\n## Development\n\n### Build Commands\n\n| Command | Description |\n|---------|-------------|\n| `npm run build` | Compile TypeScript to JavaScript |\n| `npm run dev` | Watch mode for development |\n| `npm run typecheck` | Run TypeScript type checking |\n| `npm run test` | Run test suite |\n| `npm run test:coverage` | Run tests with coverage report |\n\n### Testing\n\n```bash\n# Run all tests\nnpm run test\n\n# Watch mode for development\nnpm run test:watch\n\n# Coverage report\nnpm run test:coverage\n\n# Export validation\nnpm run test:exports\n```\n\n## Dependencies\n\nThe integration depends on the following packages:\n\n| Package | Purpose |\n|---------|---------|\n| `@langchain/core` | Core LangChain functionality |\n| `@langchain/langgraph-sdk` | LangGraph SDK for cloud deployments |\n| `langchain` | LangChain integration |\n| `partial-json` | JSON parsing for partial responses |\n| `rxjs` | Reactive extensions for event streaming |\n\n资料来源：[integrations/langgraph/typescript/package.json](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/langgraph/typescript/package.json)\n\n## Related Integrations\n\nFor other agent framework integrations, see the main integrations documentation:\n\n- **ADK Middleware**: Google Agent Development Kit integration\n- **PydanticAI**: PydanticAI agent integration\n- **Claude Agent SDK**: Anthropic Claude agent integration\n- **Langroid**: Multi-agent framework integration\n- **CrewAI**: CrewAI agent integration\n- **Mastra**: Mastra agent integration\n- **Agno**: Agno agent integration\n- **LlamaIndex**: LlamaIndex agent integration\n- **A2A Middleware**: Agent-to-Agent protocol middleware\n\n资料来源：[docs/integrations.mdx](https://github.com/ag-ui-protocol/ag-ui/blob/main/docs/integrations.mdx)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：ag-ui-protocol/ag-ui\n\n摘要：发现 13 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature]: Update Zod to ^4.0.0。\n\n## 1. 安装坑 · 来源证据：[Feature]: Update Zod to ^4.0.0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Update Zod to ^4.0.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_864feb35f0a7491399ed9e6f32d716d0 | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Java dependencies not found\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Java dependencies not found\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_76cfe35c206349ceb926d2253bc2cf03 | https://github.com/ag-ui-protocol/ag-ui/issues/930 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53c2f6a0605444afbd53e56d090a6295 | https://github.com/ag-ui-protocol/ag-ui/issues/1454 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 失败模式：installation: [Feature]: Update Zod to ^4.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Feature]: Update Zod to ^4.0.0\n- 对用户的影响：Developers may fail before the first successful local run: [Feature]: Update Zod to ^4.0.0\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_334526f2cd6ed9dc89c052647aa8d0eb | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | [Feature]: Update Zod to ^4.0.0\n\n## 5. 配置坑 · 失败模式：configuration: Java dependencies not found\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Java dependencies not found\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Java dependencies not found\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_cc82631789b14e6fa478fc47a467a6bd | https://github.com/ag-ui-protocol/ag-ui/issues/930 | Java dependencies not found\n\n## 6. 配置坑 · 失败模式：configuration: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- 建议检查：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\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 7. 配置坑 · 来源证据：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6674fe14155d4baeb366f4ac441fd962 | https://github.com/ag-ui-protocol/ag-ui/issues/1719 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | README/documentation is current enough for a first validation pass.\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | no_demo; severity=medium\n\n## 12. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | issue_or_pr_quality=unknown\n\n## 13. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：ag-ui-protocol/ag-ui\n\n摘要：发现 13 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Feature]: Update Zod to ^4.0.0。\n\n## 1. 安装坑 · 来源证据：[Feature]: Update Zod to ^4.0.0\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Feature]: Update Zod to ^4.0.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_864feb35f0a7491399ed9e6f32d716d0 | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Java dependencies not found\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Java dependencies not found\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_76cfe35c206349ceb926d2253bc2cf03 | https://github.com/ag-ui-protocol/ag-ui/issues/930 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_53c2f6a0605444afbd53e56d090a6295 | https://github.com/ag-ui-protocol/ag-ui/issues/1454 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 失败模式：installation: [Feature]: Update Zod to ^4.0.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this installation risk before relying on the project: [Feature]: Update Zod to ^4.0.0\n- 对用户的影响：Developers may fail before the first successful local run: [Feature]: Update Zod to ^4.0.0\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_334526f2cd6ed9dc89c052647aa8d0eb | https://github.com/ag-ui-protocol/ag-ui/issues/1397 | [Feature]: Update Zod to ^4.0.0\n\n## 5. 配置坑 · 失败模式：configuration: Java dependencies not found\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: Java dependencies not found\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Java dependencies not found\n- 建议检查：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.\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：failure_mode_cluster:github_issue | fmev_cc82631789b14e6fa478fc47a467a6bd | https://github.com/ag-ui-protocol/ag-ui/issues/930 | Java dependencies not found\n\n## 6. 配置坑 · 失败模式：configuration: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：Developers should check this configuration risk before relying on the project: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: `RunAgentInput` should allow `null` for `threadId`/`runId` to support server-minted IDs\n- 建议检查：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\n- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.\n- 证据：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\n\n## 7. 配置坑 · 来源证据：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: [ag_ui_adk] _shallow_copy_agent_tree does not re-parent sub-agents, breaking transfer_to_agent resolution\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6674fe14155d4baeb366f4ac441fd962 | https://github.com/ag-ui-protocol/ag-ui/issues/1719 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | README/documentation is current enough for a first validation pass.\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | no_demo; severity=medium\n\n## 12. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | issue_or_pr_quality=unknown\n\n## 13. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:979392131 | https://github.com/ag-ui-protocol/ag-ui | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# ag-ui - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for ag-ui-protocol/ag-ui.\n\nProject:\n- Name: ag-ui\n- Repository: https://github.com/ag-ui-protocol/ag-ui\n- Summary: AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. intro: Introduction to AG-UI. Produce one small intermediate artifact and wait for confirmation.\n2. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. events: Event Specification. Produce one small intermediate artifact and wait for confirmation.\n4. types-messages: Types & Messages. Produce one small intermediate artifact and wait for confirmation.\n5. typescript-sdk: TypeScript SDK. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/ag-ui-protocol/ag-ui\n- https://github.com/ag-ui-protocol/ag-ui#readme\n- README.md\n- docs/introduction.mdx\n- docs/concepts/architecture.mdx\n- docs/ag_ui.md\n- docs/concepts/capabilities.mdx\n- sdks/typescript/packages/core/src/events.ts\n- sdks/typescript/packages/core/src/event-factories.ts\n- sdks/python/ag_ui/core/events.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：ag-ui-protocol/ag-ui\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx create-ag-ui-app\n```\n\n来源：https://github.com/ag-ui-protocol/ag-ui#readme\n\n## 来源\n\n- repo: https://github.com/ag-ui-protocol/ag-ui\n- docs: https://github.com/ag-ui-protocol/ag-ui#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_42f281090908484ebb30ed913ed8a721"
}