Claude Code Managed Agents 技术总结Claude Code Managed Agents 技术

概述

Claude Code Managed Agents 是 Anthropic 推出的 Agent Skills Beta 功能的统称，提供了一套完整的智能体打包、存储、版本管理和执行的基础设施。开发者可以将智能体行为封装为可复用的 Skill，上传至 Anthropic 服务端，并在隔离的容器环境中执行。

"Managed"的核心含义：Skills 及其执行环境（Container）由 Anthropic 基础设施托管，开发者无需自建 Agent 运行层。

核心架构

Claude Code Managed Agents
         │
         ▼
   Agent Skills System
         │
   ┌─────┴──────────────────────────────┐
   │                                    │
Skills API                     Container Runtime
(client.beta.skills)           (代码执行沙箱)
   │                                    │
   ├── create()                         ├── 加载 Skills 到容器
   ├── retrieve()                       ├── 跨请求保持状态
   ├── list()                           ├── 提供 bash/text-editor 工具
   ├── delete()                         └── 支持文件上传/输出
   └── versions.*
         │
    SKILL.md 包格式
    (名称、描述、Agent 指令)

关键概念

Skill（技能）

Skill 是 Managed Agents 的基本单元，由一组文件打包而成，必须包含 SKILL.md 作为入口描述文件。每个 Skill 有独立 ID、版本历史和来源标识。

来源类型：

类型	说明
`anthropic`	Anthropic 官方内置 Skill
`custom`	用户自定义 Skill

Container（容器）

Container 是 Skill 的运行时隔离环境。支持跨多轮请求复用同一容器以保持状态。每个容器有唯一 ID 和过期时间。

SKILL.md

Skill 的包描述文件，其中定义的 name 和 description 会被提取到版本记录中。所有文件必须位于同一顶层目录下。

API 使用

前置条件

SDK 版本：@anthropic-ai/sdk >= 0.67.0（2025 年 10 月）
Beta 标识：skills-2025-10-02

Skill CRUD 操作

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

// 创建 Skill
const skill = await client.beta.skills.create({
  display_title: "My Agent Skill",
  files: [/* 包含 SKILL.md 的文件列表 */],
  betas: ['skills-2025-10-02']
});

// 查询 Skill
const retrieved = await client.beta.skills.retrieve('skill_id');

// 列出所有自定义 Skill（支持游标分页）
for await (const s of client.beta.skills.list({ source: 'custom' })) {
  console.log(s.id, s.display_title);
}

// 删除 Skill
await client.beta.skills.delete('skill_id');

版本管理

// 创建新版本
await client.beta.skills.versions.create('skill_id', {
  files: [/* 更新后的文件 */]
});

// 获取特定版本
await client.beta.skills.versions.retrieve('version_id', {
  skill_id: 'skill_id'
});

// 列出所有版本
const versions = await client.beta.skills.versions.list('skill_id');

// 删除版本
await client.beta.skills.versions.delete('version_id', {
  skill_id: 'skill_id'
});

在消息请求中使用 Skill

const response = await client.beta.messages.create({
  model: 'claude-sonnet-4-6',
  messages: [{ role: 'user', content: '执行任务...' }],
  container: {
    // 可选：传入已有 container ID 实现状态复用
    id: 'existing-container-id',
    skills: [
      {
        skill_id: 'my-skill-id',
        type: 'custom',
        version: 'latest'  // 或指定具体版本号
      }
    ]
  },
  betas: ['skills-2025-10-02']
});

// 响应中包含容器信息
console.log(response.container);
// { id: "ctr_xxx", expires_at: "2026-...", skills: [...] }

数据模型

Skill 响应结构

interface SkillCreateResponse {
  id: string;                          // 唯一标识
  created_at: string;                  // ISO 8601 创建时间
  display_title: string | null;        // 显示名称
  latest_version: string | null;       // 最新版本号
  source: 'custom' | 'anthropic';     // 来源
  type: 'skill';                       // 固定类型
  updated_at: string;                  // 更新时间
}

Version 响应结构

interface VersionCreateResponse {
  id: string;           // 版本 ID
  skill_id: string;     // 所属 Skill
  version: string;      // Unix 时间戳版本号，如 "1759178010641129"
  name: string;         // 从 SKILL.md 提取
  description: string;  // 从 SKILL.md 提取
  directory: string;    // 顶层目录名
  type: 'skill_version';
}

Container 响应结构

interface BetaContainer {
  id: string;                           // 容器实例 ID
  expires_at: string;                   // 过期时间
  skills: Array<BetaSkill> | null;     // 已加载的 Skills
}

interface BetaSkill {
  skill_id: string;
  type: 'anthropic' | 'custom';
  version: string;
}

功能	Beta Header	说明
Skills	`skills-2025-10-02`	可复用的打包 Agent 能力
Code Execution	`code-execution-2025-05-22`	服务端代码沙箱
Memory Tool	`memory-2025-08-18`	持久化 Agent 记忆
MCP Client	`mcp-client-2025-04-04`	Model Context Protocol 集成
Context Management	`context-management-2025-06-27`	多轮上下文控制
Computer Use	`computer-use-2025-01-24`	GUI 自动化
Web Search	`web-search-tool`	实时网页搜索

典型应用场景

企业级 Agent 平台 — 将通用 Agent 能力（如代码审查、文档生成）封装为 Skill，团队共享复用
多步骤工作流 — 利用 Container 状态持久化，实现跨轮次的复杂任务编排
版本化迭代 — Skill 版本管理确保生产环境稳定性，同时支持灰度发布新版本
隔离执行 — 每个 Skill 在独立容器中运行，保证安全性和资源隔离

与 Claude Code CLI 的关系

在 Claude Code CLI（Anthropic 的命令行开发工具）中，Managed Agents 体现为：

Agent 子进程：通过 Agent tool 启动专用子 Agent 执行特定任务
Skill 系统：CLI 内置的 /skill-name 调用机制与 Managed Agents API 同源
并行编排：支持同时启动多个独立 Agent 并行处理不同子任务

Claude Code v2.1.97+ 的 /claude-api 技能已覆盖 Managed Agents 的开发指导。

总结

Claude Code Managed Agents 代表了 Anthropic 在 Agent 基础设施层面的重要布局：

打包标准化 — SKILL.md 定义了统一的 Agent 能力描述规范
生命周期托管 — 从创建、版本管理到执行环境，全部由平台管理
状态持久化 — Container 复用机制让多轮有状态交互成为可能
安全隔离 — 沙箱执行确保 Agent 行为可控

该功能目前处于 Beta 阶段，需要通过 betas 参数显式开启。随着 Agent 生态的发展，预计 Skills 的共享市场和更丰富的运行时能力将持续扩展。

Claude Code Managed Agents 技术总结

概述