Create a recipe

A recipe is a versioned directory that defines one or more agents and what they share. Pi  runs it on your machine; Introspection runs the same files as a managed runtime. The format is Recipes .

You need: Node.js 24 or later. No account until you deploy.

1. Install the CLI

npm install -g @introspection-ai/cli
introspection setup          # installs Pi and Recipes

2. Scaffold a recipe

introspection init support-agent
cd support-agent

init copies template-starter from the introspection-recipes catalog and creates a Git repository. --template <name> picks another: template-claude, template-codex, template-multi-agent-research, template-slack-agent, or template-slack-triage. Inside an existing repository it adds the recipe as a subdirectory instead.

3. Shape the agent

package.json and agents/agent.yaml are the only required recipe files; the CLI also needs the runtime manifest init writes. Add the rest when a case needs it.

support-agent/
├── .introspection/support-agent.yaml   # Runtime manifest (deployment, not recipe)
├── package.json                        # Recipe manifest: dependencies and the `pi` block
├── SYSTEM.md                           # Instructions every agent shares
├── agents/agent.yaml                   # The default agent: model, tools, skills
├── skills/refund-policy/SKILL.md       # A procedure loaded when relevant
├── prompts/brief.md                    # A prompt template, run as /brief
├── extensions/lookup-order.ts          # TypeScript tools and hooks
├── judges/                             # Model-graded quality checks
├── files/                              # Inputs copied into every task
└── .recipeignore                       # Authoring-only paths left out of deploys

4. Run it locally

introspection local -p "Order 1842 arrived unopened. Draft the refund reply."
introspection local          # interactive Pi session

Run pnpm install first if package.json lists dependencies. local uses the agent’s ai.model and the provider key from your shell (or a Pi login); -- --model does not override it. If Pi cannot reach a model, see the Pi provider guide .

5. Check it and deploy

introspection check

check validates files, references, and agent policy; local and dev run it for you, and local refuses to start a recipe with errors. When the behavior is right, deploy your agent.

Verify

introspection check exits 0, and the local -p run answers the way your case expects. A passing check is not proof: only a real run is.

Already have an agent on another framework, or a Pi package? See Migrate an agent.

Or ask your agent: “Create a recipe for a support agent that drafts refund decisions from our policy, and run it locally.”