Skip to content

Pi AI

Last updated View as MarkdownAgent setup

To call AI Gateway from Pi AI ↗︎, use createAI from agents/models/pi-ai. It calls models from the model catalog, dynamic routes, and Pi AI's own model objects through your gateway. This page covers the AI Gateway features. For the full reference, refer to Pi AI.

Installation

Install the Agents SDK and Pi AI. createAI needs @earendil-works/pi-ai@~1.3.0:

npm i agents @earendil-works/pi-ai

In a Worker, add the AI binding to your Wrangler configuration:

{
	"ai": {
		"binding": "AI",
	},
}
[ai]
binding = "AI"

Call a catalog model

Pass a <provider>/<id> from Pi AI's AI Gateway catalog. You do not need a vendor key. AI Gateway bills the request through Unified Billing, or uses a key stored on the gateway:

import { createAI } from "agents/models/pi-ai";

export default {
	async fetch(request, env) {
		const ai = createAI({ binding: env.AI, id: "my-gateway" });

		const reply = await ai.complete(ai("anthropic/claude-opus-5.5"), {
			messages: [
				{ role: "user", content: "Write a short story", timestamp: Date.now() },
			],
		});

		return Response.json(reply.content);
	},
};
import { createAI } from "agents/models/pi-ai";

export default {
	async fetch(request: Request, env: Env) {
		const ai = createAI({ binding: env.AI, id: "my-gateway" });

		const reply = await ai.complete(ai("anthropic/claude-opus-5.5"), {
			messages: [
				{ role: "user", content: "Write a short story", timestamp: Date.now() },
			],
		});

		return Response.json(reply.content);
	},
};

Use the catalog's spelling of the id, such as anthropic/claude-opus-5.5 or openai/gpt-5.5. The request goes in the model's own format, Anthropic Messages or OpenAI Responses, so Pi AI's own parsers read the answer and thinking works as it does with the vendor. id sets the gateway and defaults to default. A dynamic route on that gateway is dynamic/<route>, for example ai("dynamic/support").

Call a Pi AI model object

Pass any model from a Pi AI registry. The request goes to the vendor's provider-native endpoint on your gateway, and AI Gateway supplies the credential:

import { getBuiltinModel } from "@earendil-works/pi-ai/providers/all";
import { createAI } from "agents/models/pi-ai";

const ai = createAI({ binding: env.AI, id: "my-gateway" });

const model = ai(getBuiltinModel("anthropic", "claude-opus-5-5"));

A model object keeps the vendor's own id, such as claude-opus-5-5, and all of Pi AI's metadata for it.

Fall back to another model

fallback lists models to try in order if the primary model fails before it produces any output. Mix catalog ids, dynamic routes, Workers AI ids, and model objects:

const model = ai("anthropic/claude-opus-5.5", {
	fallback: ["openai/gpt-5.5", "@cf/zai-org/glm-4.7-flash"],
});

Set gateway options

Set caching, logging, metadata, timeouts, and retries on createAI, on a model, or per call:

const ai = createAI({
	binding: env.AI,
	id: "my-gateway",
	cacheTtl: 60,
	metadata: { app: "support-bot" },
});

const model = ai("openai/gpt-5.5", { byokAlias: "production" });

For every option, refer to Cache, tag, and time out requests.

Use an account id and API token

To use a gateway in another account, or to call from outside a Worker, pass accountId and apiToken instead of binding:

const ai = createAI({
	accountId: "<ACCOUNT_ID>",
	apiToken: env.CLOUDFLARE_API_TOKEN,
	gateway: "my-gateway",
});

Create an API token with the Workers AI Read permission for model ids and AI Gateway Run for model objects.

Was this helpful?