Claude 三种 Agent 架构全解析:SDK vs Teams vs Managed 如何选择
引言
Anthropic 最近连续发布了三个与 Agent 相关的重磅产品:Agent SDK、Agent Teams 和 Managed Agents。这一系列动作标志着 Claude 正式从”对话模型”进化为”Agent 平台”。
对于开发者而言,这三个产品代表了三种截然不同的 Agent 构建范式。选择错误的架构可能导致数周的开发工作付诸东流。本文基于实际项目经验,深入剖析三种架构的技术细节、优缺点和适用场景,帮助你在项目中做出正确的选择。
一、三种架构概览
| 特性 | Agent SDK | Agent Teams | Managed Agents |
|---|---|---|---|
| 控制粒度 | 最高 | 中等 | 最低 |
| 开发工作量 | 最大 | 中等 | 最小 |
| 状态管理 | 自己实现 | 共享 Task List | 平台托管 |
| 错误处理 | 自己实现 | 部分自动 | 平台自动 |
| 适合场景 | 核心业务 | 长任务协作 | 简单任务 |
二、Agent SDK:完全控制的代价
2.1 架构原理
Agent SDK 是最早发布的方案,它提供了一套底层 API,让你自己编写完整的 agent loop。你需要处理:
- Token 计数和截断
- 工具调用和结果解析
- 错误重试和回退
- 无限循环检测
- 中间状态持久化
2.2 代码示例
from anthropic import Agent
class MyAgent:
def __init__(self):
self.agent = Agent(
model="claude-sonnet-4-20260514",
tools=[search_tool, code_tool],
max_iterations=50
)
self.state = {}
async def run(self, goal: str) -> str:
# 70% 的代码是防御性编程
try:
# Token 超限检测
if self.token_count > 180000:
await self.truncate_context()
# 调用 Agent
result = await self.agent.run(goal)
# 无限循环检测
if self.iteration_count > self.max_iterations:
raise AgentLoopError("Too many iterations")
# 持久化中间结果
await self.save_state()
return result
except ToolError as e:
# 工具失败重试
return await self.retry_with_backoff(e)
except TokenLimitError:
# Token 超限处理
return await self.compress_and_continue()
2.3 实际踩坑经验
坑 1:Token 超限
- Claude 的 context window 虽然大,但复杂任务很容易超限
- 必须实现智能截断策略:优先保留最近的消息和关键工具结果
- 建议设置软限制(180k)而非硬限制(200k)
坑 2:工具调用失败
- 网络波动、API 限流、工具超时都会导致失败
- 必须实现指数退避重试
- 对于幂等操作可以重试,非幂等操作需要补偿机制
坑 3:无限循环
- Agent 可能陷入”调用工具→失败→再调用”的死循环
- 需要检测重复的工具调用模式
- 设置最大迭代次数并强制终止
2.4 优缺点
优点:
- 完全控制 Agent 行为
- 可以针对业务场景深度优化
- 不受平台配额限制
缺点:
- 业务逻辑只占 30%,70% 是 harness 代码
- 开发周期长,维护成本高
- 需要深厚的工程经验
三、Agent Teams:共享状态的协作范式
3.1 架构原理
Agent Teams 的核心创新是共享 Task List。与传统子 Agent 的”fire-and-forget”模式不同:
- 所有 Agent 共享同一个任务列表
- Agent A 发现的问题可以直接添加到 Task List
- Agent B 实时看到并可以接手处理
- 任务状态对所有 Agent 可见
3.2 代码示例
from anthropic import AgentTeam
# 创建共享任务列表
team = AgentTeam(
model="claude-sonnet-4-20260514",
agents=[
Agent(name="researcher", tools=[search_tool]),
Agent(name="coder", tools=[code_tool]),
Agent(name="reviewer", tools=[review_tool])
],
shared_state=True # 关键:启用共享状态
)
# 所有 Agent 可以看到彼此的任务
await team.run("""
完成以下项目:
1. 调研最新的 Agent 框架
2. 实现核心功能
3. 代码审查和优化
""")
# Agent A (researcher) 可以在任务列表中添加新任务:
# "发现依赖库 X 有安全问题,需要升级到 Y 版本"
# Agent B (coder) 会立即看到并处理
3.3 与传统子 Agent 的对比
传统子 Agent 模式:
主 Agent → 子 Agent A (独立执行,返回结果)
→ 子 Agent B (独立执行,返回结果)
问题:子 Agent 之间无法通信,A 发现的问题 B 不知道
Agent Teams 模式:
共享 Task List:
- [✓] 调研框架 (Agent A 完成)
- [→] 实现功能 (Agent B 进行中)
- [!] 发现安全问题 (Agent A 添加,等待处理)
- [ ] 代码审查 (Agent C 待处理)
优势:所有 Agent 实时看到完整上下文
3.4 实际踩坑经验
坑 1:任务冲突
- 多个 Agent 可能同时处理同一个任务
- 需要实现任务锁或状态标记
- 建议设置”认领”机制
坑 2:状态同步延迟
- 共享状态不是完全实时的
- 关键决策前需要显式同步
- 避免依赖毫秒级一致性
3.5 优缺点
优点:
- 适合长任务、多阶段项目
- Agent 之间可以自然协作
- 人类可以随时介入查看进度
缺点:
- 共享状态增加复杂度
- 不适合完全独立的并行任务
- 调试难度较高
四、Managed Agents:企业级稳定 Agent 的加速器
4.1 架构原理
Managed Agents 不是为”简单任务”设计的玩具,而是为企业降低 Agent 开发成本、提升稳定性而生的生产级方案。
核心理念:让企业专注于业务逻辑,而非基础设施。
你需要做的:
- 定义业务 goal
- 提供领域 tools(API、数据库、内部系统)
- 平台处理所有工程复杂性
harness、memory、子 Agent 编排、错误恢复、状态持久化全部由平台托管。
4.2 代码示例
from anthropic import ManagedAgent
# 企业级 Agent:客户服务自动化
customer_agent = ManagedAgent(
model="claude-sonnet-4-20260514",
goal="""处理客户咨询,包括:
1. 查询订单状态
2. 处理退换货申请
3. 解答常见问题
4. 升级复杂问题到人工客服""",
tools=[
order_lookup_tool, # 内部订单系统 API
refund_tool, # 退款系统 API
knowledge_base_tool, # 企业知识库
ticket_escalation_tool # 工单系统
],
memory_config={
"type": "persistent", # 持久化记忆
"retention_days": 90 # 客户对话保留 90 天
},
compliance_config={
"data_residency": "EU", # 数据驻留要求
"audit_logging": True # 审计日志
}
)
# 生产环境部署
await customer_agent.deploy(
environment="production",
scaling_policy="auto", # 自动扩缩容
sla_target=99.9 # SLA 目标
)
4.3 企业级优势
1. 稳定性保障
- 平台级错误恢复:自动重试、fallback、熔断
- 状态持久化:Agent 崩溃后可从中断点恢复
- 版本管理:Agent 配置可版本化、回滚
- 监控告警:内置性能监控和异常告警
2. 开发成本大幅降低
- 无需编写 harness 防御代码(节省 70% 开发量)
- 无需处理 token 管理、错误重试、无限循环检测
- 无需搭建监控、日志、追踪系统
- 小团队也能构建生产级 Agent
3. 企业合规支持
- 数据驻留控制(GDPR 合规)
- 审计日志(金融、医疗行业要求)
- 访问控制和权限管理
- PII 数据自动脱敏
4. 可扩展性
- 自动扩缩容应对流量峰值
- 多区域部署降低延迟
- 与企业现有系统无缝集成
4.4 实际踩坑经验
坑 1:初期配置复杂度高
- 企业级功能需要详细配置(合规、审计、权限)
- 建议:从最小可行配置开始,逐步迭代
坑 2:自定义逻辑受限
- 核心循环逻辑由平台管理
- 非常规需求可能需要切换到 SDK
- 建议:80% 标准化流程用 Managed,20% 特殊场景用 SDK
坑 3:供应商锁定风险
- 深度依赖平台特性后迁移成本高
- 建议:关键业务逻辑保持模型无关,tools 层抽象化
4.5 优缺点
优点:
- 开发成本降低 70%+(无需 harness 代码)
- 生产级稳定性(平台级错误恢复、监控)
- 企业合规开箱即用
- 小团队也能构建复杂 Agent
缺点:
- 核心逻辑控制力较弱
- 深度定制需求受限
- 存在供应商锁定风险
4.6 适用场景
强烈推荐:
- 企业客户服务 Agent
- 内部知识库问答系统
- 标准化业务流程自动化
- 需要合规审计的场景(金融、医疗)
不推荐:
- 需要完全控制 Agent 行为的场景
- 非常规、实验性 Agent 设计
- 预算极其有限的小项目
五、选型建议:实战中的混搭策略
基于实际项目经验,推荐的架构选择策略:
5.1 核心业务 → Agent SDK
场景: 支付处理、用户数据操作、关键业务流程
理由:
- 需要完全控制错误处理
- 业务逻辑复杂,需要深度优化
- 不能接受平台配额限制
# 核心支付流程必须用 SDK
class PaymentAgent:
def __init__(self):
# 自定义重试、补偿、审计日志
self.retry_policy = ExponentialBackoff(max_retries=5)
self.audit_log = AuditLogger()
async def process_payment(self, order):
# 100% 控制力
pass
5.2 跨平台分发 → 传统子 Agent 并行
场景: 同时发布到微信公众号、Twitter、博客
理由:
- 各平台完全独立
- 不需要共享状态
- 并行执行效率最高
# 完全独立的任务,用传统子 Agent
tasks = [
publish_to_wechat(article),
publish_to_twitter(article),
publish_to_blog(article)
]
await asyncio.gather(*tasks)
5.3 长任务复盘 → Agent Teams
场景: 项目开发、代码重构、内容创作
理由:
- 任务周期长,需要多阶段协作
- 可能需要人类中途介入
- 共享状态便于追踪进度
# 长周期项目用 Teams
project_team = AgentTeam(
agents=[planner, executor, reviewer],
shared_state=True
)
await project_team.run("重构用户认证模块")
5.4 内部杂事 → Managed Agents
场景: 数据清洗、日志分析、简单报告
理由:
- 任务简单标准化
- 开发效率优先
- 可以接受平台限制
# 简单任务用 Managed
await ManagedAgent(
goal="整理昨天的错误日志",
tools=[log_tool]
).run()
六、接入自定义模型能力
虽然 Anthropic 的三种架构默认使用 Claude 模型,但在实际生产中,你可能需要:
- 降低成本:用廉价模型处理简单任务
- 特定能力:某个模型在特定领域表现更好
- 数据合规:使用本地部署模型
- 避免供应商锁定:保持架构的模型无关性
6.1 SDK 架构:完全灵活的模型接入
SDK 的最大优势是可以无缝切换任意模型提供商。
方案 A:通过 OpenRouter 统一接入
OpenRouter 提供统一的 API 格式,支持 100+ 模型:
from openai import OpenAI
# OpenRouter 兼容 OpenAI SDK
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key="YOUR_OPENROUTER_KEY"
)
class MultiModelAgent:
def __init__(self):
self.client = client
self.model_router = {
"complex": "anthropic/claude-sonnet-4",
"simple": "google/gemini-3-flash-preview",
"code": "deepseek/deepseek-coder-v2",
"local": "local/llama-3-70b" # 本地模型
}
async def run(self, goal: str, complexity: str = "medium"):
model = self.model_router.get(complexity, "complex")
response = self.client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": goal}],
tools=self.tools,
tool_choice="auto"
)
return self.parse_agent_response(response)
优点:
- 一个 API 接入所有模型
- 按实际使用付费,无需预充值
- 自动 fallback 机制
成本对比(每 1M tokens):
| 模型 | 输入 | 输出 | 适用场景 |
|---|---|---|---|
| Claude Sonnet 4 | $3 | $15 | 核心业务 |
| Gemini 3 Flash | $0.075 | $0.3 | 简单任务 |
| DeepSeek Coder | $0.14 | $0.28 | 代码生成 |
| Llama 3 70B (本地) | $0 | $0 | 数据敏感 |
方案 B:本地模型部署(Ollama/vLLM)
from openai import OpenAI
# 本地 Ollama 服务
local_client = OpenAI(
base_url="http://localhost:11434/v1",
api_key="ollama"
)
class HybridAgent:
def __init__(self):
# 云端 Claude 处理复杂任务
self.cloud_client = Anthropic(api_key="...")
# 本地模型处理敏感数据
self.local_client = local_client
async def process_sensitive_data(self, data: str):
# 敏感数据不出本地
response = self.local_client.chat.completions.create(
model="llama3:70b",
messages=[{"role": "user", "content": data}]
)
return response.choices[0].message.content
async def complex_reasoning(self, goal: str):
# 复杂推理用 Claude
return await self.cloud_client.messages.create(
model="claude-sonnet-4-20260514",
max_tokens=4096,
messages=[{"role": "user", "content": goal}]
)
方案 C:模型路由策略
class SmartRouter:
def __init__(self):
self.models = {
"claude": AnthropicClient(),
"gemini": GeminiClient(),
"local": OllamaClient()
}
def select_model(self, task: dict) -> str:
# 根据任务特征选择模型
if task.get("sensitive"):
return "local"
elif task.get("complexity", 0.5) > 0.8:
return "claude"
elif task.get("type") == "code":
return "claude" # 或 deepseek
else:
return "gemini" # 便宜够用
async def run(self, task: dict):
model = self.select_model(task)
return await self.models[model].run(task)
6.2 Agent Teams:有限的模型自定义
Agent Teams 目前仅支持 Claude 模型,但可以通过以下方式变通:
# 变通方案:外部模型作为"工具"
from anthropic import AgentTeam
import requests
def call_local_model(query: str) -> str:
"""作为工具调用的本地模型"""
response = requests.post(
"http://localhost:11434/api/generate",
json={"model": "llama3", "prompt": query}
)
return response.json()["response"]
team = AgentTeam(
model="claude-sonnet-4-20260514",
agents=[
Agent(name="researcher", tools=[search_tool]),
# 本地模型作为工具被 Claude 调用
Agent(name="local_processor", tools=[call_local_model])
]
)
限制:
- 主模型必须是 Claude
- 其他模型只能作为工具被调用
- 无法让某个 Agent 完全使用非 Claude 模型
6.3 Managed Agents:不支持自定义模型
Managed Agents 完全绑定 Claude 模型,无法切换。
应对策略:
- 简单任务用 Managed + Claude(省心)
- 需要自定义模型的任务降级为 SDK 架构
- 在 SDK 层实现模型路由,Managed 层只处理标准化流程
6.4 实战建议:混合模型架构
class ProductionAgentSystem:
"""生产环境的混合模型架构"""
def __init__(self):
# 1. SDK 层:核心业务,支持任意模型
self.core_agent = SmartRouter()
# 2. Teams 层:协作任务,用 Claude
self.project_team = AgentTeam(
model="claude-sonnet-4-20260514",
agents=[...]
)
# 3. Managed 层:简单任务,用 Claude
self.simple_tasks = [
ManagedAgent(goal="日志分析", ...),
ManagedAgent(goal="数据清洗", ...)
]
async def dispatch(self, task: dict):
if task.get("requires_custom_model"):
return await self.core_agent.run(task)
elif task.get("long_running"):
return await self.project_team.run(task)
else:
return await self.simple_tasks[0].run()
成本优化效果(月处理 100 万 tokens):
| 策略 | 纯 Claude | 混合模型 |
|---|---|---|
| 月成本 | ~$10 | ~$3 |
| 性能 | 100% | 95%+ |
| 灵活性 | 低 | 高 |
七、架构对比总结
| 维度 | SDK | Teams | Managed |
|---|---|---|---|
| 开发时间 | 2-4 周 | 1-2 周 | 1-2 天 |
| 控制力 | ★★★★★ | ★★★☆☆ | ★☆☆☆☆ |
| 维护成本 | 高 | 中 | 低 |
| 适合团队 | 资深工程师 | 中级工程师 | 任何开发者 |
| 配额限制 | 无 | 中等 | 严格 |
结语
Anthropic 发布的三个 Agent 产品,不是让你三选一,而是提供了一套完整的工具箱:
- SDK 是手术刀——精确、强大,但需要高超技艺
- Teams 是协作平台——适合团队作战的长周期项目
- Managed 是自动化工具——简单任务的首选
明智的开发者会根据场景混搭使用:核心业务用 SDK 保证控制力,跨平台任务用并行子 Agent 提升效率,长周期项目用 Teams 便于协作,日常杂事用 Managed 节省精力。
记住:架构没有银弹,只有取舍。选择最适合你当前场景的方案,而不是最酷的方案。
本文基于实际项目经验总结,欢迎交流讨论。