The open format for vertical agents, built on Pi.

The model is interchangeable. Your definition of good is not.

$pi install npm:@introspection-ai/recipes

Use curl to read https://docs.introspection.dev/agents.md and follow the instructions to set up Introspection.

Own what makes your agent good

An agent is only as good as the standard you hold it to. Post-training already names that artifact: a recipe is the data, the stages and the evals that decide whether a model worked. Recipes is that for agent products.

Today that standard lives anywhere but the agent. Evals in a dashboard, judgment in the head of whoever reviews the output, a quality bar frozen into weights nobody can read. Recipes keeps it in the directory that does the work, in plain source you and your agents can both edit, so it sharpens every time you learn something.

Underneath is Pi, the Linux of agent harnesses: sessions, models, tools, and nothing it can leave to an extension. Recipes adds your domain on top of a harness you own.

An agent recipe is a directory

A package.json and one agent file are all a recipe needs to run. Skills, subagents, MCP policy, judges and evals are optional, added as the agent grows.

agent.yaml

name: agent
description: Research an account and produce a sourced brief.

model:
  name: anthropic/claude-sonnet-4-6
  thinking_level: high
  max_tokens: 16000
  temperature: 0.2

tools: [read, write, bash]
skills: [research]
subagents: [reviewer]

mcp:
  mode: cli
  servers:
    contacts:
      include: [search_contacts, get_contact]
    warehouse:
      include: [run_query]
      exclude: [drop_table]

system_instructions:
  mode: append
  content: |
    Verify every material claim against a source you
    actually read in this session. Never assert
    competitor pricing without a dated citation.

    Open with the recommendation, then the evidence.
    If the evidence is thin, say so in the first line
    rather than padding the brief to look complete.

agents/One file per agent: model, tool allowlist, skills, subagents. agent is the entry point.

Recipes extends Pi where it matters

Three new primitives, matching the way frontier agent products actually work.

Async multi-agents

Every agent can be invoked directly, or handed to a lead agent as a tool for orchestrated work. Runs return straight away and can be waited on, steered or interrupted while the lead keeps working.

agents/agent.yaml

name: agent
description: Research an account
model:
  name: anthropic/claude-sonnet-4-6
  thinking_level: high

tools: [read, write, bash]
skills: [research]
subagents:
  - reviewer
  - fact-checker

MCP tools and CLI

Configure tool-level policy once per package, then narrow it per agent. Two modes: registered tools with deferred loading, or a single mcp command the agent drives from bash, code-mode style.

agents/agent.yaml

mcp:
  mode: cli
  servers:
    contacts:
      include:
        - search_contacts
        - get_contact
    warehouse:
      include: ["*"]
      exclude:
        - drop_table

User interactions

Ask a question or request approval from inside a tool. One contract resolves it in the terminal, over RPC, headless in CI, and in a runtime that pauses the run and resumes it later.

extensions/ask.ts

return await askUserQuestion(
  {
    header: "Scope",
    question: "Which sources count?",
    options: [
      { label: "CRM only" },
      { label: "CRM and their site" },
    ],
  },
  { toolCallId, ctx, signal },
);

Recipes run like vanilla Pi

The same recipe runs across the TUI, RPC and the SDK, with no second API to learn.

TUI

Point Pi at the directory. The extension loads the recipe and configures the session.

pi --recipe .
pi --recipe . --agent reviewer

SDK

One constructor, then the Pi session you already know. Your process owns the lifecycle.

host.ts

import {
  createAgentSession,
  resolveRecipe,
} from "@introspection-ai/recipes";

const recipe = resolveRecipe({ recipeDir: "./my-agent" });
const handle = await createAgentSession({ recipe, agentName: "agent" });

// Identical Pi API from here
await handle.session.prompt("Research the Acme account");
await handle.dispose();

Deploy on any runtime

Pi runs the recipe. The platform supplies the sandbox, the credentials and the lifecycle.

Runtime

Built for long-horizon work, managed end to end

Durable runs

A run is a session that outlives the request: queued, resumable, and kept whole for inspection afterwards

Tasks and runs

Sandbox

Provisioned per run inside a governed environment

Sandboxes

Credentials

MCP servers connected once, brokered into each run

MCP federation

Deployment

Promote a recipe version into an environment

Runtimes and environments

Observability

Conversations, judgements and experiments

Judges and experiments

recipe

What you keep in Git

Build your first recipe.

Read the docs Browse templates