在构建agent应用时，可以借鉴Claude code的分层架构来实现业务自定义扩展，不需要通过搭建agent平台（类coze）方式。

这个分层架构让 Claude Code 既能提供开箱即用的强大功能,又能通过 Plugin 系统进行高度定制化扩展,非常适合构建各种类型的 AI Agent 应用。

1 核心层：Agent SDK

【Anthropic】使用 Claude Agent SDK 构建智能体（翻译）

Claude SDK 的核心作用，确实可以概括为两大块：LLM 基础调用 + Agent 智能体开发。

基础层：封装 Claude LLM API 调用。

这是 SDK 最底层、最通用的功能。它把原生 HTTP 请求、鉴权、参数构造、响应解析全部封装好，让你不用手写网络请求，几行代码就能完成文本生成、多轮对话、流式输出、内容总结、翻译等基础大模型功能。这部分和 Agent 无关，只是单纯、高效地使用 Claude 大模型能力。

进阶层：提供 Agent 开发的全套能力

在基础调用之上，Anthropic 提供了面向 Agent 的扩展模块，封装了自主任务拆解、多工具调用、上下文管理、权限控制、会话持久化等智能体必需逻辑。你可以基于它快速开发能自主思考、调用工具、完成复杂长流程任务的 Agent，而不用从零实现 Agent 框架

Claude Agent SDK(原名 Claude Code SDK)是整个架构的基础,提供:

Agent Loop(代理循环): 自动管理对话流程和工具调用循环
Context Management(上下文管理): 自动压缩和管理上下文,防止超出限制
Built-in Tools(内置工具): Read、Write、Edit、Bash、Grep、Glob 等文件操作和命令执行工具
Permission System(权限系统): 细粒度控制代理的能力范围
Session Management(会话管理): 支持会话恢复和状态持久化

2 扩展层：Plugin 系统

将 Skill/Agent/Command/Hook/MCP 服务打包为可安装单元，通过 plugin.json 清单统一管理，支持市场分发与版本控制。Plugin 是 Claude Code 的主要扩展机制,结构如下:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin 元数据(名称、版本、作者等)
├── commands/                # Slash Commands(可选)
│   └── my-command.md
├── agents/                  # Specialized Agents(可选)
│   └── my-agent/
│       └── AGENT.md
├── skills/                  # Agent Skills(可选)
│   └── my-skill/
│       └── SKILL.md
├── hooks/                   # Event Handlers(可选)
│   └── my-hook.sh
└── .mcp.json               # MCP 服务器配置(可选)

my-plugin/

├── .claude-plugin/

│ └── plugin.json # Plugin 元数据(名称、版本、作者等)

├── commands/ # Slash Commands(可选)

│ └── my-command.md

├── agents/ # Specialized Agents(可选)

│ └── my-agent/

│ └── AGENT.md

├── skills/ # Agent Skills(可选)

│ └── my-skill/

│ └── SKILL.md

├── hooks/ # Event Handlers(可选)

│ └── my-hook.sh

└── .mcp.json # MCP 服务器配置(可选)

3 能力扩展层：Skills、Commands、Agents、Hooks

3.1 Skills(技能)

Skills 通过元工具模式工作——Skills 作为 prompt-based 的上下文修改器，而非可执行代码:

结构:

---
name: skill-name
description: 简短描述,用于 Claude 决策时参考(约 100 tokens)
---

# 详细指令
当 Skill 被激活时,这些指令会被注入到对话上下文中...

---

name: skill-name

description: 简短描述,用于 Claude 决策时参考(约 100 tokens)

---

# 详细指令

当 Skill 被激活时,这些指令会被注入到对话上下文中...

渐进式披露架构: 每个 Skill 在元数据扫描时仅使用约 100 tokens,激活后加载完整内容(小于 5k tokens),捆绑资源仅在需要时加载。

加载位置:

Project Skills: .claude/skills/ (通过 git 共享)
User Skills: ~/.claude/skills/ (个人跨项目使用)
Plugin Skills: 随 Plugin 一起打包分发

3.2 Commands(斜杠命令)

用户可以通过 /command-name 调用的快捷方式:

接受参数: $ARGUMENTS 占位符捕获用户输入
带命名空间: Plugin 中的 command 会自动添加命名空间前缀,如 /plugin-name:command

3.3 Agents(子代理)

专门化的子代理用于处理特定任务:

通过 Task() 工具调用: Task({subagent_type: 'plugin:folder:agent-name', prompt: '...'})
可以有独立的工具权限和上下文隔离
返回结构化结果,包括 usage、cost、duration 等统计信息

3.4 Hooks(钩子)

在特定事件触发时执行的处理器:

Hook 事件类型包括:PostToolUse(工具执行后)、PreToolUse(工具执行前)、PermissionRequest(权限对话)、UserPromptSubmit(用户提交 prompt 后)、SessionStart/End(会话开始/结束)等 Claude Code Plugins

配置示例:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "TodoWrite",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task.sh"
      }]
    }]
  }
}

{

"hooks": {

"PostToolUse": [{

"matcher": "TodoWrite",

"hooks": [{

"type": "command",

"command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task.sh"

}]

}

4 工具集成层：MCP(Model Context Protocol)

MCP 允许连接自定义工具、数据库和 API Claude API Docs。分为两种模式:

进程外 MCP 服务器: 独立进程,通过标准协议通信
进程内 SDK MCP: 直接在 Python/TypeScript 应用中运行,无需独立进程

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("add", "Add two numbers", {"a": float, "b": float})
async def add(args):
    return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}

calculator = create_sdk_mcp_server(
    name="calculator",
    tools=[add]
)

options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add"]
)

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("add", "Add two numbers", {"a": float, "b": float})

async def add(args):

return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}

calculator = create_sdk_mcp_server(

name="calculator",

tools=[add]

)

options = ClaudeAgentOptions(

mcp_servers={"calc": calculator},

allowed_tools=["mcp__calc__add"]

)

5 安全隔离层

6 架构设计优势

1. 渐进式披露: Skills 使用三阶段加载(元数据→指令→资源),避免上下文溢出

2. 命名空间隔离: Plugin 的 skills/commands 自动添加命名空间,防止冲突

3. 权限控制: 可以为不同的工具、Skill、子代理设置不同的权限级别

4. 安全沙箱: SDK 应在沙箱容器环境中运行,提供进程隔离、资源限制和网络控制 Claude API Docs

5. 灵活组合: Skills、Commands、Agents、Hooks、MCP 可以自由组合,构建复杂工作流

Heart.Think.Do

Claude Code的分层架构