用途
该技能解决的是在应用内部运行 Claude 智能体的问题，具体做法是使用 Claude Agent SDK：SDK 把 Claude Code 引擎作为子进程启动，从而获得内置的文件与 shell 工具、Claude Code 自身的系统提示、技能与 MCP 加载能力，以及长期运行的 Node 宿主环境。
同类技能 embedded-agents-messages-api 则在应用自身进程内通过 Anthropic SDK 的工具运行器调用 Claude API，只有封装提供的工具、无子进程、任意 Node 宿主都行，是新产品默认选择。只有在智能体需要引擎独有的能力，或产品本身已经在运行引擎时，才使用本技能。
资料同时说明：动手前先读产品自己的智能体指令（根目录的 AGENTS.md 或 CLAUDE.md），并要求为这项工作派生的任何子智能体也阅读它们；其中关于密钥、环境变量、校验、调用方、测试和发布的规则同样适用本技能。reference/playbook.md 是完整手册，包含每个选项背后的度量依据，在修改封装契约或深入解释前应先阅读。
主要能力与模型
应用负责请求、调用方、存储和 UI；智能体负责推理和工具。一个智能体就是一个目录 .claude/agents/<name>/，其中 AGENTS.md 是其唯一指令文件，可选包含 knowledge/、.claude/skills/ 下的智能体本地技能以及 .mcp.json。一个封装函数 askAgent 运行任意智能体，代码中不出现任何智能体名称。
使用方式
首次使用：先在代码中搜索 askAgent，已存在则跳过。没有应用时，创建最小的 Next.js App Router TypeScript 应用，不加用户未要求的东西（本地原型无数据库、登录或计费）。安装缺少的依赖：npm i @anthropic-ai/claude-agent-sdk zod server-only 和 npm i -D vitest。然后复制模板（仅改 import 路径）：templates/agent.ts 到 src/lib/agent.ts（封装）；templates/route.ts 到 src/app/api/agents/route.ts（GET 列出智能体，POST 流式运行一个）；templates/agent.test.ts 到 tests/unit/agent.test.ts（契约测试，包含在 npm test 中，不调用模型）；templates/agents.live.test.ts 到 tests/live/agents.live.test.ts（每个智能体对真实模型测试）。测试导入 @/lib/agent，因此 Vitest 需要与 tsconfig.json 相同的 @ 别名。实时测试使用独立 Vitest 配置（include tests/live/**/*.live.test.ts、testTimeout: 180_000、fileParallelism: false）和 agents:live 脚本；它会产生费用，因此不放入 npm test 和门禁。
环境变量：ANTHROPIC_API_KEY，加上每个智能体 .mcp.json 引用的所有密钥，按环境设置且永不提交。开发者本机缺少密钥时 SDK 回退到其自己的 Claude 登录；已部署产品始终使用密钥。保持契约：agentOptions() 中每个选项都存在，是因为某个 SDK 默认值未通过度量（playbook § 9），只有重新度量后才能改动。
添加智能体：运行 node <skill dir>/scripts/new-agent.mjs <name> [--knowledge] [--mcp]，然后填写 AGENTS.md：角色、来源、输出格式、拒绝情形。固定的结束语是实时测试中最省事的证明指令生效的方式。知识库：knowledge/*.md 文件，AGENTS.md 要求仅据此回答。智能体本地技能：.claude/agents/<name>/.claude/skills/<skill>/SKILL.md，会自动发现。MCP：.mcp.json 中配置服务器，密钥写为 ${VAR}，绝不写字面值；运行 node --env-file=.env <skill dir>/scripts/discover-mcp-tools.mjs <name> 列出各服务器提供的能力，然后在该服务器的 allowedTools 中只放智能体工作所需的项，未列出的一律拒绝。智能体的 .mcp.json 不含密钥且会提交；若 git check-ignore 报告其被忽略，说明仓库 .gitignore 有未锚定的 .mcp.json 规则（针对根文件），应锚定为 /.mcp.json。
路由无需额外配置：listAgents() 发现目录，GET /api/agents 返回，用户在多个智能体间选择时 UI 选择器展示。硬编码列表的 UI 是应修复的 bug。指令文件始终是 AGENTS.md；若要求其他名称，应创建 AGENTS.md 并说明原因：封装只加载 AGENTS.md，而 SDK 会自行加载某些其他指令文件，会导致智能体有两套指令。当智能体做出值得固定的承诺（引用、拒绝、仅据文件回答）时，在通用测试旁增加实时测试。
示例：examples/ 包含两个完成的智能体，仅在用户要求示例或描述其中之一时使用——仅根据本地产品管理知识文件回答的 knowledge-agent，以及通过 Perplexity 研究实时网页并带引用的 research-agent。复制 examples/<name>/ 到 .claude/agents/<name>/，examples/<name>.live.test.ts 到 tests/live/。research-agent 需要 PERPLEXITY_API_KEY。否则不要复制。
聊天 UI：因产品而异，无模板。要求：用户在多个智能体间选择时，从 GET /api/agents 填充选择器；产品可以只运行一个前端智能体而不显示选择器，路由仍在校验名称属于 listAgents()。向 /api/agents POST { agent, prompt, history } 并读取服务器发送事件：{ text } 块，然后 { done, agent, metadata } 或 { error, agent }。解析器在 playbook § 5。在每条消息上存储智能体，多于一个时在每条回复上显示，让读者始终知道是哪个智能体回答。history 是迄今为止的对话，除非产品要求持久化，否则保存在客户端状态。智能体输出按纯文本或经净化的 markdown 渲染，绝不原始 HTML：它和用户输入一样是不可信文本。显示错误事件而不是一直转圈。
路由与工具边界
路由：UI → POST /api/agents { agent } → 路由校验请求体并要求名称在 listAgents() 中 → askAgent → agentOptions() 只接受纯目录名并解析 .claude/agents/<agent>/ → query() 以该目录为 cwd 启动 Claude Code 引擎，并将其 AGENTS.md 追加到系统提示 → 事件流回。
边界（每层均已度量，见 playbook § 9）：tools：只有白名单中的内置工具存在——默认 Read、Glob、Grep；Bash、Write、Edit 和 WebFetch 不存在。permissionMode: 'dontAsk' 配合 allowedTools：MCP 工具仅当其服务器的 allowedTools 在 .mcp.json 中列出时才运行。strictMcpConfig：只加载智能体自己的 .mcp.json 服务器，不加载开发者或服务器用户配置中的任何东西。skills：只列出智能体自己的技能。PreToolUse 防护会阻止智能体目录之外的任何路径以及任何 .env 文件。maxTurns（默认 10）和 maxBudgetUsd 限制单次运行。
离开 localhost 之前
托管：SDK 将 Claude Code 引擎作为子进程运行，因此智能体无法在无服务器函数（如 Netlify Function，playbook § 7）中运行。站点部署在那里的产品需要第二个长期运行的 Node 主机（容器或 VM，如 Railway），应在智能体超出 localhost 前选定；首次使用时把部署流程写入产品文档。next dev 无需任何配置。
历史是客户端声明：templates/route.ts 接受来自客户端的历史（含 assistant 轮次），composePrompt 将其转为“Previous conversation”前言——因此客户端可以伪造先前的轮次，包括智能体自己的。对只读智能体可接受，因为它只能被说服对伪造者本人说些什么。在任何工具代表调用方行动之前，应把对话记录保存在服务器上，停止从请求读取。
调用方与成本：在开发者以外的人能访问路由之前，应在路由中解析调用方（是谁、哪个工作区、什么权限：saas-authorization）并设置按行为主体的限制和 maxBudgetUsd。
发布：在任何添加或更改智能体、其提示或其模型的发布前运行 npm run agents:live，将运行记录写入产品的测试覆盖图（哪个测试证明什么、上次通过时间），并在自动化文档中描述每个智能体：可读什么、可调用哪些确切工具、应用在其周围强制什么（shipping-artifacts）。
验证与脚本运行
如何判断生效：智能体在已部署主机上运行而不只是 localhost，只使用被赋予的工具，实时智能体套件对真实模型通过。
运行脚本：从应用仓库根目录运行；<skill dir> 是本技能安装位置（插件、~/.claude/skills/ 或仓库自己的 .claude/skills/），脚本写入当前目录。
适用场景与限制
适用于已在或计划以 Next.js 构建、且需要智能体使用 Claude Code 引擎内置文件与 shell 工具、技能与 MCP 加载能力的产品；也适用于产品已运行该引擎的情况。限制包括：无法部署到无服务器函数，需要长期 Node 宿主；客户端提供的历史可被伪造，在有工具代表调用方行动前需改为服务端保存；实时测试产生费用，不纳入默认测试；需自行管理密钥、调用方鉴权与预算上限。