Claude 三种 Agent 架构全解析:SDK vs Teams vs Managed 如何选择


Claude 三种 Agent 架构全解析:SDK vs Teams vs Managed 如何选择

引言

Anthropic 最近连续发布了三个与 Agent 相关的重磅产品:Agent SDKAgent TeamsManaged 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 开发成本、提升稳定性而生的生产级方案。

核心理念:让企业专注于业务逻辑,而非基础设施

你需要做的:

  1. 定义业务 goal
  2. 提供领域 tools(API、数据库、内部系统)
  3. 平台处理所有工程复杂性

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 节省精力。

记住:架构没有银弹,只有取舍。选择最适合你当前场景的方案,而不是最酷的方案。


本文基于实际项目经验总结,欢迎交流讨论。

如果你喜欢这篇文章,谢谢你的赞赏

图3

如有疑问请联系我