wikis / Pi Agent / wiki / syntheses / integration-modes.md view as markdown report a mistake

Integration Modes: Interactive, Print, RPC, SDK

Pi's coding agent runs four ways; pick by how tightly you're integrating.

1. Interactive

The TUI session for a human at a terminal (quickstart-and-usage). Use for hands-on coding.

2. Print / JSON (one-shot)

Pass a prompt, get a single result and exit. Plain text for humans/scripts, or --json for structured output (the json doc) you can parse in CI or pipelines. Use for: code review bots, batch tasks, git hooks, anything non-interactive and stateless-per-call.

3. RPC (process integration)

A long-lived pi process speaking a JSON-RPC-style protocol over stdio: you send requests and subscribe to the event stream — agent_end, turn_end, message_update (text/thinking/toolcall deltas), tool_execution_update (streaming tool output). Use when an external process (editor, daemon, another service) needs a persistent, streaming agent it controls — without embedding TypeScript.

4. SDK (embed)

Import pi's agent into your own TypeScript app for full programmatic control — build custom interfaces, embed agent capabilities, or integrate with automated workflows. This is the deepest integration: you own the loop, UI, and orchestration around pi's agent core. OpenClaw embeds pi via the SDK as a real-world example (what-is-pi).

Choosing

All four share the same events, sessions, providers, and extensions — you're choosing a transport, not a different agent. Pi can help build the integration itself ("ask it to build an integration for your use case").