Agent recipes

A recipe is the versioned package defining one or more agents and the resources they share. Recipes  is the open format for vertical agents, built on Pi.

A recipe has the following properties:

• Ownership. Agent definitions, instructions, skills, capability policy, and quality criteria live in your repository.
• Portability. Pi runs the same recipe semantics locally and inside an Introspection runtime, across supported models and infrastructure.
• Reviewability. Git shows which behavior changed and lets normal pull request controls govern production changes.
• Composability. Start with one agent, then add focused skills, tools, subagents, and judges only as requirements emerge.

Recipe, Pi, and Introspection

Pi can run a recipe without an Introspection account. Introspection surrounds that same behavior with customer identity, scoped bindings, isolated sandboxes, durable tasks, conversations, judges, experiments, and deployment controls. Nothing is translated into a platform-specific agent format on the way to production.

Inside a recipe

The refund exception agent from the Quickstart begins with one agent, one skill, and one safe capability:

refund-exception-agent/
├── agents/
│   └── agent.yaml
├── skills/
│   └── refund-exceptions/SKILL.md
├── reference/
│   └── refund-policy.md
├── SYSTEM.md
└── package.json

The adjacent .introspection/refund-exception-agent.yaml file connects this directory to a managed runtime. It is deployment configuration, not part of the portable recipe.

{
  "name": "@acme/refund-exception-agent",
  "version": "0.1.0",
  "description": "Review refund exceptions and draft evidence-backed responses.",
  "type": "module",
  "pi": {
    "agents": ["agents/*.yaml"],
    "skills": ["skills/**/SKILL.md"]
  }
}

name: agent
description: Reviews refund eligibility and prepares the next safe action.
ai:
  model: anthropic/claude-sonnet-4-6
tools:
  - read
skills:
  - refund-exceptions
system_instructions:
  mode: append
  content: |
    Ground every decision in the current refund policy and order record.
    Draft responses and escalations; never issue a refund.

---
description: Review refund eligibility and prepare a grounded response or escalation.
---
 
# Refund exceptions
 
1. Read the current refund policy and the supplied order record.
2. Identify the controlling rule and the evidence supporting it.
3. Ask for one missing fact when a decision cannot yet be made.
4. Escalate fraud, chargebacks, high-value exceptions, conflicting records,
   or policy ambiguity.
5. Otherwise draft the response. Never issue the refund yourself.
6. Begin the result with `Decision: approve`, `Decision: decline`,
   `Decision: escalate`, or `Decision: need_information`, then cite the evidence
   and provide the draft or escalation note.

name: refund-exception-agent
path: ./refund-exception-agent
description: Refund exception agent for customer operations.
runtime:
  llm_mode: managed

Run the recipe locally from the repository root:

introspection local \
  --runtime refund-exception-agent \
  --print "Review order 1842 against the refund policy and draft the next response."

The useful result is not merely a valid package. The trace should show the agent reading the authoritative files, applying the controlling rule, and returning a draft or escalation without taking the irreversible action.

Add structure only when it earns its place

Start with the smallest agent that handles representative cases. Extend it when the evidence shows a real need:

Avoid copying the same instruction into several agent files. Put shared rules in SYSTEM.md, detailed procedures in skills, and role-specific behavior in agent YAML. Reference canonical files instead of duplicating their contents.

Distribution and deployment

Distribution is Git. Pushing the directory publishes source that anyone with Pi and the Recipes extension can resolve and run. A registry package is optional, and sharing a recipe does not create an Introspection runtime.

Deployment is a separate, explicit action. Introspection reads the adjacent runtime manifest, records the exact repository path and commit, and creates an immutable runtime version. Environment-specific credentials, endpoints, customer identity, and infrastructure remain outside the recipe as bindings and runtime configuration.

Continue

• Agent definitions: models, capabilities, variants, and subagents.
• Skills and prompts: progressively loaded domain procedures.
• Packaging: composition, distribution, and dependency boundaries.
• Develop and ship: move a recipe change through staging to production.