Back to Details

ag2-overview

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AG2 — capability map

AG2 — 功能映射

AG2 (
ag2
) is an async, protocol-driven agent framework. The full reference docs live under 
website/docs/user-guide/
. This skill is the index of sibling skills that cover the common build paths.
AG2（
ag2
）是一个异步、协议驱动的Agent框架。完整参考文档位于
website/docs/user-guide/
。本技能是涵盖常见构建路径的子技能索引。

When to use

使用场景

Read this file first when a request mentions "AG2", "ag2", or building agents in this repo and you don't yet know which feature is needed. Use the table below to pick the right specialised skill, then load that skill's 
SKILL.md
for the recipe.
当请求中提及"AG2"、"ag2"或在此仓库中构建Agent，但尚未明确所需功能时，请先阅读本文档。使用下表选择合适的专业技能，然后加载该技能的
SKILL.md
获取实现方案。

Before you start

前置准备

Anything you build with AG2 needs three things in place. Get these right once and the rest of the skills run cleanly:
  1. Install the right provider extra — 
    pip install "ag2[openai]"
    , 
    ag2[anthropic]
    , 
    ag2[gemini]
    , etc. The 
    *Config
    class will raise 
    ImportError: ... requires optional dependencies
    without it. Run the install before delivering code. If you cannot run commands, state the exact 
    pip install
    command. This is a required step.
  2. Set the matching API key — 
    OPENAI_API_KEY
    , 
    ANTHROPIC_API_KEY
    , 
    GEMINI_API_KEY
    (or 
    GOOGLE_API_KEY
    ). Loading from a project-root 
    .env
    via 
    from dotenv import load_dotenv; load_dotenv()
    is the common pattern.
  3. Sanity-check the install — 
    python -c "import sys, ag2; from importlib.metadata import version; print(sys.executable, version('ag2'))"
    . If you have multiple Python environments, this confirms which 
    ag2
    your script will actually import.
Full per-provider table (install + env var + config class) lives in 
ag2-quickstart
→ "Prerequisites".
使用AG2构建任何内容都需要准备以下三项。配置好这些后，其余技能就能顺利运行：
  1. 安装对应的扩展依赖 —— 
    pip install "ag2[openai]"
    、
    ag2[anthropic]
    、
    ag2[gemini]
    等。如果没有安装，
    *Config
    类会抛出
    ImportError: ... requires optional dependencies
    错误。在交付代码前务必执行安装命令。如果无法执行命令，请明确给出具体的
    pip install
    指令。这是必填步骤。
  2. 设置匹配的API密钥 —— 
    OPENAI_API_KEY
    、
    ANTHROPIC_API_KEY
    、
    GEMINI_API_KEY
    （或
    GOOGLE_API_KEY
    ）。常见的做法是通过
    from dotenv import load_dotenv; load_dotenv()
    从项目根目录的
    .env
    文件加载密钥。
  3. 验证安装正确性 —— 
    python -c "import sys, ag2; from importlib.metadata import version; print(sys.executable, version('ag2'))"
    。如果存在多个Python环境，此命令可确认脚本实际导入的是哪个环境的
    ag2
    。
完整的各供应商对应表格（安装命令+环境变量+配置类）可在
ag2-quickstart
→ "Prerequisites"中查看。

Pick the right skill

选择合适的技能

User intentSkillWhat it covers
Build an 
Agent
from scratch, pick a model
ag2-quickstart
Agent
, 
ModelConfig
, 
ask()
/ 
reply.ask()
chaining, providers, env vars
Give the Agent a custom Python tool
ag2-add-custom-tool
@tool
, sync/async, 
ToolResult
, 
Context
, 
Inject
, 
Variable
, 
Depends
Use shipped tools (web search, code exec, MCP, etc.)
ag2-use-builtin-tools
WebSearchTool
, 
WebFetchTool
, 
CodeExecutionTool
, 
MCPServerTool
, 
ImageGenerationTool
, 
MemoryTool
, 
FilesystemToolkit
, 
DuckDuckSearchTool
, 
ExaToolkit
, 
TavilySearchTool
Run shell commands from an agent
ag2-shell-tool
SandboxShellTool
+ 
LocalEnvironment
(any provider), provider-side 
ShellTool
(OpenAI Responses), sandboxing (
allowed
/
blocked
/
ignore
/
readonly
)
Get typed Pydantic / dataclass output
ag2-structured-output
response_schema=
, 
ResponseSchema
, 
@response_schema
, 
PromptedSchema
, 
reply.content()
, retries
Multi-agent: parallel subtasks or named delegates
ag2-subagent-delegation
tasks=TaskConfig()
, 
run_subtasks(parallel=True)
, 
Agent.as_tool()
, 
persistent_stream
Pause for human input or gate a tool with approval
ag2-hitl
context.input()
, 
hitl_hook
, 
approval_required()
middleware
Logging, retry, history-trim, custom interception
ag2-middleware
BaseMiddleware
, 
LoggingMiddleware
, 
RetryMiddleware
, 
HistoryLimiter
, 
TokenLimiter
, tool middleware
Test agents and tools
ag2-testing
TestConfig
, mocking LLM responses, simulating 
ToolCallEvent
Evaluate / benchmark an agent offline, CI gate, scorers
ag2-evaluation
Suite
, 
run_agent
, 
final_answer_matches
/ 
tool_called
/ 
agent_judge
, 
@scorer
, 
RunResult
, 
TestConfig
, 
evaluate_traces
, 
diff().regressions
Compare models / prompts — leaderboard or head-to-head
ag2-eval-comparison
run_variants
(
Variants({name: Agent}, axis=...)
), 
run_pairwise
+ 
pairwise_judge
(win-rate, Wilson CI, flips, κ), 
human_pairwise
Persistent memory across runs, history compaction, assembly
ag2-knowledge-and-memory
KnowledgeStore
, 
KnowledgeConfig
, 
WorkingMemoryAggregate
, 
AssemblyPolicy
, 
SlidingWindowPolicy
, 
TokenBudgetPolicy
, 
TailWindowCompact
, 
SummarizeCompact
Observability, alerts, halts
ag2-observers-and-alerts
BaseObserver
, 
TokenMonitor
, 
LoopDetector
, 
EventWatch
, 
CadenceWatch
, 
AlertPolicy
, 
HaltEvent
Send images / audio / video / PDFs in
ag2-multimodal-input
ImageInput
, 
AudioInput
, 
VideoInput
, 
DocumentInput
, 
FilesAPI
Web frontend via the AG-UI protocol
ag2-ag-ui
AGUIStream
, FastAPI mount, CopilotKit
Serve an agent as an MCP server (server side)
ag2-mcp
MCPServer
, stdio / HTTP, prompts, resources, 
SessionConfig
, 
AskContext
Expose an agent over the A2A protocol
ag2-a2a
A2AServer
, 
build_jsonrpc
/ 
build_rest
/ 
build_grpc
, 
AgentCard
, 
A2AConfig
(consume remote)
Realtime voice / live audio (talking agent, STT, TTS)
ag2-live
LiveAgent
, 
GeminiRealTimeConfig
/ 
OpenAIRealTimeConfig
, 
SoundDeviceRecorder
/ 
Player
, 
OpenAITranscriber
, 
TTSObserver
OpenTelemetry traces / metrics
ag2-telemetry
TelemetryMiddleware
, GenAI semconv attributes, content capture
用户需求技能覆盖内容
从零构建
Agent
，选择模型
ag2-quickstart
Agent
、
ModelConfig
、
ask()
/ 
reply.ask()
链式调用、供应商、环境变量
为Agent添加自定义Python工具
ag2-add-custom-tool
@tool
、同步/异步、
ToolResult
、
Context
、
Inject
、
Variable
、
Depends
使用内置工具（网页搜索、代码执行、MCP等）
ag2-use-builtin-tools
WebSearchTool
、
WebFetchTool
、
CodeExecutionTool
、
MCPServerTool
、
ImageGenerationTool
、
MemoryTool
、
FilesystemToolkit
、
DuckDuckSearchTool
、
ExaToolkit
、
TavilySearchTool
通过Agent执行Shell命令
ag2-shell-tool
SandboxShellTool
+ 
LocalEnvironment
（支持任意供应商）、供应商侧
ShellTool
（OpenAI Responses）、沙箱机制（
allowed
/
blocked
/
ignore
/
readonly
）
获取类型化的Pydantic / 数据类输出
ag2-structured-output
response_schema=
、
ResponseSchema
、
@response_schema
、
PromptedSchema
、
reply.content()
、重试机制
多Agent：并行子任务或指定代理
ag2-subagent-delegation
tasks=TaskConfig()
、
run_subtasks(parallel=True)
、
Agent.as_tool()
、
persistent_stream
暂停以等待人工输入或通过审批管控工具
ag2-hitl
context.input()
、
hitl_hook
、
approval_required()
中间件
日志、重试、历史截断、自定义拦截
ag2-middleware
BaseMiddleware
、
LoggingMiddleware
、
RetryMiddleware
、
HistoryLimiter
、
TokenLimiter
、工具中间件
测试Agent和工具
ag2-testing
TestConfig
、模拟LLM响应、模拟
ToolCallEvent
离线评估/基准测试Agent、CI门禁、评分器
ag2-evaluation
Suite
、
run_agent
、
final_answer_matches
/ 
tool_called
/ 
agent_judge
、
@scorer
、
RunResult
、
TestConfig
、
evaluate_traces
、
diff().regressions
对比模型/提示词——排行榜或一对一对比
ag2-eval-comparison
run_variants
（
Variants({name: Agent}, axis=...)
）、
run_pairwise
+ 
pairwise_judge
（胜率、Wilson置信区间、翻转率、κ值）、
human_pairwise
跨会话持久化内存、历史压缩、整合
ag2-knowledge-and-memory
KnowledgeStore
、
KnowledgeConfig
、
WorkingMemoryAggregate
、
AssemblyPolicy
、
SlidingWindowPolicy
、
TokenBudgetPolicy
、
TailWindowCompact
、
SummarizeCompact
可观测性、告警、终止
ag2-observers-and-alerts
BaseObserver
、
TokenMonitor
、
LoopDetector
、
EventWatch
、
CadenceWatch
、
AlertPolicy
、
HaltEvent
传入图片/音频/视频/PDF
ag2-multimodal-input
ImageInput
、
AudioInput
、
VideoInput
、
DocumentInput
、
FilesAPI
通过AG-UI协议实现Web前端
ag2-ag-ui
AGUIStream
、FastAPI挂载、CopilotKit
将Agent作为MCP服务器部署（服务端）
ag2-mcp
MCPServer
、标准输入输出/HTTP、提示词、资源、
SessionConfig
、
AskContext
通过A2A协议暴露Agent
ag2-a2a
A2AServer
、
build_jsonrpc
/ 
build_rest
/ 
build_grpc
、
AgentCard
、
A2AConfig
（消费远程服务）
实时语音/直播音频（对话Agent、STT、TTS）
ag2-live
LiveAgent
、
GeminiRealTimeConfig
/ 
OpenAIRealTimeConfig
、
SoundDeviceRecorder
/ 
Player
、
OpenAITranscriber
、
TTSObserver
OpenTelemetry追踪/指标
ag2-telemetry
TelemetryMiddleware
、GenAI语义规范属性、内容捕获

Multi-agent networks

多Agent网络

Whenever two or more agents need to interact, load 
ag2-network-quickstart
 first — the network is the standard multi-agent pattern in AG2. It covers the 
Hub
setup and the two 2-party channel adapters (
consulting
for strict 1Q1R and 
conversation
for free-form). After the quickstart, route to the right deep-dive:
User intentSkillWhat it covers
N-party round-robin / fixed turn order
ag2-network-discussion
discussion
adapter, 
ORDERING_ROUND_ROBIN
knob, 
can_send
probe pattern, view-window sizing
Declarative orchestration / 
TransitionGraph
/ GroupChat migration
ag2-network-workflow
workflow
adapter, 
TransitionGraph.sequence
/ 
.round_robin
, 
Handoff
, 
ToolCalled
, 
ContextEquals
, 
context_vars
, 8 cookbook patterns, classic-
GroupChat
migration
Rate limits, access policy, expectations, audit, capability tracking
ag2-network-governance
Rule
(
AccessBlock
/ 
LimitsBlock
/ 
RateBlock
/ 
InboxBlock
), 
Expectation
s, audit log + 
AUDIT_KIND_*
, task observation, 
Resume.observed
Custom envelope handlers, view policies, peer discovery, the LLM-facing network tools
ag2-network-tools-and-views
adapter-owned 
say
+ the five 
NetworkPlugin
tools (
delegate
/ 
peers
/ 
channels
/ 
tasks
/ 
context
), 
agent_client.on_envelope
, 
ViewPolicy
(
FullTranscript
/ 
WindowedSummary
/ 
NamedWindowedSummary
), 
skill_md
peer discovery, full 
Envelope
/ 
EV_*
reference
Not a network task: if the user has one agent recursively spawning its own sub-tasks (via 
run_subtask
/ 
run_subtasks(parallel=True)
) or calling another agent as a lightweight tool, use 
ag2-subagent-delegation
 — no hub, no registry, no channels. The network is for distinct, registered agents collaborating through a shared hub.
当需要两个或多个Agent交互时，请先加载**
ag2-network-quickstart
**——网络是AG2中的标准多Agent协作模式。它涵盖
Hub
设置以及两种双向通道适配器（
consulting
用于严格的一问一答模式，
conversation
用于自由对话模式）。完成快速入门后，根据需求选择深入学习的方向：
用户需求技能覆盖内容
N方轮询/固定发言顺序
ag2-network-discussion
discussion
适配器、
ORDERING_ROUND_ROBIN
配置项、
can_send
探测模式、视图窗口大小调整
声明式编排/
TransitionGraph
/GroupChat迁移
ag2-network-workflow
workflow
适配器、
TransitionGraph.sequence
/ 
.round_robin
、
Handoff
、
ToolCalled
、
ContextEquals
、
context_vars
、8种 cookbook 模式、经典
GroupChat
迁移方案
速率限制、访问策略、预期、审计、能力跟踪
ag2-network-governance
Rule
（
AccessBlock
/ 
LimitsBlock
/ 
RateBlock
/ 
InboxBlock
）、
Expectation
s、审计日志 + 
AUDIT_KIND_*
、任务观测、
Resume.observed
自定义信封处理器、视图策略、节点发现、面向LLM的网络工具
ag2-network-tools-and-views
适配器专属
say
方法及五种
NetworkPlugin
工具（
delegate
/ 
peers
/ 
channels
/ 
tasks
/ 
context
）、
agent_client.on_envelope
、
ViewPolicy
（
FullTranscript
/ 
WindowedSummary
/ 
NamedWindowedSummary
）、
skill_md
节点发现、完整
Envelope
/ 
EV_*
参考
非网络任务说明： 如果用户需要单个Agent递归生成自身子任务（通过
run_subtask
/ 
run_subtasks(parallel=True)
）或调用另一个Agent作为轻量工具，请使用**
ag2-subagent-delegation
**——无需hub、注册中心或通道。网络模式适用于独立注册的Agent通过共享hub协作的场景。