AG2AG2

模型与开放条件Model & openness

provider 清单是显式的、类型安全的配置类，覆盖云端与本地两条路。

官方 beta/model_configuration 页原文：

"The AG2 framework provides an explicit, predictable, and type-safe way to configure Large Language Models"

每家 provider 一个 Config 类 + 一个 extra：

• OpenAIConfig / OpenAIResponsesConfig（ag2[openai]）
• AnthropicConfig（ag2[anthropic]）
• GeminiConfig / VertexAIConfig（ag2[gemini]）
• BedrockConfig（ag2[bedrock]）
• OllamaConfig（ag2[ollama]）
• DashScopeConfig（ag2[dashscope]）
• XAIConfig（ag2[xai]）
• ZAIConfig（ag2[zai]）

本地 / 自托管明确支持。

官方专列一节 "Self-Hosted and OpenAI-Compatible Models（vLLM, LM Studio, etc.）"， 走 OpenAIConfig 的 base_url。README 亦列出 ag2[ollama]。

Bedrock 于 v1.1.1 改为原生异步客户端 aiobotocore。官方 release 明示为 breaking。

未知 —— 换 provider 后 tool calling / structured output 的可靠性对比，官方未说明 （已查 beta/model_configuration 与 Grok 兼容页）。

运行位置Where it runs

纯 Python 库，异步贯穿，不提供托管服务。

README 原文：

"AG2 requires Python version >= 3.10"

"AG2 is async throughout. Agent.ask(...) starts a turn and returns an AgentReply"

安装是 pip install ag2[openai]。

多 agent 的调度形态官方给了两种链路（network/overview 页）：

• 默认 LocalLink —— 官方描述：

"same-process duplex queues"

即同进程内 hub + agents。

• 换成 WsLink —— 官方描述：

"the hub and each agent as separate OS processes connected over WebSocket"

即 hub 与每个 agent 分处不同操作系统进程。

换链路时 HubClient API 不变、无需改业务代码。

它不运营 agent loop。

库里的一切跑在你自己的进程 / 主机上，官方无 any 托管 offer。

本地文件Local files

框架不内置通用文件工具。文件能力来自 KnowledgeStore 与沙箱 shell 工具。

后者的边界写得比多数同类清楚，这是本对象最值得记的一处。

① 磁盘知识库。

官方 harness 示例用 DiskKnowledgeStore(Path("./knowledge_demo"))，官方注释：

"Disk-backed, so anything the agent remembers survives the process exiting"

即知识落盘位置由你指定的目录决定。

② 受限 shell（已核到，见官方 release v1.1.1）。

受限模式 "runs commands without a shell"。

SandboxShellTool / ShellAdapter 传 allowed=[...] 或 readonly=True 时， 会把命令切分成 argv。然后只检查 argv 再原样执行：

官方原文："Nothing can expand after the check"

管道 / 重定向 / 通配符 / 变量在受限模式下被拒。

• readonly=True 只放行不可写文件、不启动其它程序的命令
• blocked=[...] 官方明说：

"remains best-effort. It is not a security boundary."

未知 —— 框架级的默认文件访问边界与容器级隔离，官方未说明 （已查 network/overview、agent_harness 与 release 页）。

关机后的任务Tasks after shutdown

「关机后还能跑」在本站是纯库形态 —— 没有托管后台。

但 durable messaging 机制官方给了明确实现。network/overview 页列出的 Network 能力包含：

"Durable messaging with replayable channel transcripts (write-ahead log)"

"Distributed / cross-process deployment: replace LocalLink with WsLink"

hub 持有权威状态：registry、audit log、channel table、write-ahead logs。客户端是：

"thin frontends"

官方另有 Distributed Deployment 专页。

它涵盖 WsLink、serve_ws、auth、at-least-once delivery、reconnect 与 task durability。

长期记忆可跨进程存活。 DiskKnowledgeStore 落盘，见 local_files 轴。

但没有任何厂商托管 offer。

进程必须跑在你自己的服务器上；要真后台得自己上容器 / K8s。

未知 —— 托管选项与断点续跑在崩溃场景下的具体语义，官方未说明 （已查 network/overview 页）。

工具与扩展Tools & extensions

工具、MCP、AG-UI 三项都能在官方源核到；A2A 仅见仓库 topics。

① 原生工具。

普通 Python 函数加 @tool 装饰器即成为工具。官方原文：

"AG2 runs the full tool-calling loop: the model decides when to call it, AG2 executes it, and the result is fed back"

agent 还可 Agent.as_tool() 被别的 agent 当工具用。

② MCP。

官方 release 记录持续维护 MCPToolkit 与 MCPServerTool：

• v1.1.1 "send exactly one Authorization header on every provider"
• v1.1.2 "fix(mcp): derive model output schemas from serialization"

③ AG-UI。

• v1.1.2 "feat(ag-ui)!: serve AG-UI 1.0"
• v1.1.1 支持 "Human input over AG-UI"（工具内 context.input() 的问题经 AG-UI 客户端以 interrupt 抛出）

④ Skills。

官方 release 有 skill 相关修复：

• "check local skill ownership before validating arguments"
• "execute nested scripts from declared paths"

A2A 目前只能在官方仓库 topics 里看到（含 a2a）。

本轮未取到 v1.0 的 A2A 专页正文，故不展开。

子任务委派另有 run_subtask / run_subtasks 自动注入工具（见 context 轴）。

上下文与记忆Context & memory

这是 AG2 最贴合本站「状态 ≠ 上下文」主张的设计。

它把 harness 显式拆成三组 opt-in 原语。

官方 agent_harness 页原文：

"A bare Agent is just a model loop. The harness is the set of opt-in primitives you compose onto it"

三个关键参数：

• assembly=（上下文策略） —— 官方示例含 WorkingMemoryPolicy（把 memory/working.md 注入 system prompt）、SlidingWindowPolicy(max_events=50)（限制历史占用）、AlertPolicy

• knowledge= —— KnowledgeConfig(store=..., compact=..., compact_trigger=..., aggregate=...)， 配 SummarizeCompact / TailWindowCompact 做上下文压缩（README 示例 "18 -> 3 events"）； write_event_log 会把流历史落到 /log/{stream_id}.jsonl

• tasks=（默认关闭） —— 开启后自动注入子任务工具；子 Agent 默认继承父工具， 且子任务自身 tasks=False，官方原文：

官方原文："recursive delegation is structurally impossible"

分野很清楚：compact= 管窗口压缩。

KnowledgeStore 管跨进程持久记忆 —— 两者官方分开描述。

权限与限制Permissions & limits

官方机制分两层：HITL 人审 + 受限 shell 工具。两层都不等于容器沙箱。

① HITL。

README 原文如下：

• 在工具里调 context.input(...) 暂停本次 run 向人提问
• 由 hitl_hook 决定答案来源（CLI / web UI / 队列）

② 工具审批。

release v1.1.1 明说：

"Approval grants are keyed by tool implementation"

且同名工具每轮只暴露一个。

MCP 发现的工具排在代码声明的工具之下，不能覆盖本地工具。

③ 受限 shell。

SandboxShellTool 的 allowed / readonly / blocked 见 local_files 轴。 官方自己声明 blocked=[...] 不是安全边界。

v1.1.2 还修了一个 shell 命令过滤绕过漏洞（GHSA-42mf-vpmr-gw5r）。

④ 数据接口安全提示。

官方文档警告 Redis 的 Serializer.PICKLE 会把代码执行能力交给任何能写该 stream 的人。 建议只用完全可信的 Redis，JSON 为默认。

未知 —— 框架级的进程 / 容器沙箱默认值，官方未说明 （已查 agent_harness 与 release 页）。

适合什么任务Best for

适合。

• 要用 Python 编排多 agent 会话 / 协议化网络（Hub + channel，含咨询、讨论、工作流适配器）
• 需要可审计的 durable messaging（write-ahead log、audit trail）与跨进程部署（WsLink）
• 要在本地模型上跑（Ollama / vLLM / LM Studio）
• 要 HITL 与受限 shell 工具
• 需要 MCP 与 AG-UI 对接
• 偏好 opt-in、可组合的 harness 原语

不适合。

• 期待 pip install ag2 仍是老 AutoGen API（v1.0 起经典类已移入 ag2-classic）
• 需要厂商托管后台（纯库，进程自负）
• 需要开箱即用的容器级沙箱隔离（官方给的是受限 shell 白名单，非容器）
• 非 Python 技术栈（无官方非 Python 端口）

本页由This page is generated from the ai-agent-guide 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内 METHODOLOGY.md。