SDK reference

Construct a session

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

// Parses and validates the package once. No model client, no session.
const recipe = resolveRecipe({ recipeDir });

// Selects one agent from that snapshot and builds its Pi session.
const handle = await createAgentSession({
  recipe,
  agentName,
  cwd: workspaceDir,
  credentials,
});

// handle.session is Pi's own AgentSession, unchanged.
await handle.session.prompt("Start the task");

// Closes children, session, instrumentation and MCP. Idempotent.
await handle.dispose();

createAgentSession(options) is the only session constructor. Root sessions, default in-process child sessions, conformance tests and external hosts all call it, and it always takes one options object. Both it and resolveRecipe() are on the package root, so the whole construction flow is one import.

Hold the snapshot

Resolve once, then inspect the plan and construct every session, root and child, from that same graph. See Recipes for what resolution produces.

const recipe = resolveRecipe({ recipeDir });

// Read the plan before committing to it: model, tools, MCP policy.
const agent = recipe.selectAgent("reviewer");
const credentials = await credentialsFor(agent.modelSpec);

const handle = await createAgentSession({
  recipe,
  agentName: agent.name,
  credentials,
});

Options

const handle = await createAgentSession({
  // What to run. Only these two are about the recipe.
  recipe,
  agentName,

  // Transport and materialized resources
  cwd,
  credentials,
  modelOverride,
  mcpBindings,
  mcpBindingsPath,
  mcpProvisioning,
  env,

  // Execution seams
  runController,
  inProcessRunController,
  agentToolOptions,
  extensionFactories,
  customTools,
  eventBus,
  settingsManager,
  sessionManager,
  additionalSkillPaths,
  materializedSkillPaths,
  transformSystemPrompt,

  // What the host observes
  onDiagnostics,
  onEvent,
  otel: { tracer, meter, meta: { conversationId } },
});

Types for every option are exported from /session. 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().

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

The handle

Agent runs

Recipes defines AgentRunController in /agents as a portable contract and ships one lightweight in-process implementation. See Agents for what a child inherits.

const runs = handle.agentRuns.list();

// Or hand the same contract a durable, cross-process implementation.
const durable = await createAgentSession({
  recipe,
  agentName,
  runController: myDurableController,
});

An injected controller owns child selection and execution once the root session exists. dispose() calls its shutdown() exactly once, while close(id) ends a single run.

Inspection

import { inspectRecipe } from "@introspection-ai/recipes/inspect";

// Returns the same graph execution uses. Reads no host bindings.
const requirements = inspectRecipe(recipe);

Inspection reports effective model and prompt provenance, what each step of a from: chain declared, authored versus root and delegated tools, selected skills, visible subagents, MCP policy, expected credential variables, and the ordered extension and prompt closure. Binding files are host state and are excluded.

OpenTelemetry

otel takes tracer, meter, meta, and the runSpans and getParentContext seams for hosts that create their own turn spans. See Telemetry for the spans, attributes and metrics this produces.

Environment leases

In CLI mode, default MCP provisioning leases the supplied env object until the handle is disposed, then restores its prior state. Concurrent CLI sessions need separate environment objects. A host that provisions MCP itself passes mcpProvisioning: "host".

Conformance

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 uses the same session-construction contract as Pi. Protocol behavior, persistence, tenancy and deployment remain host-specific and need their own tests.

Public exports

Not included

No HTTP server or wire protocol, no task database or state machine, no scheduler or queue, no sandbox or tenant isolation, no deployment CLI, no provider-specific hosting integrations. Those layers compose above the session boundary.