Claude Managed Agents 调研

pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-xxx"

from anthropic import Anthropic

client = Anthropic()

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-sonnet-4-6",
    system="You are a helpful coding assistant. Write clean, well-documented code.",
    tools=[
        {"type": "agent_toolset_20260401"},  # 全量内置工具
    ],
)
print(f"Agent ID: {agent.id}")`

environment = client.beta.environments.create(
    name="quickstart-env",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)
print(f"Environment ID: {environment.id}")

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Quickstart session",
)
print(f"Session ID: {session.id}")

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text", "text": "搜索最新的 Claude 新闻并总结"}],
        }],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[🔧 Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\n✅ Agent finished.")
                break

[🔧 Using tool: web_search]
Here's a summary of the latest news about Claude and Anthropic:
...（Agent 自主搜索网页、整理信息、输出结果）
✅ Agent finished.

• Outcomes 解决"代理不知道好不好"的问题。你写一个 rubric，独立的 grader 模型在自己的 context 里打分，代理拿到"哪里没达标"再迭代。Anthropic 自己的内部基准里，Outcomes 把任务成功率提升最多 10 个百分点，docx 生成质量 +8.4%，pptx +10.1%。

• Multiagent Orchestration 解决"上下文塞不下、子任务又要并行"的问题。一个 lead agent 可以协调最多 20 种 subagent，最多 25 个并行线程，所有 subagent 共享同一份文件系统，事件持久化、可在 Claude Console 里逐步追踪。

• Webhooks 解决"我不想轮询、不想拿着 connection 等"的问题。代理跑完一个 Outcome 自动 POST 你的 endpoint。这是把"需要人盯着"的玩具，变成"能挂在生产 CI 里"的工具的关键。

• 事实核查（找出文中可疑的数字 / 名字 / 引用，给出可信度评分）

• 风格润色（按品牌 voice 给出修订建议）

• 结构评估（按"标题 + TL;DR + 主体三段 + 参考资料"模板检查）

{
    "name": "article_quality_v1",
    "criteria": [
        {
            "id": "facts",
            "description": "文章中所有数字、人名、引用都能在外部公开来源核实，否则该条须被标红并给出怀疑等级 (low/medium/high)。"
        },
        {
            "id": "voice",
            "description": "全文风格与品牌 voice guide 一致：第二人称、避免 buzzword、段落 ≤ 4 句。违反的句子要列出。"
        },
        {
            "id": "structure",
            "description": "包含 Title / TL;DR / 至少 3 个二级标题 / 参考资料章节，否则不合格。"
        }
    ],
    "pass_when": "facts.high_risk_count == 0 AND voice.violations <= 3 AND structure.missing_sections == 0"
}

{
    "subagents": [
        {
            "name": "fact_checker",
            "model": "claude-opus-4-7",
            "system_prompt": "你是事实核查员。对输入文章中每个数字、人名、引用，给出 cite_url 与可信度 (low/medium/high)。",
            "tools": [
                "web_search",
                "url_fetch"
            ]
        },
        {
            "name": "voice_editor",
            "model": "claude-opus-4-7",
            "system_prompt": "你按附件 voice_guide.md 检查文章，列出所有违反第二人称 / buzzword / 段落过长的句子，给出建议改写。",
            "tools": [
                "read_file"
            ]
        },
        {
            "name": "structure_auditor",
            "model": "claude-haiku-4-5",
            "system_prompt": "你按模板检查 markdown 文档结构，缺失章节就报错。",
            "tools": []
        }
    ]
}

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    default_headers={"anthropic-beta": "managed-agents-2026-04-01"},
)

job = client.managed_agents.sessions.create(
    lead_model="claude-haiku-4-5",
    lead_system_prompt=(
        "你是审稿流水线的主调度。收到草稿后并行调度 "
        "fact_checker / voice_editor / structure_auditor 三个子代理，"
        "汇总结果，触发 Outcome 评估，最终把通过/不通过结果交回给我。"
    ),
    subagents=SUBAGENTS_JSON,           # 第四节那段 JSON
    outcome=OUTCOME_JSON,               # 第三节那段 JSON
    input={
        "draft_markdown_url": "https://drafts.example.com/a83.md",
        "voice_guide_url":   "https://internal.example.com/voice_guide.md",
    },
    webhook={
        "url": "https://hooks.example.com/article-review",
        "events": ["outcome.passed", "outcome.failed"],
        "signing_secret": os.environ["HOOK_SECRET"],
    },
)
print("session id:", job.id)

from flask import Flask, request, abort
import hmac, hashlib, os

app = Flask(__name__)
SECRET = os.environ["HOOK_SECRET"].encode()

def verify(sig: str, body: bytes) -> bool:
    expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

@app.post("/article-review")
def hook():
    sig = request.headers.get("X-Claude-Signature", "")
    if not verify(sig, request.get_data()):
        abort(401)
    payload = request.get_json()
    if payload["event"] == "outcome.passed":
        notify_slack_pass(payload["session_id"])
    else:
        notify_slack_fail(payload["session_id"], payload["grader_feedback"])
    return "", 204

1. 别让 lead 自己干活。 多智能体编排的本意是 lead 当调度。你给 lead 配 Opus、又让它自己写文本，子代理就变摆设，账单会爆。Spiral 那种"Haiku 当 lead、Opus 当 worker"的拆分是当前主流姿势。

2. Outcomes 的 rubric 别写得太抽象。 “通顺易读"这种描述 grader 会给你打满分。要拆成"段落 ≤ 4 句”、"避免 buzzword 清单 X"这种可机判定的小条款。Wisedocs 团队对外说他们的审查代理在引入 Outcomes 后效率提升 50%，关键就是把内部审查指南拆成了 rubric。

3. webhook 重试要做幂等。 Anthropic 文档明确，webhook 失败会重试。如果你直接发 Slack，重复通知会很烦，按 session_id 做去重。

4. 别忘了带 beta header。anthropic-beta: managed-agents-2026-04-01，不带这个头 multiagent / outcomes / webhooks 全部 404。

5. 用 Claude Console 看 trace。 当 subagent 行为不符合预期时，Console 里能逐条看到 lead 把任务怎么拆、subagent 收到什么 prompt、最后输出什么——比日志好用 10 倍。

1. 把 Outcomes 的 rubric 版本化，跟着 voice_guide 一起进 git，每次改 rubric 都生成新 outcome name，便于 A/B；给 lead 接 Memory + Dreaming（Dreaming 目前是研究预览，需要申请），让它把"过去哪些类型的稿件最常败在 voice 项"沉淀成自己的记忆；最后，把 webhook 触发的通知改成 PR：fact_checker 输出可信度 high 的疑点直接以 GitHub PR 注释形式落地，作者在原稿位置就能看见。

2. 另一个值得做的演进是"成本可视化"。Multiagent 一旦并发起来，Opus 子代理的账单会比单代理高一个量级。建议在 webhook 回调里顺手把每个 session 的 token 用量、grader 重试次数、subagent 失败次数写到一张表，方便后面按 outcome 名做成本/质量回归——这件事 Anthropic 暂时没给你做。

3. 最后，把 lead agent 自己也版本化。lead 的 system prompt 决定了它怎么拆任务、怎么决定何时重试、什么时候直接抛回用户。这是这个流水线最容易"看似没改、行为大变"的地方，必须有 prompt diff、有 A/B、有金丝雀流量，否则你某天会发现整条线突然只用了一个 subagent。