Pi Coding Agent SDK (gateway)

Build agents on pi ’s harness and send their model calls through the Respan gateway. Add Respan as a provider in a models.json, then pick its models when you create a session.

Trace pi agents

This page covers gateway routing. To also capture runs, tool calls, and threads from inside the agent, see Pi Coding Agent SDK (tracing).

Paste this into your coding agent:


Help me set up the Respan gateway with the Pi Coding Agent SDK.
Follow https://www.respan.ai/docs/integrations/gateway/pi-sdk.md

Setup

Install the SDK

Terminal


npm install @earendil-works/pi-coding-agent
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

Add Respan as a provider

Create models.json in your project:

JSON


{
  "providers": {
    "respan": {
      "baseUrl": "https://gateway.respan.ai",
      "api": "openai-completions",
      "apiKey": "$RESPAN_API_KEY",
      "models": [{ "id": "gpt-5.5" }, { "id": "claude-sonnet-4-5" }]
    }
  }
}

Create a session

TypeScript


import { createAgentSession, ModelRuntime } from "@earendil-works/pi-coding-agent";

const modelRuntime = await ModelRuntime.create({ modelsPath: "./models.json" });
const model = modelRuntime.getModel("respan", "gpt-5.5");

const { session } = await createAgentSession({ model, modelRuntime });
await session.prompt("Say hello in one sentence.");
session.dispose();

Switch models

Add any ID from respan.ai/models to models, then select it with modelRuntime.getModel("respan", "<id>").