用途
AG2（ag2）是一个异步、协议驱动的智能体框架。本技能是 AG2 的能力地图，也是兄弟技能的索引，覆盖常见的构建路径。当请求提到“AG2”“ag2”或在本仓库中构建智能体，而尚不清楚需要哪个功能时，应先阅读本文件，再通过下方表格选择对应的专项技能，然后加载该技能的 SKILL.md 获取具体做法。
前置准备
使用 AG2 构建任何内容都需要先完成三件事：
- 安装正确的 provider 扩展：
pip install "ag2[openai]"、ag2[anthropic]、ag2[gemini]等。没有安装时，*Config 类会抛出ImportError: ... requires optional dependencies。应在交付代码前运行安装；如果无法运行命令，需说明确切的 pip install 命令。这是必需步骤。 - 设置匹配的 API Key：
OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY（或GOOGLE_API_KEY）。常见做法是通过项目根目录的 .env 加载：from dotenv import load_dotenv; load_dotenv()。 - 校验安装：
python -c "import sys, ag2; from importlib.metadata import version; print(sys.executable, version('ag2'))"。如果有多个 Python 环境，这可以确认脚本实际会导入哪个 ag2。
完整的按 provider 对照表（安装命令 + 环境变量 + 配置类）位于 ag2-quickstart 的“Prerequisites”部分。
选择正确的技能
| 用户意图 | 技能 | 覆盖内容 |
|---|---|---|
| 从零构建 Agent、选择模型 | ag2-quickstart | Agent、ModelConfig、ask() / reply.ask() 链式调用、providers、环境变量 |
| 为 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 |
| 从智能体运行 shell 命令 | ag2-shell-tool | SandboxShellTool + LocalEnvironment（任意 provider）、provider 侧 ShellTool（OpenAI Responses）、沙箱（allowed/blocked/ignore/readonly） |
| 获取带类型的 Pydantic / dataclass 输出 | ag2-structured-output | response_schema=、ResponseSchema、@response_schema、PromptedSchema、reply.content()、retries |
| 多智能体：并行子任务或命名委派 | 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、工具中间件 |
| 测试智能体与工具 | ag2-testing | TestConfig、模拟 LLM 响应、模拟 ToolCallEvent |
| 离线评估/基准测试智能体、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、flips、κ）、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 mount、CopilotKit |
| 将智能体作为 MCP 服务器提供（服务端） | ag2-mcp | MCPServer、stdio / HTTP、prompts、resources、SessionConfig、AskContext |
| 通过 A2A 协议暴露智能体 | ag2-a2a | A2AServer、build_jsonrpc / build_rest / build_grpc、AgentCard、A2AConfig（消费远程） |
| 实时语音/实时音频（对话智能体、STT、TTS） | ag2-live | LiveAgent、GeminiRealTimeConfig / OpenAIRealTimeConfig、SoundDeviceRecorder / Player、OpenAITranscriber、TTSObserver |
| OpenTelemetry 追踪/指标 | ag2-telemetry | TelemetryMiddleware、GenAI semconv 属性、内容捕获 |
多智能体网络
当两个或更多智能体需要交互时，应先加载 ag2-network-quickstart——网络是 AG2 中标准的多智能体模式。它涵盖 Hub 设置以及两种两方通道适配器（consulting 用于严格 1Q1R，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）、Expectations、审计日志 + 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_* 参考 |
注意：如果用户只有一个智能体递归生成自己的子任务（通过 run_subtask / run_subtasks(parallel=True)）或将另一个智能体作为轻量工具调用，则不属于网络任务，应使用 ag2-subagent-delegation——没有 hub、没有注册表、没有通道。网络用于通过共享 hub 协作的、已注册的独立智能体。
适用场景
本技能适用于在 AG2 框架下构建智能体时进行能力定位与技能路由，帮助开发者从整体上了解 AG2 提供的各项能力，并快速找到对应的专项技能文档。
限制
本技能本身是索引与能力地图，不包含各专项功能的具体实现细节；具体做法需加载对应兄弟技能的 SKILL.md。使用前必须完成 provider 扩展安装、API Key 配置与安装校验。