Cloudflare Release Notes

The Agents SDK now provides first-class support for building agents using the Pi harness.

You can build long-running agents using the combination of Pi 1.0 ↗︎, Pi Durable ↗︎, and the new PiHarness class that the Cloudflare Agents SDK provides, ensuring your agent's work is durably persisted, even if interrupted mid-turn.

Built with Earendil ↗︎, this integration is our first step toward first-class support for third-party agent harnesses on Cloudflare.

Copy promptPrompt copied!

Beta

PiHarness is in beta. Pi Durable ↗︎ is a new, experimental package, and the PiHarness API will likely change as Pi Durable matures.

PiHarness is a new "Lifecycle capability" provided by the Cloudflare Agents SDK. Pi Durable provides the agent harness and the Lifecycle is responsible for keeping the agent running in the Durable Object. The Lifecycle is a core concept in the Agents SDK ensuring that long-running work can run in a Durable Object, surviving restarts, crashes, and network issues. We will share more on Lifecycle capabilities in the near future.

Install

npmyarnpnpmbun

npm i agents@latest @earendil-works/pi-durable @earendil-works/pi-ai
yarn add agents@latest @earendil-works/pi-durable @earendil-works/pi-ai
pnpm add agents@latest @earendil-works/pi-durable @earendil-works/pi-ai
bun add agents@latest @earendil-works/pi-durable @earendil-works/pi-ai

Both Pi packages are optional peer dependencies of agents, so you only install them if you use the harness.

Use it in an Agent

Creating a Pi agent requires configuring the Pi Harness with a model, skills, and tools, then registering the PiHarness with the Agent class.

import { Agent } from "agents";
import { createModels } from "@earendil-works/pi-ai/models";
import { createRegistry, Harness } from "@earendil-works/pi-durable";
import { PiHarness } from "agents/harness/pi";
import { createAI } from "agents/models/pi-ai";

export class Assistant extends Agent {
ai = createAI({ binding: this.env.AI });
registry = createRegistry();
harness = new PiHarness({
harness: ({ storage, context }) => {
const models = createModels();
models.setProvider(this.ai.provider);
return Harness.open(
storage,
{ models, registry: this.registry },
context,
);
},
defaults: { model: this.ai("@cf/moonshotai/kimi-k2.7-code") },
});
constructor(ctx, env) {
super(ctx, env);
this.lifecycle.use(this.harness);
}
async ask(prompt) {
const { text } = await this.harness.prompt(prompt);
return text;
}
}

import { Agent } from "agents";
import { createModels } from "@earendil-works/pi-ai/models";
import { createRegistry, Harness } from "@earendil-works/pi-durable";
import { PiHarness } from "agents/harness/pi";
import { createAI } from "agents/models/pi-ai";

export class Assistant extends Agent<Env> {
ai = createAI({ binding: this.env.AI });
registry = createRegistry();
harness = new PiHarness({
harness: ({ storage, context }) => {
const models = createModels();
models.setProvider(this.ai.provider);
return Harness.open(
storage,
{ models, registry: this.registry },
context,
);
},
defaults: { model: this.ai("@cf/moonshotai/kimi-k2.7-code") },
});
constructor(ctx: DurableObjectState, env: Env) {
super(ctx, env);
this.lifecycle.use(this.harness);
}
async ask(prompt: string) {
const { text } = await this.harness.prompt(prompt);
return text;
}
}

The agents/models/pi-ai entry point supports AI Gateway and Workers AI models, so you can get started with Cloudflare models right away or use your existing pi-ai provider.

Add tools with extensions

Both tools and system prompt sections are provided to the Pi Harness via extensions.

import { Type } from "@earendil-works/pi-ai";
import { skills } from "agents/harness/pi";

const WordCount = Type.Object({ text: Type.String() });

const wordCount = {
name: "word_count",
description: "Count the words in a text.",
parameters: WordCount,
replay: "safe",
async execute({ text }) {
const words = text.split(/\s+/).filter(Boolean).length;
return { content: [{ type: "text", text: String(words) }] };
},
};

// In the harness factory, before Harness.open():
registry.install({
name: "editor",
sections: [
{ key: "preamble", render: () => "You are an editor.", tag: false },
],
tools: [wordCount],
});
registry.install(await skills(sources));

import { Type } from "@earendil-works/pi-ai";
import type { ToolRegistration } from "@earendil-works/pi-durable";
import { skills } from "agents/harness/pi";

const WordCount = Type.Object({ text: Type.String() });

const wordCount: ToolRegistration<typeof WordCount> = {
name: "word_count",
description: "Count the words in a text.",
parameters: WordCount,
replay: "safe",
async execute({ text }) {
const words = text.split(/\s+/).filter(Boolean).length;
return { content: [{ type: "text", text: String(words) }] };
},
};

// In the harness factory, before Harness.open():
registry.install({
name: "editor",
sections: [
{ key: "preamble", render: () => "You are an editor.", tag: false },
],
tools: [wordCount],
});
registry.install(await skills(sources));

For more information on creating and configuring extensions, refer to Extensions.

Learn more

Pi harness documentation

Pi harness extensions

pi-ai model provider

Pi harness example ↗︎, with WebSockets, a browser UI, and a @cloudflare/computer Workspace for the model's tools

Lifecycle ↗︎

Pi Durable announcement ↗︎ from Earendil

The strict service token authentication setting applies consistent behavior to requests made with service tokens. When the setting is on for a Zero Trust organization, Access handles requests with service token headers as follows:

• If authentication or authorization fails, Access always returns 401 or 403 instead of redirecting the client to the login page with 302.
• Only Service Auth policies can authorize the request. Access ignores Allow policies and any CF_Authorization cookie sent with the request.
• Access does not return a CF_Authorization cookie to the client after successful authentication. Subsequent requests should continue to use service token headers.
• Failed requests for recognized service tokens appear in Access authentication logs.
• Zero Trust organizations created on or after October 5, 2026 have strict service token authentication turned on by default and cannot turn it off. Cloudflare recommends that existing organizations turn it on as well.
• Organizations created before October 5, 2026 can configure the setting in the dashboard or through the API.

In the Cloudflare dashboard ↗︎, go to Zero Trust > Access controls > Access settings.

Go to Access settings ↗

Under Manage service tokens, turn on Strict service token authentication.

In the confirmation dialog, select Enable.

To turn off strict service token authentication, turn off the setting and select Disable.

curl "https://api.cloudflare.com/client/v4/accounts/%7Baccount_id%7D/access/organizations" \
--request PATCH \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"strict_service_token_auth": true
}'

To turn off strict service token authentication, set strict_service_token_auth to false.

For behavior and configuration details, refer to Strict service token authentication.

Jurisdictions for Workers KV namespaces are now generally available. When you create a namespace, you can set a jurisdiction to make sure the namespace's data is only durably stored within that region. Jurisdictions can help you comply with data localization regulations such as GDPR or FedRAMP. Supported jurisdictions are eu, us, and fedramp.

A jurisdiction can only be set when a namespace is created, using the Cloudflare dashboard, Wrangler, the cf CLI, or the REST API, and cannot be added or changed afterwards.

npx wrangler@latest kv namespace create <NAMESPACE_NAME> --jurisdiction=eu
cf kv namespaces create --title <NAMESPACE_NAME> --jurisdiction eu
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/storage/kv/namespaces" \ --request POST \ --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{
"title": "<NAMESPACE_NAME>",
"jurisdiction": "eu"
}'

Workers can still access a namespace restricted to a jurisdiction from anywhere in the world, and KV data can be cached outside the jurisdiction on Cloudflare's network. The jurisdiction only controls where the namespace's data is durably stored.

To learn more, refer to Data location.

Web Search API

Web Search API is now available in beta. Web Search API lets your AI agents and applications search the Internet and ground their responses in live information, instead of guessing URLs or relying on a model's training cutoff.

At launch, you can choose between three search providers: Ceramic.ai, Exa, and Linkup. All three support Zero Data Retention for requests made through Cloudflare, and all have committed to Cloudflare's verified bot crawling standards.

Web Search API runs through AI Gateway, so search requests appear in your gateway logs and are billed to your AI Gateway credits at each provider's list API price, with no additional markup. You can also bring your own provider API key.

Call Web Search API with the REST API:

curl https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/websearch/ \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"query": "What are some fun things to do in Salt Lake City as fall approaches?",
"provider": "ceramic",
"limit": 5,
"options": { "gateway": { "id": "default" } }
}'

Or from a Worker with the AI binding:

const response = await env.AI.websearch({
gatewayId: "default",
query: "What are some fun things to do in Salt Lake City as fall approaches?",
provider: "exa",
limit: 5,
});
const results = await response.json();

To get started, refer to How to use Web Search API.

Minor Changes

• #15928 7f57b1c Thanks @ichernetsky-cf! - Allow "us" as a jurisdiction for Container applications

Container placement constraints now accept constraints.jurisdiction: "us" in Wrangler and typed Cloudflare configuration. This makes the US jurisdiction available alongside "eu" and "fedramp".

Patch Changes

• #15974 7f700ef Thanks @martinezjandrew! - Fix wrangler containers list to report live instances

The LIVE INSTANCES column now reports each application's active runtime instances instead of its configured instance count, matching the Cloudflare dashboard. JSON output continues to expose the configured count through the existing instances field.

• #15980 90e6a1b Thanks @martinezjandrew! - Accept Durable Object application IDs in Containers commands

wrangler containers instances and wrangler containers delete now accept the 32-character hexadecimal application IDs returned for Durable Object-backed applications, in addition to legacy dashed UUIDs.

• #15871 6a4b0fe Thanks @tw4! - Retry transient API failures in wrangler workflows instances list and wrangler workflows instances describe

Previously, a single temporary 5xx response or dropped connection made these read-only commands exit with an error, even though the next request would have succeeded. They now use Wrangler's existing bounded API retry handling. The read that resolves --id latest is retried too, which also benefits the other wrangler workflows instances commands that accept latest; the mutating requests they make afterwards are not retried. Persistent failures are still reported after the retries are exhausted, and under --json any retry notices are written to stderr so stdout stays valid JSON.

Updated dependencies []:

• [email protected]