phuryn/product-engineering / app-stack/skills/embedded-agents-agent-sdk
embedded-agents-agent-sdk
VerifiedOnly 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:
-
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.
-
Install the missing dependencies. Run
npm i @anthropic-ai/claude-agent-sdk zod server-onlyandnpm i -D vitest. -
Copy the wrapper, route and tests, changing only import paths.
From this skill To the app templates/agent.tssrc/lib/agent.ts— the wrappertemplates/route.tssrc/app/api/agents/route.ts—GETlists agents,POSTstreams onetemplates/agent.test.tstests/unit/agent.test.ts— the contract, insidenpm test, no model calltemplates/agents.live.test.tstests/live/agents.live.test.ts— every agent against the real modelThe tests import
@/lib/agent, so Vitest needs the same@alias astsconfig.json. The live test gets its own Vitest config (includetests/live/**/*.live.test.ts,testTimeout: 180_000,fileParallelism: false) and a script,agents:live. It costs money, so it stays out ofnpm testand the gate. -
Set each required secret per environment and never commit it. Set
ANTHROPIC_API_KEYand every secret referenced by an agent's.mcp.json; applyenvironments. 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. -
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
- Create the agent directory and fill in its instructions. Run
node <skill dir>/scripts/new-agent.mjs <name> [--knowledge] [--mcp], then fill inAGENTS.md: role, sources, output format, refusals. A fixed sign-off line is the cheapest live-test proof that the instructions are in force. - Keep knowledge and automatically discovered skills inside the agent directory. Put knowledge in
knowledge/*.md, and tell the agent inAGENTS.mdto answer only from them. Agent-local skills are found automatically in.claude/agents/<name>/.claude/skills/<skill>/SKILL.md. - Allow only MCP tools the agent's job needs. Put servers in
.mcp.json, with secrets as${VAR}, never literal. Runnode --env-file=.env <skill dir>/scripts/discover-mcp-tools.mjs <name>to list each server's tools, then restrict itsallowedTools. Anything unlisted is denied. Commit the agent's.mcp.json, which holds no secrets. Ifgit check-ignorereports it ignored, the repository's.gitignorehas an unanchored.mcp.jsonrule meant for the root file. Anchor it as/.mcp.json. - Discover agents from their directories rather than hardcoding the UI list.
listAgents()finds the directory,GET /api/agentsreturns it, and the UI's picker shows it when users choose between agents. Fix a UI that hardcodes that list. - The instruction file is always
AGENTS.md. Asked for another name, createAGENTS.mdand say why: the wrapper loads onlyAGENTS.md, and the SDK loads some other instruction files on its own, which would give the agent two sets of instructions. - 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/agentswhen users choose agents. A product may run one front agent and show no picker; the route still checks the name againstlistAgents(). - Send the conversation to the route and read server-sent events.
POST { agent, prompt, history }to/api/agentsand 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
errorevent instead of spinning forever.
5. Explaining routing and the tool boundary
Validate the requested agent before routing it to the wrapper.
- UI
POST /api/agents { agent }- the route validates the body and requires the name to be in
listAgents() askAgentagentOptions()accepts only a plain directory name and resolves.claude/agents/<agent>/query()starts the Claude Code engine with that directory ascwdand itsAGENTS.mdappended to the system prompt- events stream back.
Keep every measured layer of the tool boundary in force. See playbook § 9:
- Expose only built-in tools on the allowlist. In
tools, only those built-ins exist —Read,Glob,Grepby default.Bash,Write,EditandWebFetchdo not. - Allow an MCP tool only when its server lists it. With
permissionMode: 'dontAsk'andallowedTools: an MCP tool runs only if its server'sallowedToolsin.mcp.jsonlists it. - Load only the agent's own MCP servers.
strictMcpConfig: only the agent's own.mcp.jsonservers load — nothing from the developer's or the server's user configuration. - List only the agent's own skills.
skillsenforces this. - Block paths outside the agent directory and every
.envfile. The PreToolUse guard enforces this. - Cap the run by turns and budget. Use
maxTurns(10 by default) andmaxBudgetUsd.
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 devneeds nothing. - History is a client claim.
templates/route.tsacceptshistoryfrom the client,assistantturns included, andcomposePromptturns 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 amaxBudgetUsd. - Run live tests before releasing any agent, prompt or model change. Run
npm run agents:livebefore 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Unverified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |