← Vytvářejte agenty na Cloudflare / agents / tools / codemode

integrace AI SDK

@cloudflare/codemode/ai vstupní bod převádí nástroje AI SDK na jeden nástroj Code Mode. Model píše JavaScript, který volá vaše nástroje, a exekutor tento kód spouští v izolovaném sandboxu.

Zvolte mezi dvěma vzory integrace:

Vzor	Případ použití	Chování schvalování
`createCodeTool()`	Jednoduché, bezstavové spouštění s jedním nebo více poskytovateli nástrojů	Vylučuje nástroje, které používají `needsApproval`
`ToolSetConnector` nebo `toolSetConnector()`	Trvalé provádění prostřednictvím runtime Code Mode	Mapuje `needsApproval` na trvalé schválení runtime

Vytvořte bezstavový nástroj Code Mode

createCodeTool() přijímá AI SDK ToolSet nebo pole poskytovatelů nástrojů. Vyžaduje také executor. Vrací standardní nástroj AI SDK pro použití s streamText() nebo generateText().

Nainstalujte Code Mode, AI SDK a Zod:
npm i @cloudflare/codemode agents ai zod

Přidejte vazbu Worker Loader pro DynamicWorkerExecutor:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  // Set this to today's date
  "compatibility_date": "2026-08-28",
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "worker_loaders": [
    {
      "binding": "LOADER"
    }
  ]
}

# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = ["nodejs_compat"]

[[worker_loaders]]
binding = "LOADER"

Definujte spustitelné nástroje AI SDK. Code Mode použije jejich schémata k vygenerování typů a ověření argumentů před voláním execute.

src/tools.js

import { tool } from "ai";
import { z } from "zod";

export const weatherTools = {
	getWeather: tool({
		description: "Get the weather for a city",
		inputSchema: z.object({
			city: z.string().describe("City name"),
		}),
		outputSchema: z.object({
			city: z.string(),
			conditions: z.string(),
		}),
		execute: async ({ city }) => ({
			city,
			conditions: "sunny",
		}),
	}),
};

src/tools.ts

import { tool } from "ai";
import { z } from "zod";

export const weatherTools = {
  getWeather: tool({
    description: "Get the weather for a city",
    inputSchema: z.object({
      city: z.string().describe("City name")
    }),
    outputSchema: z.object({
      city: z.string(),
      conditions: z.string()
    }),
    execute: async ({ city }) => ({
      city,
      conditions: "sunny"
    })
  })
};

Každý nástroj volatelný ze sandboxu potřebuje execute funkci. Nástroje na straně klienta nebo spouštěné poskytovatelem nemohou běžet přes tento exekutor na straně serveru.

Vytvořte nástroj Code Mode a předejte ho do volání modelu AI SDK:

src/index.js

import { DynamicWorkerExecutor } from "@cloudflare/codemode";
import { createCodeTool } from "@cloudflare/codemode/ai";
import { generateText, stepCountIs } from "ai";
import { model } from "./model";
import { weatherTools } from "./tools";

export default {
	async fetch(request, env) {
		const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
		const codemode = createCodeTool({ tools: weatherTools, executor });

		const response = await generateText({
			model,
			prompt: await request.text(),
			tools: { codemode },
			stopWhen: stepCountIs(5),
		});

		return new Response(response.text);
	},
};

src/index.ts

import { DynamicWorkerExecutor } from "@cloudflare/codemode";
import { createCodeTool } from "@cloudflare/codemode/ai";
import { generateText, stepCountIs } from "ai";
import { model } from "./model";
import { weatherTools } from "./tools";

export default {
 	async fetch(request, env): Promise<Response> {
 		const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
 		const codemode = createCodeTool({ tools: weatherTools, executor });

 		const response = await generateText({
 			model,
 			prompt: await request.text(),
 			tools: { codemode },
 			stopWhen: stepCountIs(5),
 		});

 		return new Response(response.text);
 	},
} satisfies ExportedHandler<Env>;

Příklad používá generateText() pro dokončenou odpověď. Můžete předat stejný codemode nástroj na streamText() pro streamování. Vygenerovaný popis nástroje obsahuje definice TypeScript pro getWeather. Model přesto píše JavaScript, například:

async () => {
	const weather = await codemode.getWeather({ city: "Lisbon" });
	return weather.conditions;
};

Výchozí jmenný prostor je codemode. createCodeTool() také přijímá vlastní description. Zahrňte {{types}} v tomto popisu, kam má Code Mode vložit vygenerované definice.

Organizujte nástroje pomocí poskytovatelů

Poskytovatel nástrojů seskupuje nástroje pod jeden sandboxový jmenný prostor. Sadu nástrojů předejte přímo, pokud každý nástroj patří pod codemode.*.

Použijte aiTools() při kombinování nástrojů AI SDK s poskytovateli z jiných balíčků. Následující volitelný příklad pracovního prostoru také vyžaduje @cloudflare/shell:

npm i @cloudflare/shell

import { AIChatAgent } from "@cloudflare/ai-chat";
import { DynamicWorkerExecutor } from "@cloudflare/codemode";
import { aiTools, createCodeTool } from "@cloudflare/codemode/ai";
import { Workspace } from "@cloudflare/shell";
import { stateTools } from "@cloudflare/shell/workers";
import { weatherTools } from "./tools";

export class Chat extends AIChatAgent {
	workspace = new Workspace({ sql: this.ctx.storage.sql });

	codemodeTool() {
		return createCodeTool({
			tools: [aiTools(weatherTools), stateTools(this.workspace)],
			executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
		});
	}
}

import { AIChatAgent } from "@cloudflare/ai-chat";
import { DynamicWorkerExecutor } from "@cloudflare/codemode";
import { aiTools, createCodeTool } from "@cloudflare/codemode/ai";
import { Workspace } from "@cloudflare/shell";
import { stateTools } from "@cloudflare/shell/workers";
import { weatherTools } from "./tools";

export class Chat extends AIChatAgent<Env> {
	workspace = new Workspace({ sql: this.ctx.storage.sql });

	codemodeTool() {
		return createCodeTool({
			tools: [aiTools(weatherTools), stateTools(this.workspace)],
			executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
		});
	}
}

Tento příklad zpřístupňuje nástroje AI SDK jako codemode.* a nástroje pracovního prostoru jako state.*.

Chcete-li přiřadit vlastní jmenné prostory, místo toho předejte objekty poskytovatele:

const executor = new DynamicWorkerExecutor({ loader: env.LOADER });

const codemode = createCodeTool({
	tools: [
		{ name: "weather", tools: weatherTools },
		{ name: "notifications", tools: notificationTools },
	],
	executor,
});

const executor = new DynamicWorkerExecutor({ loader: env.LOADER });

const codemode = createCodeTool({
	tools: [
		{ name: "weather", tools: weatherTools },
		{ name: "notifications", tools: notificationTools },
	],
	executor,
});

Vygenerovaný kód pak může zavolat weather.getWeather() a notifications.send(). Názvy poskytovatelů musí být jedinečné platné identifikátory JavaScriptu.

Použití nástrojů AI SDK s trvalým runtime

Použijte ToolSetConnector nebo jeho toolSetConnector() pomocná funkce pro případy, kdy běhy potřebují trvalý stav. Konektor přizpůsobuje AI SDK ToolSet pro createCodemodeRuntime(). Pomocná funkce vrací new ToolSetConnector(ctx, options).

Vytvořte konektor uvnitř Agenta nebo jiného Durable Object:

src/server.js

import { AIChatAgent } from "@cloudflare/ai-chat";
import {
	createCodemodeRuntime,
	DynamicWorkerExecutor,
} from "@cloudflare/codemode";
import { toolSetConnector } from "@cloudflare/codemode/ai";
import { convertToModelMessages, streamText } from "ai";
import { model } from "./model";
import { operationTools } from "./tools";

// Export this manually when the @cloudflare/codemode/vite plugin is not configured.
export { CodemodeRuntime } from "@cloudflare/codemode";

export class OperationsAgent extends AIChatAgent {
	async onChatMessage() {
		const operations = toolSetConnector(this.ctx, {
			name: "operations",
			instructions: "Use these tools to manage customer requests.",
			tools: operationTools,
		});

		const runtime = createCodemodeRuntime({
			ctx: this.ctx,
			executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
			connectors: [operations],
		});

		const result = streamText({
			model,
			messages: await convertToModelMessages(this.messages),
			tools: { codemode: runtime.tool() },
		});

		return result.toUIMessageStreamResponse();
	}
}

src/server.ts

import { AIChatAgent } from "@cloudflare/ai-chat";
import {
	createCodemodeRuntime,
	DynamicWorkerExecutor,
} from "@cloudflare/codemode";
import { toolSetConnector } from "@cloudflare/codemode/ai";
import { convertToModelMessages, streamText } from "ai";
import { model } from "./model";
import { operationTools } from "./tools";

// Export this manually when the @cloudflare/codemode/vite plugin is not configured.
export { CodemodeRuntime } from "@cloudflare/codemode";

export class OperationsAgent extends AIChatAgent<Env> {
	async onChatMessage() {
		const operations = toolSetConnector(this.ctx, {
			name: "operations",
			instructions: "Use these tools to manage customer requests.",
			tools: operationTools,
		});

		const runtime = createCodemodeRuntime({
			ctx: this.ctx,
			executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
			connectors: [operations],
		});

		const result = streamText({
			model,
			messages: await convertToModelMessages(this.messages),
			tools: { codemode: runtime.tool() },
		});

		return result.toUIMessageStreamResponse();
	}
}

Příklad exportuje CodemodeRuntime ručně. Pokud nakonfigurujete plugin Code Mode Vite podle popisu v Vytvořte trvalý runtime Code Mode, odstraňte tento ruční export, protože ho přidává plugin.

Konektor ve výchozím nastavení používá tools namespace, když name je vynechán. Vylučuje nástroje bez execute funkci jak z generovaných typů, tak z vazeb sandboxu.

Trvalý runtime přidává deník běhů, chování pro pozastavení a obnovení a zjišťování konektorů na vyžádání. Model dokáže najít metody pomocí codemode.search() a zkontrolovat jejich typy pomocí codemode.describe().

Chování schvalování

Oba integrační vzory zpracovávají schválení AI SDK odlišně.

`createCodeTool()` schválení

createCodeTool() odfiltruje nástroje, u kterých needsApproval je true nebo funkci. Filtrované nástroje se neobjeví ve vygenerovaných typech a nelze je spustit z kódu v sandboxu. Nástroj s needsApproval: false zůstává dostupný.

Tato bezstavová cesta nepozastavuje běh kvůli schvalování v AI SDK. Pokud nástroj vyžaduje schvalovací proces AI SDK, použijte mimo Code Mode standardní nástroj AI SDK.

`ToolSetConnector` schválení

ToolSetConnector mapuje AI SDK needsApproval do durable runtime requiresApproval anotace. Volání tohoto nástroje pozastaví běh. Vaše aplikace může zkontrolovat čekající akce a pokračovat ve stejném běhu pomocí runtime.approve({ executionId }).

Funkční hodnota needsApproval nelze vyhodnotit dříve, než sandbox dodá argumenty. Konektor proto tento nástroj považuje za vždy vyžadující schválení. needsApproval: false se provede bez pozastavení.

Toto schválení využívá trvalý tok pozastavení, schválení a přehrávání v rámci runtime Code Mode. Nevyužívá tok schválení AI SDK po jednotlivých voláních.