Agents, recipes, and Introspection

An agent is a runnable role with a model, instructions, capabilities, skills, and optional subagents. A recipe is the versioned package that keeps one or more agent definitions together with the resources they share. Recipes  is the open format for vertical agents, built on Pi: an agent is only as good as the standard you hold it to, and the recipe keeps that standard in the directory that does the work.

How the pieces fit together

1. A recipe defines the agent system. It packages agent definitions, shared instructions, skills, extensions, capability policy, and quality criteria as source you can inspect and own.
2. Pi runs an agent from that recipe. Pi coordinates the model, context, and tools through the agent loop, whether you are working locally or running the recipe elsewhere.
3. Introspection operates and improves it. The platform deploys a pinned recipe in a managed runtime, supplies environment-specific identity and infrastructure, and records the evidence needed to understand and improve behavior.

The recipe remains the source of truth for behavior. Pi is the harness that executes it. Introspection provides the production environment and learning loop around it.

Pi in one minute

Pi gives a model its instructions, working context, and tools, then coordinates the turns between the model and those capabilities: build the context, ask the model, execute an allowed tool, repeat until the work is done. Its minimal system prompt and deliberate extensibility — skills, extensions, prompt templates, and models as focused extension points — are what make it a great fit for actual context engineering, and they are exactly the surfaces a recipe declares.

Pi can run a resolved agent without requiring Introspection, which is what lets you work on a recipe locally and keep the behavior in source you control. Introspection then runs the same recipe semantics inside a managed runtime, so nothing is translated into a platform-specific format on the way to production. For the harness itself, see the Pi documentation .

Start with the foundation

• Recipes explains the portable package, its structure, and how its parts come together.
• Agent definitions explains how a recipe turns models, instructions, capabilities, variants, and subagents into runnable roles.

From there, use the focused pages in this section when you need to define a particular part of the agent system.