Embedded agents — Claude API

Which skill. Two skills run the same agent directories. This one runs them on the Claude API: the Anthropic SDK's tool runner (client.beta.messages.toolRunner) drives the loop inside the app's process, and the agent has exactly the tools the wrapper gives it — nothing built in. It is the default for a new product. The embedded-agents-agent-sdk skill runs them through the Claude Agent SDK, which starts the Claude Code engine as a subprocess with built-in file and shell tools and needs a long-lived Node host: use it only when an agent needs what only that engine has, or the product already runs it. An agent directory moves between the two unchanged (playbook § 10).

Read the product's own agent instructions first (its root AGENTS.md or CLAUDE.md), and tell any subagent you spawn for this work to read them too: their rules on secrets, environment variables, validation, callers, tests and release apply to everything here. reference/playbook.md is the full playbook, with the measurement behind every choice — read it before changing the wrapper's contract or explaining it in depth.

The model: the app owns the request, the caller, storage and the UI; the agent owns reasoning and tool choice. An agent is a directory, .claude/agents/<name>/, holding AGENTS.md (its instructions — its whole system prompt), and optionally knowledge/, agent-local skills in .claude/skills/, and .mcp.json. One wrapper function, askAgent, runs any of them. No agent name appears in code.

1. First use: install the wrapper

Search the code for askAgent. If it exists, skip to § 2 (if it imports @anthropic-ai/claude-agent-sdk, the product is on the other skill — moving it is playbook § 10). Otherwise:

1. No app yet? Create the smallest Next.js App Router app in TypeScript (what this skill's files are written for) and nothing the user did not ask for — no database, sign-in or billing for a local prototype.
2. Install what is missing: npm i @anthropic-ai/sdk @modelcontextprotocol/sdk zod server-only and npm i -D vitest. Pin exact versions: the tool runner is marked beta in the TypeScript SDK, so an upgrade is re-tested, not assumed.
3. Copy, changing only import paths: