Claude Managed Agents 全景：Sessions / Agents / Environments API 三层架构

第二十九章：Managed Agents 概述：Projects、Artifacts 与 Agent 生命周期

29.1 什么是 Managed Agents？

在 Anthropic 的产品体系中，Managed Agents 是指运行在 Claude.ai 平台上、由平台本身负责基础设施管理的 Agent 实例。与通过 API 自行搭建的 Agent（需要开发者管理服务器、数据库、会话状态）不同，Managed Agents 将基础运维完全交给 Claude.ai 平台，开发者和用户只需专注于业务逻辑。

Managed Agents 的核心特征：

1. 平台托管：会话持久化、记忆存储、工具执行环境由 Claude.ai 管理
2. Projects 支持：Agent 可以关联到 Projects，拥有专属知识库和指令集
3. Artifacts 生成：Agent 可以产出可交互的工件（代码、图表、网页）
4. 生命周期管理：暂停、恢复、克隆、版本控制均由平台处理

Managed Agents vs API Agents

29.2 Projects：有记忆的 Agent 工作空间

Projects 是 Claude.ai 中最重要的功能之一，它将单次对话升级为具有持久记忆的专业工作空间。

Projects 的核心组成

┌─────────────────────────────────────────────┐
│                  Project                     │
│                                             │
│  ┌──────────────┐  ┌──────────────────────┐ │
│  │  知识库       │  │  自定义指令            │ │
│  │  (Knowledge  │  │  (Custom Instructions)│ │
│  │   Base)      │  │                      │ │
│  └──────────────┘  └──────────────────────┘ │
│                                             │
│  ┌──────────────────────────────────────┐   │
│  │          对话历史                      │   │
│  │  (Conversation History)               │   │
│  └──────────────────────────────────────┘   │
│                                             │
│  ┌────────────┐  ┌────────────┐             │
│  │  Artifacts │  │  工具集     │             │
│  └────────────┘  └────────────┘             │
└─────────────────────────────────────────────┘

知识库（Knowledge Base）

Projects 的知识库允许上传和索引文档，Claude 在该 Project 的所有对话中都能访问这些文档：

支持的文件类型：

• 文本文件：.txt, .md, .csv
• 文档：.pdf, .docx
• 代码文件：.py, .js, .ts, .go 等
• 数据文件：.json, .yaml

知识库的工作机制：

用户上传文档后，Claude.ai 自动完成：

1. 文档解析（提取文本）
2. 语义分块（Chunking）
3. 嵌入向量生成
4. 向量索引构建

在对话时，Claude 根据用户消息自动检索相关文档片段，注入上下文。这本质上是一个平台托管的 RAG 系统。

最佳实践：

知识库内容建议
├── 核心参考文档（高频检索）
│   ├── API 文档
│   ├── 规范文档
│   └── 技术手册
├── 案例和示例（提供模式参考）
│   ├── 代码示例
│   └── 历史案例
└── 背景材料（提供上下文）
    ├── 团队规范
    └── 项目背景文档

不建议放入
├── 超大文件（>10MB 的单个文件）
├── 高度重复的内容（稀释检索精度）
└── 敏感信息（密码、密钥、PII）

自定义指令（Custom Instructions）

Custom Instructions 是 Project 级别的系统提示扩展，在每次对话开始时自动注入：

# 示例：代码审查 Project 的 Custom Instructions

## 你的角色
你是一位专注于 Python 后端开发的资深代码审查专家，拥有深厚的 FastAPI、PostgreSQL 和微服务架构经验。

## 审查标准
对于提交的代码，你必须检查：
1. **安全性**：SQL 注入、认证绕过、敏感数据暴露
2. **性能**：N+1 查询、同步阻塞 I/O、未释放资源
3. **代码质量**：函数长度（>50行需重构建议）、命名规范（snake_case）
4. **测试覆盖**：关键路径是否有对应的单元测试

## 输出格式
对于每个问题，使用以下格式：

[严重程度] 文件名:行号 问题描述 建议修复方案

严重程度：CRITICAL（必须修复）/ HIGH（强烈建议）/ MEDIUM（建议）/ LOW（可选）

## 上下文
团队使用 Python 3.11+，遵循 PEP 8，使用 pytest 做测试框架。
禁止使用 print() 做日志，必须使用 structlog。

29.3 Artifacts：可交互的输出工件

Artifacts 是 Claude.ai 的核心差异化功能，允许 Claude 生成不只是文字，而是可以直接运行、预览和部署的工件。

Artifact 类型大全

1. 代码（Code）

触发条件：用户请求独立可运行的代码
展示方式：代码编辑器视图，支持语法高亮
文件类型：Python, JavaScript, TypeScript, SQL, Shell 等
特殊能力：部分代码类型可直接在浏览器沙箱中执行

2. SVG 图形（SVG）

触发条件：用户请求矢量图形、图标、流程图
展示方式：实时渲染的矢量图
典型用途：
  - 技术架构图
  - 品牌 Logo 草图
  - 流程示意图
  - 数据可视化图形

SVG Artifact 示例场景：

用户：画一个简单的微服务架构图，包含 API Gateway、3个微服务和数据库
Claude 输出 SVG Artifact：
  <svg>...</svg>  (实时渲染为可视化图形)

3. HTML 网页（HTML）

触发条件：用户请求完整可运行的网页
展示方式：内嵌浏览器预览
能力范围：
  - 完整 HTML/CSS/JavaScript
  - 可访问外部 CDN（Bootstrap、Chart.js 等）
  - 支持动画和交互
  - 支持表单和本地状态管理

4. React 组件（React）

触发条件：用户请求交互式 React 组件
展示方式：实时编译并渲染的 React 组件
依赖限制：可使用 shadcn/ui, lucide-react 等预装库
典型用途：
  - 数据看板（Dashboard）
  - 表单组件
  - 交互式图表
  - 小型工具应用

5. Mermaid 图表（Mermaid）

触发条件：用户请求流程图、时序图、ER图等
展示方式：实时渲染的 Mermaid 图表
支持类型：
  - flowchart（流程图）
  - sequenceDiagram（时序图）
  - erDiagram（ER图）
  - gantt（甘特图）
  - classDiagram（类图）
  - mindmap（思维导图）

6. Markdown 文档（Markdown）

触发条件：生成长篇文档、报告、规范
展示方式：渲染后的富文本视图
与普通回复的区别：Artifact 形式的 Markdown 可以独立保存和导出

Artifact 的生命周期

创建 → 预览 → 修改 → 版本历史 → 导出/部署
  ↑                    │
  └────────────────────┘ (迭代修改)

Claude.ai 对 Artifact 维护版本历史，用户可以在不同版本间切换，或回退到之前的状态。

29.4 Agent 生命周期

会话生命周期

在 Claude.ai 中，每个对话（Conversation）都有完整的生命周期：

初始化
  │
  ├─ 加载 Project 配置（Custom Instructions + Knowledge Base）
  │
  ├─ 会话中（Active）
  │   ├─ 用户消息 → RAG 检索 → 上下文构建 → 模型推理 → 回复
  │   ├─ Artifact 生成和版本管理
  │   └─ 工具调用（代码执行、搜索等）
  │
  ├─ 归档（Archived）
  │   └─ 对话历史保留，可重新激活
  │
  └─ 删除（Deleted）
      └─ 不可恢复

Project 生命周期

# 概念示意（非真实 API，Claude.ai Projects 通过 UI 管理）
class ProjectLifecycle:
    """
    Claude.ai Project 的生命周期状态机（概念模型）
    
    实际操作通过 Claude.ai Web 界面进行
    未来可能通过 API 管理
    """
    
    states = {
        "draft": "配置阶段：设置 Custom Instructions，上传知识库",
        "active": "活跃阶段：团队成员可以在 Project 内创建对话",
        "shared": "共享阶段：通过共享链接开放给协作者",
        "archived": "归档阶段：只读，不能创建新对话",
    }
    
    transitions = {
        "draft → active": "完成配置后发布",
        "active → shared": "开启共享访问",
        "active → archived": "项目结束归档",
        "archived → active": "重新激活",
    }

29.5 内置工具集

Managed Agents 享有 Claude.ai 平台提供的内置工具，无需用户自行实现：

工具一：网络搜索

Claude 可以主动搜索互联网以获取实时信息：

• 触发时机：用户询问实时信息、近期事件、需要验证的数据
• 来源：公开网页、新闻站点
• 注意：不能访问需要登录的内容

工具二：代码执行（Python Sandbox）

Claude 可以在安全的沙箱环境中执行 Python 代码：

沙箱环境特征：
- Python 3.x 运行时
- 预装常见库：numpy, pandas, matplotlib, scikit-learn 等
- 文件系统隔离（不能访问主机文件）
- 网络访问受限
- 执行超时限制

典型用途：

• 数据分析和可视化（生成图表）
• 数学计算和验证
• 代码测试验证
• 数据处理和格式转换

工具三：文件读写（Projects 内）

在支持的功能下，Claude 可以读取用户上传到 Project 的文件内容，并在 Artifacts 中生成可导出的文件。

29.6 Managed Agents 的适用边界

理解 Managed Agents 的能力边界，有助于选择合适的技术方案：

适合 Managed Agents 的场景：

• 团队知识助手（技术文档、公司规范）
• 代码审查和分析
• 报告生成和数据分析
• 原型设计和 MVP 快速验证
• 个人生产力工具

需要 API 自建 Agent 的场景：

• 需要接入私有系统（内部数据库、企业 ERP）
• 需要自定义工具调用（调用内部 API）
• 需要高度定制化的工作流（复杂的 Multi-Agent 编排）
• 需要实时数据流处理
• 对数据合规有严格要求（数据不能离开企业内网）

小结

Managed Agents 是 Claude.ai 平台为非技术用户和快速迭代场景提供的完整解决方案。它通过 Projects（知识库 + 指令集）、Artifacts（可交互工件）和内置工具集，将复杂的 Agent 工程问题抽象成可配置的用户界面。

核心概念：

• Projects = 持久化工作空间，包含知识库、指令和对话历史
• Artifacts = 代码、SVG、HTML、React、Mermaid 等可交互工件
• 内置工具 = 网络搜索、Python 代码执行、文件处理
• 适用边界 = 快速启动、知识库问答、内容生成；复杂定制化需要 API 自建

下一章将深入 Claude Projects 的高级使用：如何组织知识库、设计高效的 Custom Instructions，以及团队协作的最佳实践。