Embedding recipes

An Introspection runtime is the managed way to run a recipe, but the format does not require it. @introspection-ai/recipes exposes the same construction flow Pi’s TUI uses, so your own process—a server, a worker, a test harness—can run a recipe directly.

import {
  createAgentSession,
  resolveRecipe,
} from "@introspection-ai/recipes";
 
// Parses and validates the package once. No model client, no session.
const recipe = resolveRecipe({ recipeDir: "./my-agent" });
 
// Selects one agent from that snapshot and builds its Pi session.
const handle = await createAgentSession({ recipe, agentName: "agent" });
 
// handle.session is Pi's own AgentSession, unchanged.
await handle.session.prompt("Start the task");
 
// Closes children, session, telemetry, and MCP. Idempotent.
await handle.dispose();

resolveRecipe() and createAgentSession() are the whole public construction flow, both on the package root. Construction resolves the agent, resolves credentials fail-closed, materializes required MCP bindings fail-closed, loads skills, prompts, and extensions, registers the subagent tool, creates the Pi session, and returns one idempotent dispose().

The handle has four members:

Every construction option after recipe and agentName replaces transport or a materialized resource, never the portable definition—modelOverride is checked against the agent’s declared ai.model, so a host cannot quietly swap the model a recipe asked for.

The Recipes extension for Pi and embedded-host parity

Both paths use the same resolver and apply model metadata and provider payload policy, including OpenRouter routing, Anthropic context management, and Vercel AI Gateway routing. Embedded recipe sessions also apply ai.options and session directly to the live Pi agent and a session-local settings manager.

Pi’s current extension API exposes provider payload hooks but not setters for request defaults or session policy. Therefore pi --recipe fails closed when a recipe declares ai.options or session; it does not silently ignore the authored behavior. Use the embedded createAgentSession() path for those fields until Pi exposes the required setters.

Inspect before you run

import { inspectRecipe } from "@introspection-ai/recipes/inspect";
 
// Returns the same graph execution uses. Reads no host bindings.
const requirements = inspectRecipe(recipe);

Inspection reports the effective model, authored versus generated tools, selected skills, visible subagents, MCP policy, and expected credential variables—everything a host needs to know before committing to a session.

Prove your host

import { hostConformanceCases } from "@introspection-ai/recipes/test-utils";
 
for (const testCase of hostConformanceCases(myHost)) {
  it(testCase.name, testCase.run);
}

Passing the suite means your host constructs and disposes sessions with the same contract as Pi—a recipe behaves in your runtime the way it behaves locally. Protocol behavior, persistence, tenancy, and deployment remain host-specific and need their own tests.

The SDK deliberately ships no HTTP server, task database, scheduler, sandbox, or tenant isolation: those layers compose above the session boundary, which is exactly what an Introspection runtime provides.

See the SDK reference  for the complete options object, subpath exports, and run-controller contract.