pi-graph

Author a schemaVersion 2 JSON graph defining agent nodes with context modes, edges for control flow, and response schemas for handoffs. Validate it with /pig validate, then run it with /pig run followed by your task text or JSON input.

Use a graph only when the task needs distinct specialties, parallelism, an independent reviewer, persistent role memory, typed handoffs, human approval gates, or failure isolation. For ordinary tasks, a single Pi agent loop is simpler and preferred.

Isolated mode gives nodes no private memory, suiting reviewers and parallel branches. Thread mode reopens a private session history per threadKey for roles persisting across loops. Shared mode appends role-tagged messages to graph state for an auditable conversation.

A human node pauses the run and returns an interrupt with a runId. Resume it using /pig resume <runId> with the user's answer as a value or JSON, or call the pi_graph_resume tool with the runId and value.

Parallel nodes writing the same path without a configured reducer cause the run to fail. Add a reducer such as collect, append, or merge to the path; use collect for current-round fan-in results in refinement loops.

Checkpoints are at-least-once, so external side effects are not exactly-once. readOnly is a tool allowlist, not an OS sandbox, so high-risk execution should run in a container.