← Frameworks

模型与开放条件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 兼容页）。

The provider list is explicit, type-safe config classes, covering both cloud and local paths.

Official beta/model_configuration page wording:

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

One Config class + one extra per provider:

• 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])

Local / self-hosted support is explicit.

The official docs have a dedicated section "Self-Hosted and OpenAI-Compatible Models (vLLM, LM Studio, etc.)", via OpenAIConfig's base_url. The README also lists ag2[ollama].

Bedrock switched to the native async client aiobotocore in v1.1.1. The official release marks it breaking.

Unknown — how tool calling / structured output reliability compares across providers, not stated officially (beta/model_configuration and the Grok compatibility page checked).

运行位置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。

A pure Python library, async throughout, no hosted service.

README wording:

"AG2 requires Python version >= 3.10"

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

Install is pip install ag2[openai].

The official docs give two scheduling links for multi-agent form (network/overview page):

• default LocalLink — official description:

"same-process duplex queues"

i.e. hub + agents inside one process.

• switch to WsLink — official description:

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

i.e. the hub and each agent live in separate OS processes.

When switching links the HubClient API is unchanged; no business-code changes needed.

It does not operate an agent loop.

Everything in the library runs on your own process / host; the official docs offer no hosted offering.

本地文件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 页）。

The framework ships no general-purpose file tools. File capability comes from KnowledgeStore and the sandboxed shell tool.

The latter's boundaries are written more clearly than most peers — the single most notable thing about this object.

① Disk knowledge store.

The official harness example uses DiskKnowledgeStore(Path("./knowledge_demo")), official comment:

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

i.e. where knowledge lands on disk is decided by the directory you specify.

② Restricted shell (verified, see official release v1.1.1).

Restricted mode "runs commands without a shell".

When SandboxShellTool / ShellAdapter gets allowed=[...] or readonly=True, it splits the command into argv. Then it checks only the argv and executes it verbatim:

Official wording: "Nothing can expand after the check"

Pipes / redirection / wildcards / variables are rejected in restricted mode.

• readonly=True allows only non-writing commands that launch no other programs
• blocked=[...] officially stated plainly:

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

Unknown — framework-level default file-access boundaries and container-level isolation, not stated officially (network/overview, agent_harness and the release page checked).

关机后的任务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 页）。

"Still running after shutdown" is pure-library form on this site — there is no hosted background.

But the durable messaging mechanism has an explicit official implementation. The Network capabilities listed on the network/overview page include:

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

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

The hub holds authoritative state: registry, audit log, channel table, write-ahead logs. Clients are:

"thin frontends"

There is also a dedicated Distributed Deployment page.

It covers WsLink, serve_ws, auth, at-least-once delivery, reconnect and task durability.

Long-term memory can survive across processes. DiskKnowledgeStore persists to disk, see the local_files axis.

But there is no vendor-hosted offering at all.

Processes must run on your own servers; a true background needs your own containers / K8s.

Unknown — hosting options and the exact semantics of resume-after-crash, not stated officially (network/overview page checked).

工具与扩展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 轴）。

Tools, MCP and AG-UI are all verifiable from official sources; A2A is only seen in repository topics.

① Native tools.

A plain Python function with the @tool decorator becomes a tool. Official wording:

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

Agents can also be used as tools by other agents via Agent.as_tool().

② MCP.

Official releases record ongoing maintenance of MCPToolkit and 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 supports "Human input over AG-UI" (questions via context.input() inside tools are raised as interrupts to the AG-UI client)

④ Skills.

Official releases contain skill-related fixes:

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

A2A can currently only be seen in the official repository topics (including a2a).

This pass did not capture the body of a v1.0 A2A dedicated page, so it is not expanded.

Subtask delegation has separately auto-injected run_subtask / run_subtasks tools (see the context axis).

上下文与记忆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 管跨进程持久记忆 —— 两者官方分开描述。

This is the AG2 design that best matches this site's "state ≠ context" stance.

It explicitly splits the harness into three groups of opt-in primitives.

Official agent_harness page wording:

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

Three key parameters:

• assembly= (context policy) — official examples include WorkingMemoryPolicy (injects memory/working.md into the system prompt), SlidingWindowPolicy(max_events=50) (caps history usage), AlertPolicy

• knowledge= — KnowledgeConfig(store=..., compact=..., compact_trigger=..., aggregate=...), with SummarizeCompact / TailWindowCompact doing context compaction (README example "18 -> 3 events"); write_event_log dumps stream history to /log/{stream_id}.jsonl

• tasks= (off by default) — when enabled, subtask tools are auto-injected; sub-Agents inherit parent tools by default, and subtasks themselves have tasks=False, official wording:

Official wording: "recursive delegation is structurally impossible"

The boundary is clear: compact= governs window compaction.

KnowledgeStore governs cross-process persistent memory — the official docs describe the two separately.

权限与限制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 页）。

The official mechanisms come in two layers: HITL human review + restricted shell tools. Neither layer equals a container sandbox.

① HITL.

README wording:

• calling context.input(...) inside a tool pauses the run to ask a human
• hitl_hook decides where the answer comes from (CLI / web UI / queue)

② Tool approval.

Release v1.1.1 states plainly:

"Approval grants are keyed by tool implementation"

and only one same-named tool is exposed per turn.

MCP-discovered tools rank below code-declared tools and cannot override local tools.

③ Restricted shell.

SandboxShellTool's allowed / readonly / blocked — see the local_files axis. The official docs themselves declare blocked=[...] not a security boundary.

v1.1.2 also fixed a shell command-filter bypass vulnerability (GHSA-42mf-vpmr-gw5r).

④ Data-interface security note.

Official docs warn that Redis's Serializer.PICKLE hands code-execution capability to anyone who can write that stream.

The advice is to use only fully trusted Redis; JSON is the default.

Unknown — framework-level process / container sandbox defaults, not stated officially (agent_harness and release pages checked).

适合什么任务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 端口）

Fits.

• orchestrating multi-agent conversations / protocolized networks in Python (Hub + channel, with consulting, discussion, workflow adapters)
• needing auditable durable messaging (write-ahead log, audit trail) and cross-process deployment (WsLink)
• running on local models (Ollama / vLLM / LM Studio)
• wanting HITL and restricted shell tools
• needing MCP and AG-UI integration
• preferring opt-in, composable harness primitives

Does not fit.

• expecting pip install ag2 to still be the old AutoGen API (since v1.0 the classic classes moved into ag2-classic)
• needing a vendor-hosted background (pure library, processes are your own)
• needing out-of-the-box container-level sandbox isolation (the official offering is a restricted-shell allowlist, not containers)
• non-Python stacks (no official non-Python port)

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