Pi SDK harness
Run supported provider models with the managed Pi SDK harness in Orca Agent Engine.
The pi_sdk harness runs the Pi SDK agent loop with a model from its pinned provider catalog. It supports Cloud separate and colocated execution and self-hosted colocated execution. This is a different harness from the older pi CLI identifier.
colocated mode is not fully implemented in this release. Use separate, the default.
Get your registry endpoint
Registry endpoint
Examples on this page target your registry endpoint - the deployment host root, with no path
suffix. For CLI, set ORCA_REGISTRY_URL and exactly one of ORCA_ACCESS_TOKEN (Bearer) or
ORCA_API_KEY (x-api-key). For TypeScript SDK, set ORCA_BASE_URL / ORCA_API_KEY (Bearer).
To find the endpoint, see Connect to the registry.
Select this harness
Set metadata.harness and choose a provider and model. This example uses a model in Pi's pinned Anthropic catalog:
ork agent create \
--name "support-triage" \
--model-json '{"provider":"anthropic","id":"claude-sonnet-4-6"}' \
--metadata harness=pi_sdkOmitting mode selects separate. Set metadata.mode to colocated on the agent to run the worker inside the sandbox. A self-hosted environment requires colocated.
After configuring the Python SDK, pass the provider and model as an object:
from orca import Orca
client = Orca()
agent = client.agents.create(
name="support-triage",
model={"provider": "anthropic", "id": "claude-sonnet-4-6"},
metadata={"harness": "pi_sdk"},
)The images embedded in ork local CLI v0.5.0 reject pi_sdk at agent creation. Follow the local tutorial to select the published Agent Engine v0.5.1 Registry and Harness images. Agent creation and request guardrail denial were verified with the v0.5.0 images, and v0.5.1 changes neither path; model replies require the selected provider's key or Gateway route.
Models and provider setup
If the deployment exposes the runtime.runorca.ai/v1 group in GET /apis, GET /apis/runtime.runorca.ai/v1/harnesses lists Pi's supported providers, models, effort levels, and modes. The pinned Pi catalog includes models using OpenAI Responses, Chat Completions, Anthropic Messages, and Gemini GenerateContent. A supported model is usable only when the deployment also configures its provider credential, exact model and route grants, and pricing where cost budgets apply. Pi SDK accepts explicit static API keys; OAuth and ambient cloud credentials are not supported.
Cloud separate mode can use a configured provider key on the harness host or session-scoped Gateway egress. Cloud colocated mode uses a scoped Gateway token. Pi's Gateway route uses the provider's native protocol, so operators must configure the corresponding Pi provider route and use a Gateway build that includes the native proxy support. The standard legacy Claude, OpenAI, and DeepSeek routes do not configure Pi routes. The provider key stays outside a Cloud colocated sandbox.
Capabilities and limits
Pi SDK tools are mediated by the session's managed tool policies. The harness supports managed skills, remote MCP tools, client custom-tool callbacks, interruption, and native conversation recovery across worker restarts. The SDK reports the model usage used for accounting.
The harness does not support multiagent rosters. Request budgets are checked between turns; they do not stop spending partway through a model turn. Soft budget approvals and stateful tool-phase guardrails are unsupported. In separate mode, the harness enforces stateless request, tool_call, and tool_result guardrails, and stateful guardrails at request only. colocated mode does not fully support guardrails yet. A rule the harness cannot enforce stops the session from starting; see Guardrail enforcement.