Skip to main content

Pi

Since v1.109.0

Harness.PI runs the Pi coding agent in your sandbox. Use the same litellm.agent() API for model routing, events, file changes, token usage and cost.

Install and run​

Install the SDK dependencies on the host and the Pi CLI where the agent runs. For a local sandbox, run both commands on your machine.

pip install -U litellm starlette uvicorn
npm install -g @earendil-works/pi-coding-agent
pi --version

The pi binary must be on the sandbox's PATH. For sandbox.docker(), install it in the container image. A missing binary raises HarnessInstallFailed.

Set LITELLM_PROXY_API_BASE to your gateway's base URL and LITELLM_PROXY_API_KEY to a virtual key. The example uses a gateway model group named coder; replace it with a group your key can access that supports Chat Completions and tool calling.

export LITELLM_PROXY_API_BASE=https://litellm.example.com
export LITELLM_PROXY_API_KEY=sk-your-virtual-key
mkdir -p pi-workspace
run_pi.py
from pathlib import Path

import litellm
from litellm import Harness, sandbox

result = litellm.agent(
Harness.PI,
"Create hello.txt containing exactly hello from Pi.",
sandbox=sandbox.local("./pi-workspace"),
model="litellm_proxy/coder",
permissions="edit",
)

print(result.text)
print(result.usage)
print(result.cost)
assert result.stop_reason == "done"
assert Path("pi-workspace/hello.txt").read_text().strip() == "hello from Pi"

Run python run_pi.py. The assertion verifies the file the agent created. result.files reports the workspace changes. A local sandbox runs with your user's filesystem access; use a Docker sandbox when you need container isolation.

Shared agent APIs​

Pass stream=True to receive typed events, or use await litellm.aagent(...) for an async result. For multi-turn tasks, use agent_session() and session.run(). Pi also supports detach() and agent_resume() on a saved State. The Pi session cache must remain available in the sandbox environment; serialized state does not contain the full native session history.

Use output=YourPydanticModel for validated structured output. Pi receives instructions to return JSON, and LiteLLM validates the response. Invalid output raises OutputInvalid. Pass skills=["./skills/review"] to load a directory containing SKILL.md.

The session guide, event reference and structured output guide use the same API with Harness.PI. For evaluations, pass EvalTarget(Harness.PI, model="litellm_proxy/coder") to the evaluation API, subject to that API's SDK version requirements.

Permissions and tools​

ModePi built-in tools
read-onlyread, grep, find, ls
editRead-only tools plus edit, write
full (default)Edit tools plus bash

Use disable_tools=("bash", "write") to remove tools from the selected mode. Normalized event names match the shared tool names, including find as glob and powershell as bash.

Custom Python tools=, session.history() and permissions="ask" are unsupported and raise CapabilityUnsupported. For Python functions or interactive tool approval, use Tool Loop or compare the capability table.

Pi options​

from litellm import PiOptions

options = PiOptions(
thinking="medium",
config={"compaction": {"enabled": True}},
)

Pass this object as options= on your agent or session call.

FieldUse
thinkingoff, minimal, low, medium, high, xhigh or max; the selected model must support the requested level
configExtra Pi settings; mcpServers configures native Pi MCP servers
envExtra environment variables for the Pi process

LiteLLM manages model selection, provider credentials, permission tools, skills and session paths. Settings that override these controls or load packages and extensions are rejected. Use the matching agent() argument instead. Pi runs with private configuration and does not load your personal Pi setup or project-local extensions.

Configured MCP servers remain available in every permission mode. Their tools can have effects beyond reading files, so use disable_tools= to filter them when needed. MCP configuration belongs in PiOptions.config["mcpServers"], rather than Python tools=.

Routing and accounting​

Pi sends streamed requests to /v1/chat/completions. With model="litellm_proxy/<group>", LiteLLM forwards them to the gateway with the harness,pi tags and your metadata. Your gateway key stays on the host; Pi receives a session-scoped token.

Usage and cost come from the model responses. A self-hosted group must return stream usage for complete token accounting. For SDK routing without a gateway, see Models and routing.

LiteLLM Enterprise
SSO/SAML, audit logs, spend tracking, multi-team management, and guardrails, built for production.
Learn more →