导航|地址|刷新
Use an OpenAPI service with Code Mode

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt
Use this file to discover all available pages before exploring further.



DocsDirectoryAPISDKsChangelog

Search

Log in






Agents

/




Overview


Getting started


Quick start

Add to existing project

Testing your Agents






Concepts


What are agents?

Conversation state and memory

Tools

Calling LLMs

Using Agents with Workflows


Agentic patterns


Overview

Human-in-the-loop patterns

Long-running agents










Communication channels



Chat


Chat agents

Autonomous responses

Client SDK





Voice

Email

Slack


Webhooks


Overview

Push notifications










Tools


Sandbox

MCP

Browser

AI Search


Agentic Payments


Overview

Charge for HTTP content


x402


Overview

Charge for HTTP content

Charge for MCP tools

Pay from Agents SDK

Pay from coding tools





MPP (Machine Payments Protocol)






Code Mode


Overview

Create a durable Code Mode runtime

AI SDK integration

Use Code Mode with TanStack AI

Browser-owned tools

MCP

OpenAPI

How Code Mode works

Code Mode API reference










Harnesses


Overview


Think


Overview

Getting started

Configuration

Tools

Actions

Lifecycle hooks

Client tools

Messengers

Channels

Scheduled tasks

Workflows

Sub-agent RPC and programmatic turns

Programmatic submissions

Durable recovery










Runtime


Agents API


Lifecycle


Agent class internals

Callable methods

Store and sync state

Sessions

getCurrentAgent()






Communication


Routing

WebSockets

HTTP and Server-Sent Events

Chat SDK

Protocol messages

Readonly connections






Execution


Sub-agents

Schedule tasks

Durable execution with fibers

Queue tasks

Retries

Run Workflows

Agents as tools

Agent Skills






Operations


Configuration

Cross-domain authentication

Using AI Models

Observability










Examples


Chat agent

Slack agent

Voice agent

Browser agent

Email agent






Model Context Protocol (MCP)


Overview


APIs


MCP handler APIs

McpAgent

McpClient






Protocol


Tools

Authorization

Transport

MCP governance






Guides


Build MCP client

Build a Remote MCP server

Test a Remote MCP Server

Securing MCP servers

Connect to an MCP server

Handle OAuth with MCP servers

Migrate to MCP SDK v2

Build a single-tool Code Mode MCP server

Build a search and execute MCP server






Cloudflare


MCP server portals ↗


Cloudflare's own MCP servers


Overview

Cloudflare Community MCP Server









Code Mode MCP server patterns






Platform


Limits






Agent resources


Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Agents llms.txt ↗

Agents llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗













Home

/Agents

/…
Tools


/Code Mode

/OpenAPI



Use an OpenAPI service with Code Mode


Last updated Jun 24, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewPrerequisitesCreate an OpenAPI connectorDerived method behaviorRequest escape hatch




Use OpenApiConnector to expose an OpenAPI service inside a durable Code Mode runtime. The connector derives one sandbox method for each operation in the OpenAPI document.

The model can discover methods with codemode.search() and request focused input types with codemode.describe(). The complete OpenAPI document does not need to enter the model context.

This page covers an Agent consuming an OpenAPI service. To publish an OpenAPI service to external MCP clients through search and execute, refer to Build a search and execute MCP server.


Prerequisites


You need a project with the durable Code Mode runtime configured. The runtime setup provides the Worker Loader binding and the CodemodeRuntime export used in this guide.


Create an OpenAPI connector




Add the OpenAPI document to your project. Give each operation a unique operationId so it produces a stable sandbox method name:






src/orders-openapi.jsjsexport const ordersOpenApiSpec = { openapi: "3.1.0", info: { title: "Orders API", version: "1.0.0" }, paths: { "/orders/{orderId}": { get: { operationId: "get_order", summary: "Get an order by ID.", parameters: [ { name: "orderId", in: "path", required: true, schema: { type: "string" }, }, ], }, }, "/orders": { post: { operationId: "create_order", summary: "Create an order.", requestBody: { required: true, content: { "application/json": { schema: { type: "object", properties: { productId: { type: "string" }, quantity: { type: "integer" }, }, required: ["productId", "quantity"], }, }, }, }, }, }, },};

src/orders-openapi.tstsexport const ordersOpenApiSpec = { openapi: "3.1.0", info: { title: "Orders API", version: "1.0.0" }, paths: { "/orders/{orderId}": { get: { operationId: "get_order", summary: "Get an order by ID.", parameters: [ { name: "orderId", in: "path", required: true, schema: { type: "string" }, }, ], }, }, "/orders": { post: { operationId: "create_order", summary: "Create an order.", requestBody: { required: true, content: { "application/json": { schema: { type: "object", properties: { productId: { type: "string" }, quantity: { type: "integer" }, }, required: ["productId", "quantity"], }, }, }, }, }, }, },} as const;






Create the connector. Implement spec() to return the document and request() to make authenticated host-side requests:






src/orders-connector.jsjsimport { OpenApiConnector } from "@cloudflare/codemode";import { ordersOpenApiSpec } from "./orders-openapi";const API_ORIGIN = "https://api.example.com";export class OrdersConnector extends OpenApiConnector { name() { return "orders"; } instructions() { return "Use for reading and creating orders."; } spec() { return ordersOpenApiSpec; } async request(options) { if (!options.path.startsWith("/")) { throw new Error("Orders API path must start with a slash"); } const url = new URL(options.path, API_ORIGIN); for (const [key, value] of Object.entries(options.params ?? {})) { if (value !== undefined) { url.searchParams.set(key, String(value)); } } const response = await fetch(url, { method: options.method ?? "GET", headers: { ...(options.body !== undefined ? { "Content-Type": "application/json" } : {}), ...options.headers, Authorization: `Bearer ${this.env.ORDERS_API_TOKEN}`, }, body: options.body === undefined ? undefined : JSON.stringify(options.body), }); if (!response.ok) { throw new Error(`Orders API request failed: ${response.status}`); } if (response.status === 204) return null; return response.json(); } tool(name, tool) { if (name === "create_order") { return { ...tool, requiresApproval: true }; } return tool; }}

src/orders-connector.tstsimport { OpenApiConnector, type ConnectorTool, type OpenApiRequestOptions,} from "@cloudflare/codemode";import { ordersOpenApiSpec } from "./orders-openapi";const API_ORIGIN = "https://api.example.com";export class OrdersConnector extends OpenApiConnector<Env> { override name() { return "orders"; } protected override instructions() { return "Use for reading and creating orders."; } protected override spec() { return ordersOpenApiSpec; } protected override async request(options: OpenApiRequestOptions) { if (!options.path.startsWith("/")) { throw new Error("Orders API path must start with a slash"); } const url = new URL(options.path, API_ORIGIN); for (const [key, value] of Object.entries(options.params ?? {})) { if (value !== undefined) { url.searchParams.set(key, String(value)); } } const response = await fetch(url, { method: options.method ?? "GET", headers: { ...(options.body !== undefined ? { "Content-Type": "application/json" } : {}), ...options.headers, Authorization: `Bearer ${this.env.ORDERS_API_TOKEN}`, }, body: options.body === undefined ? undefined : JSON.stringify(options.body), }); if (!response.ok) { throw new Error(`Orders API request failed: ${response.status}`); } if (response.status === 204) return null; return response.json(); } protected override tool(name: string, tool: ConnectorTool): ConnectorTool { if (name === "create_order") { return { ...tool, requiresApproval: true }; } return tool; }}




Credentials remain in the host Worker. Model-written code receives connector methods and their results, not ORDERS_API_TOKEN.

The tool() hook decorates derived operations. This example requires approval before create_order executes. You can also use the hook to add replay or rollback behavior.



Import the connector and add it to the runtime:






src/server.jsjsimport { AIChatAgent } from "@cloudflare/ai-chat";import { createCodemodeRuntime, DynamicWorkerExecutor,} from "@cloudflare/codemode";import { OrdersConnector } from "./orders-connector";export class Chat extends AIChatAgent { #runtime() { return createCodemodeRuntime({ ctx: this.ctx, executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }), connectors: [new OrdersConnector(this.ctx, this.env)], }); } async onChatMessage() { const tools = { codemode: this.#runtime().tool() }; // Pass tools to your model call. }}

src/server.tstsimport { AIChatAgent } from "@cloudflare/ai-chat";import { createCodemodeRuntime, DynamicWorkerExecutor,} from "@cloudflare/codemode";import { OrdersConnector } from "./orders-connector";export class Chat extends AIChatAgent<Env> { #runtime() { return createCodemodeRuntime({ ctx: this.ctx, executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }), connectors: [new OrdersConnector(this.ctx, this.env)], }); } async onChatMessage() { const tools = { codemode: this.#runtime().tool() }; // Pass tools to your model call. }}






Let the model discover the operations and call the generated connector methods:
async () => { const matches = await codemode.search("get an order by ID"); const docs = await codemode.describe(matches.results[0].path); const order = await orders.get_order({ orderId: "order-123" }); return { docs, order };};



Derived method behavior


OpenApiConnector uses a sanitized operationId as the method name. If an operation has no operationId, it derives a name from the HTTP method and path. Define unique operation IDs to keep method names stable and avoid collisions.

Each generated method accepts one object:

Path, query, and header parameters appear as top-level fields.

A JSON request body appears under body.

Required OpenAPI parameters become required TypeScript fields.

Local $ref values in input schemas are resolved before types are generated.

The connector substitutes path parameters and passes a normalized { path, method, params, body, headers } object to request().

The current connector derives input types but does not derive response types from OpenAPI response schemas. Generated methods therefore return unknown unless your application provides more specific declarations through another connector implementation.


Request escape hatch


Every OpenAPI connector also exposes a low-level request() sandbox method. Use it when the OpenAPI document does not describe an operation the model needs:
const result = await orders.request({ path: "/orders", method: "GET", params: { status: "processing" },});
Prefer derived operation methods when available. They provide discoverable descriptions and generated input types.

exposeSpec() returns false by default. Override it to return true only when model-written code needs access to the raw OpenAPI document. Large documents can produce large results and durable log entries.


PreviousMCPNextHow Code Mode works


Was this helpful?

YesNo

Edit pageReport issue




On this page

Overview

Prerequisites

Create an OpenAPI connector

Derived method behavior

Request escape hatch


Edit pageReport issue














Getting started
PlansContact salesPartnersFind a partnerStartupsUnder attack?Domain name search


Company
AboutCareersInvestorsPressPress kitGlobal network




Public interest
Project GalileoAthenian ProjectCloudflare for CampaignsProject FairshotImpact/ESG


Compliance
Compliance resourcesTrust HubData ProtectionResponsible AITransparency reportReport abuse




Resources
App innovation reportCloudflare RadarCase studiesStatusSupportEventsBlog


Developers
DocumentationLearning centerCommunity




Solutions
SSE and SASE platformCloudflare AI CloudAI SecurityFrontend Development PlatformMulti-Tenant Platform DevelopmentWeb Security Platform


Start BuildingLog In












© 2026 Cloudflare, Inc.

Privacy policy|Report security issues|Terms of use|Trademark
|
Your privacy choices








Docs




------
导航页 打开网址