ag2-overview

AG2 — 能力地图

AG2（ag2）是一个异步、由协议驱动的 Agent 框架。完整参考文档位于 website/docs/user-guide/ 下。本技能是涵盖常见构建路径的相关技能索引。

适用场景

当请求提到“AG2”“ag2”或在此仓库中构建 Agent，而你还不清楚需要哪项功能时，请先阅读此文件。使用下表选择合适的专项技能，然后加载该技能的 SKILL.md 查看操作指南。

开始之前

使用 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”。

选择合适的技能

用户意图	技能	涵盖内容
从头构建 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 / dataclass 输出	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、模拟大模型响应、模拟 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 CI、翻转、κ）、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、stdio / 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 semconv 属性、内容捕获

多 Agent 网络

每当两个或更多 Agent 需要交互时，先加载 ag2-network-quickstart —— 网络是 AG2 中标准的多 Agent 模式。它涵盖 Hub 的设置和两种双边通道适配器（严格的 1Q1R 对应 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 种示例模式、经典 GroupChat 迁移
速率限制、访问策略、预期、审计、能力跟踪	ag2-network-governance	Rule（AccessBlock／LimitsBlock／RateBlock／InboxBlock）、Expectation、审计日志 + AUDIT_KIND_*、任务观测、Resume.observed
自定义信封处理器、视图策略、对等方发现、面向大模型的网络工具	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 协作的场景。