Recipes

A recipe keeps package-wide instructions, agent definitions, skills, extensions, capability policy, judges, and optional user interactions together. Pi Recipes is the open format for vertical agents, built on Pi, and the toolchain that creates, validates, resolves, runs, and distributes these packages.

A small customer-support recipe might look like this:

customer-support/
├── agents/
│   ├── agent.yaml
│   ├── triage.yaml
│   └── escalation.yaml
├── skills/
│   └── ticket-triage/SKILL.md
├── judges/
│   └── useful-support-resolution.yaml
├── SYSTEM.md
└── package.json

Benefits of recipes:

• Own the behavior. Instructions, agents, skills, capability policy, and quality definitions live together as reviewable source rather than hidden configuration.
• Run the same agent in every stage. Use the recipe locally with Pi, then deploy a commit-pinned version to Introspection without redefining the agent.
• Change it deliberately. Git history shows exactly which behavior changed, while structural checks, judges, and the evals you keep beside the recipe make important expectations repeatable.
• Compose instead of copy. Share package-wide rules, derive agent variants, and add focused skills, extensions, or subagents as the system grows.
• Keep behavior portable. The recipe declares what the agent needs while Introspection supplies environment-specific credentials, bindings, identity, and infrastructure at runtime.

When you deploy with Introspection, an adjacent .introspection manifest connects the committed recipe source to a managed Pi runtime. It is deployment configuration, not part of the portable Pi Recipes format. See Runtimes and environments for how a commit becomes a runtime version.

Inside a recipe

A recipe folder uses package.json as its manifest and entry point. Top-level fields identify the package; the pi block declares recipe-owned resources and policies such as agents, skills, prompts, optional extensions, and the MCP servers the recipe may use. Shared instructions live in SYSTEM.md, and each agent is a YAML file (the conventional default is agents/agent.yaml; named variants are additional agents).

The final tab shows adjacent Introspection deployment configuration for context. It is not part of the recipe itself.

{
  "name": "@acme/customer-support",
  "version": "0.1.0",
  "description": "Triage support requests, draft grounded replies, and escalate sensitive cases.",
  "type": "module",
  "pi": {
    "agents": ["agents/*.yaml"],
    "skills": ["skills/**/SKILL.md"],
    "mcp": {
      "servers": [
        {
          "id": "slack",
          "required": false,
          "tools": {
            "include": ["slack_read_thread", "slack_send_message_draft"]
          }
        }
      ]
    }
  }
}

name: agent
description: Triage support requests, retrieve approved answers, and draft replies.
ai:
  model: anthropic/claude-sonnet-4-6
  thinking_level: medium
  options:
    max_tokens: 4096
session:
  tool_execution: parallel
  retry:
    enabled: true
    max_retries: 2
tools:
  - read
mcp:
  mode: tools
  servers:
    slack:
      include:
        - slack_read_thread
        - slack_send_message_draft
subagents:
  - triage
  - escalation
skills:
  - ticket-triage
system_instructions:
  mode: append
  content: |
    Search approved sources before answering. Escalate billing, security,
    legal, privacy, and account-access requests to a human. Draft replies;
    do not send them unless the user explicitly asks.

---
description: Use for support ticket triage, reply drafting, and escalation notes.
---
 
# Ticket triage
 
1. Identify the customer's ask, impact, and urgency.
2. Check for billing, security, legal, privacy, or account-access risk.
3. Retrieve an approved answer or record what is missing.
4. Draft a reply with a concrete next step, or prepare a human escalation.

name: customer-support-agent
path: .
description: Customer-support recipe for Pi and Introspection.
runtime:
  llm_mode: managed

Offline evals

Judges are the recipe’s validated evals; everything else you measure with lives in an evals/ directory that is yours — versioned beside the behavior it measures, but not part of the format. See Judges & evals for the split.

More on recipes