# Claude Managed Agents 小白指引

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

- 原文链接: https://laojin.blog/blog/20260410_claude_managed_agents
- 作者: 老金
- 发布日期: 2026-04-10
- 标签: Claude, Managed Agents, AI Agent, Anthropic, 自动化

---

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

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

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

**类比理解**：

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

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

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

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

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

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

```
你（开发者）
  │
  ├─ 定义 Agent（干什么活、有什么工具）
  │
  ├─ 配置 Environment（工作电脑装什么软件）
  │
  └─ 创建 Session（开始干活！）
       │
       └─ 通过 Events 实时交流
```

| 概念 | 是什么 | 类比 | 创建频率 |
|------|--------|------|----------|
| **Agent** | 模型 + 提示词 + 工具的组合配置 | 岗位说明书 | 一次定义，反复使用 |
| **Environment** | 云端容器模板（预装软件、网络策略） | 工作电脑的系统镜像 | 一次配置，多个 Session 共享 |
| **Session** | Agent 在 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 工具：

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

# 验证安装
ant --version
```

然后创建 Agent 和 Environment：

```bash
# 创建 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 代码集成

```bash
pip install anthropic
export ANTHROPIC_API_KEY="your-key"
```

```python
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` | 上网 | 爬数据、查文档 |

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

```json
{
  "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 可以直接连第三方服务，不用你自己写集成代码：

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

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

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

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

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

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

```json
{
  "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 等常用工具

还能声明需要预装的包：

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

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

## 进阶玩法：技能和记忆

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

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

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

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

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

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

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

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

## 实战：文件和 GitHub 集成

### 上传文件

```bash
# 上传文件
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 仓库

```json
{
  "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 了？** 评论区聊聊，我特别好奇大家的想法。