Pi Agent Python SDK

Your terminal agent. Your Python API.

Pi is the coding agent that runs in your terminal. This unofficial community SDK puts your Pi behind a typed sync and async Python API — run prompts, stream events, and keep sessions going without leaving Python.

https://github.com/user-attachments/assets/c64dde3a-e812-42d4-a005-aa60df861e92

from pi_agent import PiClient

with PiClient() as pi:
    print(pi.run("Explain the current project without changing files.").text)

Requires an installed, configured Pi CLI — see Prerequisites.

Prerequisites · Quick start · Streaming · Async · Configuration · Thinking · RPC · Documentation · Troubleshooting · Support

What you can do

• Run prompts from Python — get a final answer, or stream text, thinking, and tool events as they happen.
• Keep conversations going — send follow-ups on the same client, or resume, fork, and clone sessions.
• Control the agent — switch models, set thinking level, steer mid-run, and compact context.
• Reuse your Pi setup — same configuration, tools, and extensions as the CLI, with sync or async clients.

Prerequisites

Quick start

Install Pi with Node.js 22.19.0 or newer (pin matches the tested baseline):

npm install -g @earendil-works/pi-coding-agent@0.87.0
pi --version

Run pi once to configure your provider and model. The SDK uses that configuration when it starts Pi.

Install the Python package from PyPI:

python -m pip install pi-agent-python-sdk

The distribution is named pi-agent-python-sdk; import it as pi_agent.

from pi_agent import PiClient

with PiClient() as pi:
    result = pi.run("Explain the current project without changing files.")
    print(result.text)

The context manager starts and closes Pi. run() waits for the conversation to settle. The result includes finalized messages, session identity, elapsed time, and observed assistant usage.

Continue the conversation with another call on the same client:

from pi_agent import PiClient

with PiClient() as pi:
    print(pi.run("Explain this project's entry points without editing files.").text)
    print(pi.run("Which of those entry points handles configuration?").text)

Pi keeps the conversation context. Each result contains only the messages and answer from that call; a call with no assistant output has empty text.

Streaming

from pi_agent import PiClient

with PiClient() as pi:
    with pi.stream("Explain this project's entry points without editing files.") as stream:
        for event in stream:
            if event.text_delta is not None:
                print(event.text_delta, end="", flush=True)
        result = stream.result()
    print(f"\nStop reason: {result.stop_reason}")

Async usage

Use AsyncPiClient in applications that already run an event loop. Command arguments and results match the synchronous client.

import asyncio

from pi_agent import AsyncPiClient


async def main() -> None:
    async with AsyncPiClient() as pi:
        result = await pi.run("Explain the current project without changing files.")
        print(result.text)


if __name__ == "__main__":
    asyncio.run(main())

Configuration

Choose the project directory and whether to save the conversation:

from pi_agent import PiClient

with PiClient(cwd=".", no_session=True) as pi:
    print(pi.run("Describe this project without changing files.").text)

Leave no_session unset to preserve Pi's normal session persistence. Use session= to open an existing session. For model overrides, see Models and thinking.

Models and thinking

By default the SDK uses whatever model you already configured in the Pi CLI. Override it when you construct the client, or switch later on the same client. Set the model and thinking level before run() or stream().

Select a model at construction:

from pi_agent import PiClient

with PiClient(provider="openai", model="gpt-5") as pi:
    print(pi.run("Summarise this repo without changing files.").text)

Thinking levels depend on the current model. Query them, set one, then confirm what Pi actually applied:

from pi_agent import PiClient

with PiClient() as pi:
    levels = pi.get_available_thinking_levels()
    print("available:", levels)
    if "high" in levels:
        pi.set_thinking_level("high")
    print("effective:", pi.get_state()["thinkingLevel"])
    print(pi.run("Analyse this project's architecture without changing files.").text)

Replace the example provider/model ids with ones from your Pi install (pi --list-models or get_available_models()).

from pi_agent import PiClient

with PiClient() as pi:
    for model in pi.get_available_models():
        print(model["provider"], model["id"])
    selected = pi.set_model("openai", "gpt-5")
    print("using", selected["provider"], selected["id"])
    print(pi.run("Summarise this repo without changing files.").text)

RPC access

The SDK speaks Pi's existing JSONL protocol over stdin/stdout:

Your Python application
    PiClient / AsyncPiClient
        pi --mode rpc
            Models · tools · extensions · sessions

Inspect session state without starting a model run:

from pi_agent import PiClient

with PiClient() as pi:
    state = pi.get_state()
    print(state["sessionId"])

Documentation

Examples use your configured Pi and may make provider calls. Development checks use an isolated local test provider; see CONTRIBUTING.md for setup and validation commands.

Troubleshooting

Support

• Open an issue for bugs, questions, or compatibility reports.
• See CONTRIBUTING.md for local setup and pull requests.
• For security reports, open a private security advisory.

License

MIT