К основному содержанию
скилл CX Codex

embedded-agents-agent-sdk — скилл для Claude Code: установка и обзор

Скилл embedded-agents-agent-sdk для Claude Code и Codex встраивает агентов Claude в приложение на Next.js через Claude Agent SDK. Запускается при запросе на интеграцию Agent SDK или когда агенту нужен движок Claude Code.

MIT ★ 741 обновлён 2026-11-14

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add phuryn/product-engineering
/plugin install app-stack@product-engineering
Открыть на GitHub

Что делает embedded-agents-agent-sdk

Скилл разворачивает архитектуру встроенных агентов на базе @anthropic-ai/claude-agent-sdk. Движок запускается отдельным подпроцессом со встроенными инструментами оболочки, файловой системы и системным промптом Claude Code. Структура каждого агента хранится в каталоге .claude/agents/<name>/, а единственным файлом инструкций выступает AGENTS.md. Единая обёртка askAgent динамически исполняет любого описанного агента без хардкода имён в кодовой базе.

В проект копируются готовые шаблоны обёртки src/lib/agent.ts, потокового API-роута src/app/api/agents/route.ts и тестов Vitest. Инструменты MCP изолируются через .mcp.json внутри папки конкретного агента, при этом ключи передаются исключительно переменными среды.

Для работы SDK требует долгоживущий хост Node, пакеты @anthropic-ai/claude-agent-sdk, zod, server-only и ключ ANTHROPIC_API_KEY. На машине разработчика при отсутствии ключа поддерживается авторизация через локальный логин Claude. Скилл research-agent из примеров требует отдельный ключ PERPLEXITY_API_KEY.

Какие задачи решает

  • Встроить движок Claude Code в Next.js App Router через официальный Agent SDK
  • Изолировать контекст, файлы знаний и конфигурации MCP по папкам агентов
  • Настроить потоковую передачу ответов агентов через SSE в API-роутах Next.js
  • Покрыть поведение агентов модульными и живыми тестами с помощью Vitest

Примеры запросов агенту

  • Встрой Claude Agent SDK в этот Next.js проект с помощью скилла embedded-agents-agent-sdk
  • Создай нового агента с локальной базой знаний через embedded-agents-agent-sdk
  • Настрой потоковый роут для встроенного агента Claude

Как установить embedded-agents-agent-sdk

1Через маркетплейс плагинов

/plugin marketplace add phuryn/product-engineering
/plugin install app-stack@product-engineering

Команда ставит плагин app-stack целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

npx skills add phuryn/product-engineering --skill embedded-agents-agent-sdk -a claude-code

3Вручную: положить файлы

~/.claude/skills/embedded-agents-agent-sdk/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/embedded-agents-agent-sdk/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об embedded-agents-agent-sdk

Как установить embedded-agents-agent-sdk в Claude Code?

Выполните в терминале команду npx skills add phuryn/product-engineering --skill embedded-agents-agent-sdk -a claude-code или добавьте плагин через команды маркетплейса /plugin marketplace add phuryn/product-engineering и /plugin install app-stack@product-engineering.

Что делает embedded-agents-agent-sdk?

Разворачивает обёртку askAgent, API-роут и структуру каталогов .claude/agents/ для запуска движка Claude Code как подпроцесса внутри Next.js-сервера.

Что нужно для работы embedded-agents-agent-sdk?

Требуются долгоживущий Node-сервер, зависимости @anthropic-ai/claude-agent-sdk, zod, server-only, фреймворк Next.js и ключ ANTHROPIC_API_KEY.

Исходный текст

SKILL.md · MIT
---
name: embedded-agents-agent-sdk
description: "Only when the Agent SDK is asked for, an agent needs Claude Code's own tools, or the app already runs it: embed Claude agents in a Next.js app with the Agent SDK."
---

# Embedded agents — Claude Agent SDK

**Use the Agent SDK when the agent needs the Claude Code engine.** Also use it when the product already runs it. The SDK starts that engine as a subprocess with built-in file and shell tools and Claude Code's own system prompt. It loads skills and MCP and needs a long-lived Node host. Both embedded-agent skills run the same agent directories. The `embedded-agents-messages-api` skill is the default for a new product. It uses the Anthropic SDK's tool runner in the app's own process on any Node host, with only the wrapper's tools and no subprocess.

**Read the product's own agent instructions before changing its embedded agents.** Start with its root `AGENTS.md` or `CLAUDE.md`, and tell any subagent spawned for this work to read it too. Its rules on secrets, environment variables, validation, callers, tests and release apply here. This skill adds how to run Claude agents inside the app. Read `reference/playbook.md` before changing the wrapper's contract or explaining it in depth. It holds the full playbook and the measurement behind every option.

**Keep request, caller, storage and UI ownership in the app.** The agent owns reasoning and tools. An agent is a directory, `.claude/agents/<name>/`, with `AGENTS.md` as its only instruction file. It may also hold `knowledge/`, agent-local skills in `.claude/skills/`, and `.mcp.json`. One wrapper function, `askAgent`, runs any agent. No agent name appears in code.

## 1. First use: install the wrapper

**Search for `askAgent` before installing another wrapper.** If it exists, skip to § 2. Otherwise:

1. **Create only the smallest requested app when none exists.** Use Next.js App Router in TypeScript, which these files target. Add nothing unasked for: no database, sign-in or billing for a local prototype.
2. **Install the missing dependencies.** Run `npm i @anthropic-ai/claude-agent-sdk zod server-only` and `npm i -D vitest`.
3. **Copy the wrapper, route and tests, changing only import paths.**

   | From this skill | To the app |
   |---|---|
   | `templates/agent.ts` | `src/lib/agent.ts` — the wrapper |
   | `templates/route.ts` | `src/app/api/agents/route.ts` — `GET` lists agents, `POST` streams one |
   | `templates/agent.test.ts` | `tests/unit/agent.test.ts` — the contract, inside `npm test`, no model call |
   | `templates/agents.live.test.ts` | `tests/live/agents.live.test.ts` — every agent against the real model |

   The tests import `@/lib/agent`, so Vitest needs the same `@` alias as `tsconfig.json`. The live test gets its own Vitest config (include `tests/live/**/*.live.test.ts`, `testTimeout: 180_000`, `fileParallelism: false`) and a script, `agents:live`. It costs money, so it stays out of `npm test` and the gate.
4. **Set each required secret per environment and never commit it.** Set `ANTHROPIC_API_KEY` and every secret referenced by an agent's `.mcp.json`; apply `environments`. On a developer's laptop the SDK falls back to their own Claude login when the key is absent; a deployed product always uses the key.
5. **Keep the contract.** Every option in `agentOptions()` exists because an SDK default failed a measurement (playbook § 9). Change one only after re-measuring it.

## 2. Add an agent

1. **Create the agent directory and fill in its instructions.** Run `node <skill dir>/scripts/new-agent.mjs <name> [--knowledge] [--mcp]`, then fill in `AGENTS.md`: role, sources, output format, refusals. A fixed sign-off line is the cheapest live-test proof that the instructions are in force.
2. **Keep knowledge and automatically discovered skills inside the agent directory.** Put knowledge in `knowledge/*.md`, and tell the agent in `AGENTS.md` to answer only from them. Agent-local skills are found automatically in `.claude/agents/<name>/.claude/skills/<skill>/SKILL.md`.
3. **Allow only MCP tools the agent's job needs.** Put servers in `.mcp.json`, with secrets as `${VAR}`, never literal. Run `node --env-file=.env <skill dir>/scripts/discover-mcp-tools.mjs <name>` to list each server's tools, then restrict its `allowedTools`. Anything unlisted is denied. Commit the agent's `.mcp.json`, which holds no secrets. If `git check-ignore` reports it ignored, the repository's `.gitignore` has an unanchored `.mcp.json` rule meant for the root file. Anchor it as `/.mcp.json`.
4. **Discover agents from their directories rather than hardcoding the UI list.** `listAgents()` finds the directory, `GET /api/agents` returns it, and the UI's picker shows it when users choose between agents. Fix a UI that hardcodes that list.
5. **The instruction file is always `AGENTS.md`.** Asked for another name, create `AGENTS.md` and say why: the wrapper loads only `AGENTS.md`, and the SDK loads some other instruction files on its own, which would give the agent two sets of instructions.
6. **Add a live test for each promise worth pinning.** Examples include citing, refusing and answering only from its files. Put it beside the generic test.

## 3. Examples — only when asked

**Copy finished examples only when asked for or described.** The `examples/` agents are: answering only from local product-management knowledge files (`knowledge-agent`), or live-web research through Perplexity with citations (`research-agent`). Copy `examples/<name>/` to `.claude/agents/<name>/` and `examples/<name>.live.test.ts` to `tests/live/`. `research-agent` needs `PERPLEXITY_API_KEY`. Otherwise, never copy them.

## 4. The chat UI

**Build the chat UI for this product and its agent flow.** There is no template. It must do the following:

- **Fill the picker from `GET /api/agents` when users choose agents.** A product may run one front agent and show no picker; the route still checks the name against `listAgents()`.
- **Send the conversation to the route and read server-sent events.** `POST { agent, prompt, history }` to `/api/agents` and read: `{ text }` chunks, then `{ done, agent, metadata }` or `{ error, agent }`. The parser is in playbook § 5.
- **Store the agent on every message; identify replies with several agents.** When there is more than one agent, show it on each reply, so the reader always knows which agent answered. History is the conversation so far, kept in client state unless the product asks to persist it.
- **Render agent output as plain text or sanitized markdown.** Never render raw HTML: it is untrusted text, like anything a user typed. Show an `error` event instead of spinning forever.

## 5. Explaining routing and the tool boundary

**Validate the requested agent before routing it to the wrapper.**

1. UI
2. `POST /api/agents { agent }`
3. the route validates the body and requires the name to be in `listAgents()`
4. `askAgent`
5. `agentOptions()` accepts only a plain directory name and resolves `.claude/agents/<agent>/`
6. `query()` starts the Claude Code engine with that directory as `cwd` and its `AGENTS.md` appended to the system prompt
7. events stream back.

**Keep every measured layer of the tool boundary in force.** See playbook § 9:
1. **Expose only built-in tools on the allowlist.** In `tools`, only those built-ins exist — `Read`, `Glob`, `Grep` by default. `Bash`, `Write`, `Edit` and `WebFetch` do not.
2. **Allow an MCP tool only when its server lists it.** With `permissionMode: 'dontAsk'` and `allowedTools`: an MCP tool runs only if its server's `allowedTools` in `.mcp.json` lists it.
3. **Load only the agent's own MCP servers.** `strictMcpConfig`: only the agent's own `.mcp.json` servers load — nothing from the developer's or the server's user configuration.
4. **List only the agent's own skills.** `skills` enforces this.
5. **Block paths outside the agent directory and every `.env` file.** The PreToolUse guard enforces this.
6. **Cap the run by turns and budget.** Use `maxTurns` (10 by default) and `maxBudgetUsd`.

## 6. Before it leaves localhost

- **Choose a long-lived Node host before the agent leaves localhost.** The SDK runs the Claude Code engine as a subprocess, so an agent cannot run in a serverless function such as a Netlify Function (playbook § 7). A product whose site deploys there needs a second, long-lived Node host (a container or VM, such as Railway), chosen before the agent goes beyond localhost; write its deploy procedure into the product's docs the first time it is used. `next dev` needs nothing.
- **History is a client claim.** `templates/route.ts` accepts `history` from the client, `assistant` turns included, and `composePrompt` turns it into a "Previous conversation" preamble — so a client can forge earlier turns, the agent's own included. That is acceptable for a read-only agent, which can only be talked into saying something to the person forging it. Before any tool acts on the caller's behalf, keep the transcript on the server and stop reading it from the request.
- **Resolve the caller and cap cost before opening the route.** Before anyone but the developer can reach the route, resolve the caller there (who they are, which workspace, which permission: `saas-authorization`) and set a per-actor limit and a `maxBudgetUsd`.
- **Run live tests before releasing any agent, prompt or model change.** Run `npm run agents:live` before any release that adds or changes an agent, its prompt or its model, record the run in the product's test-coverage map (which test proves what, and when it last passed), and describe each agent in its automation doc: what it may read, the exact tools it may call, and what the app enforces around it (`shipping-artifacts`).

## How you can tell it worked

The agent runs on the deployed host, not only on localhost, uses only the tools it was given, and the live agent suite passes against the real model.

## Running the scripts

**Run these scripts from the app's repository root.** `<skill dir>` is this skill's installation location: a plugin, `~/.claude/skills/`, or the repository's own `.claude/skills/`. The scripts write into the current directory.

© Paweł Huryn · MIT · phuryn/product-engineering

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
new-sdk-app официальный Anthropic Команда new-sdk-app для Claude Code, которая разворачивает новый проект на Claude Agent SDK — на TypeScript или Python — с нуля. Задаёт структуру каталогов, устанавливает пакеты, генерирует стартовый код и проверяет типы перед завершением. CX Codex +1 ★ 47 914звёзд репо agent-sdk-verifier-ts официальный Anthropic Субагент agent-sdk-verifier-ts проверяет конфигурацию приложений на базе @anthropic-ai/claude-agent-sdk. Находит ошибки сборки, утечки ключей и проблемы в tsconfig.json перед развёртыванием. CX Codex ★ 47 914звёзд репо vercel-ai-sdk wsimmonds Подсказывает агенту, как писать код на Vercel AI SDK v5: чат через useChat, стриминг, вызов инструментов, эмбеддинги. CX Codex +1 348установок migrating-claude-agent-sdk-to-pydantic-ai pydantic Скилл migrating-claude-agent-sdk-to-pydantic-ai для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI переводит Python-приложения с claude_agent_sdk на Pydantic AI. CX Codex +1 468установок nuqs-scaffolder pproenca Скилл nuqs-scaffolder собирает из одного JSON-описания четыре файла для фильтров в URL на Next.js: карту парсеров, серверный загрузчик, клиентский компонент и тест. CX Codex +1 145установок typescript-scaffold Seth Hobson Команда typescript-scaffold создаёт структуру TypeScript-проекта на pnpm: Next.js, React с Vite, Node.js API или библиотеку, вместе с тестами и сборкой. CX Codex +1 ★ 42 780звёзд репо

Из того же набора51

Весь набор →
performance-audit-static Скилл performance-audit-static для Claude Code проверяет производительность кода статически: ищет N+1-запросы, лишнюю загрузку данных, проблемы с индексами и кешированием. Запускается по запросу на аудит производительности. CX Codex +1 ★ 741звёзд репо legal-pages Скилл legal-pages для Claude Code помогает подготовить юридические страницы по фактическому поведению приложения. Запускается при создании продукта и изменениях в обработке данных, cookies или провайдерах. CX Codex +1 ★ 741звёзд репо flight-deck Скилл flight-deck для Claude Code, который сохраняет ход долгой работы в файлах и на странице статуса. Запускается по просьбе показать прогресс или восстановить, на чём остановилась сессия. CX Codex +1 ★ 741звёзд репо environments Скилл environments для Claude Code разделяет настройки разработки и production, а также описывает работу с секретами и миграциями. Агент подключает его при настройке окружения, добавлении переменной или разборе утечки ключа. CX Codex +1 ★ 741звёзд репо mcp-server Скилл mcp-server для Claude Code помогает собрать удалённый MCP-сервер, подключить OAuth и подготовить его к публикации в каталоге. Описывает этапы разработки, проверки инструментов и подтверждения работы клиента. CX Codex +1 ★ 741звёзд репо transactional-email Скилл transactional-email для Claude Code помогает добавить транзакционные письма и оповещения в приложение. Разбирает выбор почтового провайдера, повторы отправки и отписку в один клик. CX Codex +1 ★ 741звёзд репо grok-agents Скилл grok-agents для Claude Code запускает Grok CLI из другого агента как партнёра, исполнителя или независимого ревьюера. Он подключается к просьбам привлечь Grok к обсуждению решения, этапу разработки или проверке изменений. CX Codex +1 ★ 741звёзд репо shipping-artifacts Скилл shipping-artifacts для Claude Code создаёт комплект технической документации для аудита и передачи кода. Фиксирует архитектуру, сценарии с проверками прав, переменные окружения и карту покрытия тестами. CX Codex +1 ★ 741звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой