老金的分享
返回博客

Claude Managed Agents 小白指引

2026年4月10日

从 Messages API 到 Managed Agents 的范式转换——一个数据分析师的一周踩坑实录。四个核心概念、三条上手路径、七个血泪教训，手把手带你搞懂 Anthropic 最新的 AI Agent 云端运行方案。

这篇指引主要是为了帮助零基础读者理解 Claude Managed Agents 是什么、解决什么问题、以及如何从零开始创建并运行第一个 Agent。读完后你将掌握核心概念、能跑通一个完整的 Hello World 流程，并知道接下来往哪个方向深入。

先说人话：Managed Agents 到底是啥？

一句话：Managed Agents 是 Anthropic 提供的托管式 AI Agent 运行平台——你定义好 Agent 的能力，平台帮你搞定运行环境、沙箱隔离、故障恢复等一切基础设施。

类比理解：

概念类比
直接调用 Claude API你发微信问朋友一个问题，朋友回答完就结束了
Managed Agents你雇了一个远程员工，给他一台电脑（Environment）、一份岗位说明书（Agent 定义），他可以自己打开文件、运行代码、上网搜索，持续工作几个小时，最后把成果交给你

和直接调用 Messages API 的核心区别：

特性Messages APIManaged Agents
交互模式一问一答持续自主工作
任务时长秒级分钟到小时级
运行环境无云端沙箱容器
工具执行你自己实现平台内置
状态保持无跨交互持久化
适合场景翻译、问答、摘要写代码、数据分析、自动化流水线

判断标准也很简单：如果你的任务只需要 Claude "想一想再回答"，用 Messages API 就够了。如果需要 Claude "动手干活"（写文件、跑命令、调接口），那就是 Managed Agents 的场景。

四个核心概念，我打个比方你就记住了

搞懂下面四个概念，你就理解了 Managed Agents 80% 的架构。

你（开发者）
  │
  ├─ 定义 Agent（干什么活、有什么工具）
  │
  ├─ 配置 Environment（工作电脑装什么软件）
  │
  └─ 创建 Session（开始干活！）
       │
       └─ 通过 Events 实时交流
概念是什么类比创建频率
Agent模型 + 提示词 + 工具的组合配置岗位说明书一次定义，反复使用
Environment云端容器模板（预装软件、网络策略）工作电脑的系统镜像一次配置，多个 Session 共享
SessionAgent 在 Environment 中的一次运行实例一次具体的工作任务每个任务创建一个
Events你和 Agent 之间的双向消息流工作中的即时通讯实时产生

它们的关系：一个 Agent 可以在多个 Session 中运行，每个 Session 绑定一个 Environment，Session 中的所有交互通过 Events 传递。

上手体验：三条路径（我建议你走第一条）

有三条路径可以创建 Agent，推荐新手从 Console 可视化路径开始。

路径一：Console 可视化界面（推荐新手）

  1. 打开 https://platform.claude.com
  2. 在左侧菜单选择"Agents"
  3. 点击"Create Agent"，按引导填写：
    • Model：选择 Claude 模型（推荐 claude-sonnet-4-6，性价比最高）
    • System Prompt：写清楚 Agent 的角色和任务（比如"你是一个 Python 代码助手"）
    • Tools：勾选需要的内置工具
  4. 创建 Environment，开启网络访问
  5. 点击"Run Session"直接测试

Console 会实时显示等效的 API 请求，调试满意后可直接复制 Agent ID 到代码中。

路径二：CLI 命令行——适合不爱点鼠标的

先安装 CLI 工具：

# macOS
brew install anthropics/tap/ant
xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant"

# 验证安装
ant --version

然后创建 Agent 和 Environment：

# 创建 Agent
ant beta:agents create \
  --name "My First Agent" \
  --model claude-sonnet-4-6 \
  --system "你是一个有用的编程助手。"

# 创建 Environment（开启网络）
ant beta:environments create \
  --name "dev-env" \
  --config '{"type": "cloud", "networking": {"type": "unrestricted"}}'

路径三：SDK 代码集成

pip install anthropic
export ANTHROPIC_API_KEY="your-key"

import anthropic

client = anthropic.Anthropic()

# 创建 Session 并发送消息
session = client.beta.sessions.create(
    agent="agent_01XXX",          # 替换为你的 Agent ID
    environment_id="env_01XXX",   # 替换为你的 Environment ID
)

# 发送消息
client.beta.sessions.events.create(
    session_id=session.id,
    events=[{
        "type": "user.message",
        "text": "帮我写一个 Python 脚本，统计当前目录下所有文件的行数"
    }]
)

# 流式接收结果
with client.beta.sessions.stream(session_id=session.id) as stream:
    for event in stream:
        print(event)

推荐组合：用 Console 快速原型验证 → 用 CLI 管理 Agent/Environment → 用 SDK 集成到生产代码。

工具系统：让 Agent 长出"手"

Agent 之所以不是一个只会聊天的花瓶，是因为它有工具。这套内置工具开箱即用：

工具干啥的我实际用到的场景
bash执行命令装依赖、跑脚本、调接口
read / write / edit文件操作读数据、写报告、改代码
glob / grep搜索找文件、搜关键词
web_fetch / web_search上网爬数据、查文档

默认全部开启。但你可以按需关掉——比如不想让它上网：

{
  "tools": [{
    "type": "agent_toolset_20260401",
    "configs": [
      {"name": "web_fetch", "enabled": false},
      {"name": "web_search", "enabled": false}
    ]
  }]
}

还能自定义工具

除了内置工具，你还可以定义自己的工具，让 Agent 调用你公司内部的 API。流程是：

  1. Agent 定义里声明工具
  2. Agent 运行中发出 agent.custom_tool_use 事件（"老板，我需要查一下订单数据"）
  3. 你的后端执行实际操作
  4. 把结果通过 user.custom_tool_result 返回

适合连接企业内部 API、数据库查询等场景。

MCP 协议：直连 GitHub、Slack 这些

通过 MCP（Model Context Protocol），Agent 可以直接连第三方服务，不用你自己写集成代码：

{
  "mcp_servers": [{
    "type": "url",
    "name": "github",
    "url": "https://api.githubcopilot.com/mcp/"
  }]
}

权限控制：别让 AI 打工人乱搞

说到这里你可能有点慌——给 AI 这么多权限，它不会搞出事吗？

放心，Anthropic 想到了。工具执行有两种权限模式：

权限策略行为适用场景
always_allowAgent 自动执行，不用审批读文件、搜索等低风险操作
always_askAgent 暂停，等你审批后再执行写文件、执行命令等高风险操作

我的建议：大部分工具 always_allow，但 bash 一定设成 always_ask。

{
  "tools": [{
    "type": "agent_toolset_20260401",
    "default_config": {"permission_policy": "always_allow"},
    "configs": [
      {"name": "bash", "permission_policy": "always_ask"}
    ]
  }]
}

当 Agent 因为 always_ask 暂停时，你的应用需要监听事件并返回审批结果。

Environment：它的工作电脑长啥样

每个 Agent 的运行环境是一个 Ubuntu 22.04 云端容器：

  • 内存最高 8GB、磁盘最高 10GB
  • 预装了 8 种语言（Python 3.12+、Node.js 20+、Go、Rust、Java、Ruby、PHP、C/C++）
  • 预装 SQLite、git、curl、jq 等常用工具

还能声明需要预装的包：

{
  "type": "cloud",
  "packages": {
    "pip": ["pandas", "matplotlib", "requests"],
    "npm": ["typescript", "express"]
  },
  "networking": {"type": "unrestricted"}
}

网络策略有两种：unrestricted（全放开）和 limited（白名单）。开发随便浪，生产一定要用 limited。

进阶玩法：技能和记忆

技能（Skills）——让 Agent 成为领域专家

技能是可复用的知识包。Anthropic 预置了处理 PPT、Excel、Word 等文档的技能，你也可以自己写：

{
  "skills": [
    {"type": "anthropic", "skill_id": "xlsx"},
    {"type": "custom", "skill_id": "skill_abc123"}
  ]
}

每个 Session 最多挂 20 个技能，Agent 会自动判断什么时候用。

记忆（Memory）——让 Agent 越用越聪明

这是研究预览功能，但已经很能打了。记忆存储让 Agent 跨 Session 保留学习成果：

{
  "resources": [{
    "type": "memory_store",
    "memory_store_id": "mem_store_01XXX",
    "access": "read_write"
  }]
}

比如它记住了"这个用户喜欢用 pandas 不喜欢 polars"，下次就直接用 pandas 写代码。不用你每次都重复交代。

实战：文件和 GitHub 集成

上传文件

# 上传文件
curl https://api.anthropic.com/v1/files -F file=@data.csv

# 创建 Session 时挂载
{
  "resources": [{
    "type": "file",
    "file_id": "file_01XXX",
    "mount_path": "/workspace/data.csv"
  }]
}

每个 Session 最多挂 100 个文件。

挂载 GitHub 仓库

{
  "resources": [{
    "type": "github_repository",
    "url": "https://github.com/your-org/your-repo",
    "auth_token": "github_pat_XXX",
    "ref": "main"
  }]
}

仓库初始化时克隆到容器里，Agent 不会接触你的 token。这个安全设计我给好评。

接下来可以探索什么

功能一句话我的期待值
多 Agent 协作一个协调者指挥多个专业 Agent 并行⭐⭐⭐⭐⭐ 这个出来就是核弹级
成果评估Agent 自我打分并迭代改进⭐⭐⭐⭐ 非常适合内容生产
Vault 认证安全存储第三方凭据⭐⭐⭐ 上生产的刚需
Agent 版本管理版本控制 + 灰度发布⭐⭐⭐ 稳定性保障

最后说两句掏心窝的

我最大的感受是：Managed Agents 不是一个工具升级，而是一个范式转换。

你觉得 AI Agent 会取代你现在工作中的哪一块？还是说你已经在用 Agent 了？ 评论区聊聊，我特别好奇大家的想法。