← Vytvářejte agenty na Cloudflare / agents / runtime / operations

Konfigurace

Tento návod pokrývá vše, co potřebujete pro konfiguraci agentů pro lokální vývoj a nasazení do produkce, včetně nastavení konfiguračního souboru Wrangler, generování typů, proměnných prostředí a dashboardu Cloudflare.

Struktura projektu

Typická struktura souborů projektu Agent vytvořeného z npm create cloudflare@latest agents-starter -- --template cloudflare/agents-starter následuje:

src/
- index.ts definice vašeho Agenta
public/
- index.html
test/
- index.spec.ts vaše testy
package.json
tsconfig.json
vitest.config.mts
worker-configuration.d.ts
wrangler.jsonc, konfigurace vašich Workers a Agent

Konfigurační soubor Wrangler

wrangler.jsonc soubor konfiguruje váš Cloudflare Worker a jeho vazby. Zde je kompletní příklad pro projekt agentů:

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "my-agent-app",
	"main": "src/server.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"compatibility_flags": ["nodejs_compat"],

	// Static assets (optional)
	"assets": {
		"directory": "public",
		"binding": "ASSETS",
	},

	// Durable Object bindings for agents
	"durable_objects": {
		"bindings": [
			{
				"name": "MyAgent",
				"class_name": "MyAgent",
			},
			{
				"name": "ChatAgent",
				"class_name": "ChatAgent",
			},
		],
	},

  // Provision storage for each agent class
	"exports": {
		"MyAgent": {
			"type": "durable-object",
			"storage": "sqlite",
		},
		"ChatAgent": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},

	// AI binding (optional, for Workers AI)
	"ai": {
		"binding": "AI",
	},

	// Observability (recommended)
	"observability": {
		"enabled": true,
	},
}

"$schema" = "node_modules/wrangler/config-schema.json"
name = "my-agent-app"
main = "src/server.ts"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "nodejs_compat" ]

[assets]
directory = "public"
binding = "ASSETS"

[[durable_objects.bindings]]
name = "MyAgent"
class_name = "MyAgent"

[[durable_objects.bindings]]
name = "ChatAgent"
class_name = "ChatAgent"

[exports.MyAgent]
type = "durable-object"
storage = "sqlite"

[exports.ChatAgent]
type = "durable-object"
storage = "sqlite"

[ai]
binding = "AI"

[observability]
enabled = true

Klíčová pole

`compatibility_flags`

nodejs_compat příznak je pro agenty povinný:

{
	"compatibility_flags": ["nodejs_compat"],
}

compatibility_flags = [ "nodejs_compat" ]

Tím se zapne režim kompatibility s Node.js, na kterém agenti závisí kvůli crypto, streamům a dalším API Node.js.

`durable_objects.bindings`

Každá třída agenta potřebuje vazbu:

{
	"durable_objects": {
		"bindings": [
			{
				"name": "Counter",
				"class_name": "Counter",
			},
		],
	},
}

[[durable_objects.bindings]]
name = "Counter"
class_name = "Counter"

Pole	Popis
`name`	Název vlastnosti na `env`. V kódu použijte toto: `env.Counter`
`class_name`	Musí přesně odpovídat názvu exportované třídy

Když se `name` a `class_name` liší

Když name a class_name liší, postupujte podle vzoru uvedeného níže:

{
	"durable_objects": {
		"bindings": [
			{
				"name": "COUNTER_DO",
				"class_name": "CounterAgent",
			},
		],
	},
}

[[durable_objects.bindings]]
name = "COUNTER_DO"
class_name = "CounterAgent"

Toto se hodí, když chcete pojmenování ve stylu proměnných prostředí (COUNTER_DO) ale s výstižnějšími názvy tříd (CounterAgent).

`exports`

exports pole deklaruje každou třídu Agent, kterou váš Worker exportuje, a úložný backend, který pro ni má Cloudflare použít:

{
	"exports": {
		"MyAgent": {
			"type": "durable-object",
			"storage": "sqlite",
		},
	},
}

[exports.MyAgent]
type = "durable-object"
storage = "sqlite"

Pole	Popis
`type`	Druh exportu. Vždy `"durable-object"` pro Agenta.
`storage`	Úložný backend. Použijte `"sqlite"` pro nové Agenty (doporučeno).

Podrobnosti o přejmenování, mazání nebo přenosu tříd Agent najdete v Exporty tříd Durable Object. Existující Workers používající legacy migrations pole nadále fungují, podrobnosti najdete v Migrace tříd Durable Object (zastaralé).

`assets`

Pro poskytování statických souborů (HTML, CSS, JS):

{
	"assets": {
		"directory": "public",
		"binding": "ASSETS",
	},
}

[assets]
directory = "public"
binding = "ASSETS"

S vazbou můžete assety obsluhovat programově:

export default {
	async fetch(request, env) {
		// Static assets are served by the worker automatically by default

		// Route the request to the appropriate agent
		const agentResponse = await routeAgentRequest(request, env);
		if (agentResponse) return agentResponse;

		// Add your own routing logic here
		return new Response("Not found", { status: 404 });
	},
};

export default {
	async fetch(request: Request, env: Env) {
		// Static assets are served by the worker automatically by default

		// Route the request to the appropriate agent
		const agentResponse = await routeAgentRequest(request, env);
		if (agentResponse) return agentResponse;

		// Add your own routing logic here
		return new Response("Not found", { status: 404 });
	},
} satisfies ExportedHandler<Env>;

`ai`

Pro integraci s Workers AI:

{
	"ai": {
		"binding": "AI",
	},
}

[ai]
binding = "AI"

Přístup ve vašem agentovi:

const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
	prompt: "Hello!",
});

const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
	prompt: "Hello!",
});

Konfigurace TypeScript

Agents SDK dodává sdílený tsconfig.json která nastavuje všechny možnosti kompilátoru potřebné pro projekty agentů, včetně ES2021 cíl vyžadovaný pro @callable() dekorátory, strict mode, rozlišování modulů bundleru a typy Workers.

Rozšiřte ji ve svém tsconfig.json:

{
	"extends": "agents/tsconfig"
}

To odpovídá:

{
	"compilerOptions": {
		"target": "ES2021",
		"lib": ["ES2022", "DOM", "DOM.Iterable"],
		"jsx": "react-jsx",
		"module": "ES2022",
		"moduleResolution": "bundler",
		"types": ["node", "@cloudflare/workers-types", "vite/client"],
		"allowImportingTsExtensions": true,
		"noEmit": true,
		"isolatedModules": true,
		"verbatimModuleSyntax": true,
		"esModuleInterop": true,
		"forceConsistentCasingInFileNames": true,
		"strict": true,
		"skipLibCheck": true
	}
}

Jednotlivé možnosti můžete podle potřeby přepsat:

{
	"extends": "agents/tsconfig",
	"compilerOptions": {
		"jsx": "preserve"
	}
}

Konfigurace Vite

Agents SDK poskytuje plugin pro Vite, který se stará o transformace dekorátorů TC39. Vite 8 používá pro transpilaci Oxc, jenž zatím dekorátory TC39 nepodporuje: bez tohoto pluginu @callable() a další dekorátory selžou za běhu.

Přidejte plugin do svého vite.config.ts:

import { cloudflare } from "@cloudflare/vite-plugin";
import react from "@vitejs/plugin-react";
import agents from "agents/vite";
import { defineConfig } from "vite";

export default defineConfig({
	plugins: [agents(), react(), cloudflare()],
});

vite.config.ts

import { cloudflare } from "@cloudflare/vite-plugin";
import react from "@vitejs/plugin-react";
import agents from "agents/vite";
import { defineConfig } from "vite";

export default defineConfig({
	plugins: [agents(), react(), cloudflare()],
});

agents() plugin je bezpečné zahrnout, i když váš projekt dekorátory nepoužívá. Transformaci spouští pouze na souborech, které obsahují @ syntaxe.

Startovní šablona a všechny příklady tento plugin ve výchozím nastavení obsahují. Pokud narazíte na SyntaxError: Invalid or unexpected token s dekorátory, viz Volatelné metody | Řešení potíží.

Generování typů

Wrangler dokáže vygenerovat typy TypeScript pro vaše bindings.

Automatické generování

Spusťte příkaz types:

npx wrangler types

Tím se vytvoří nebo aktualizuje worker-configuration.d.ts s vaším Env typ.

Vlastní výstupní cesta

Zadejte vlastní cestu:

npx wrangler types env.d.ts

Bez runtime typů

Pro čistší výstup (doporučeno pro agenty):

npx wrangler types env.d.ts --include-runtime false

Tím se vygenerují jen vaše bindings, bez typů Cloudflare runtime.

Příklad vygenerovaného výstupu

// env.d.ts (generated)
declare namespace Cloudflare {
	interface Env {
		OPENAI_API_KEY: string;
		Counter: DurableObjectNamespace;
		ChatAgent: DurableObjectNamespace;
	}
}
interface Env extends Cloudflare.Env {}

Ruční definice typu

Typy můžete také definovat ručně:

// env.d.ts

// env.d.ts
import type { Counter } from "./src/agents/counter";
import type { ChatAgent } from "./src/agents/chat";

interface Env {
	// Secrets
	OPENAI_API_KEY: string;
	WEBHOOK_SECRET: string;

	// Agent bindings
	Counter: DurableObjectNamespace<Counter>;
	ChatAgent: DurableObjectNamespace<ChatAgent>;

	// Other bindings
	AI: Ai;
	ASSETS: Fetcher;
	MY_KV: KVNamespace;
}

Přidání do package.json

Přidejte skript pro snadnou regeneraci:

{
	"scripts": {
		"types": "wrangler types env.d.ts --include-runtime false"
	}
}

Proměnné prostředí a secrets

Lokální vývoj (`.env`)

Vytvořte .env soubor pro lokální secrets (přidejte do .gitignore):

# .env
OPENAI_API_KEY=sk-...
GITHUB_WEBHOOK_SECRET=whsec_...
DATABASE_URL=postgres://...

Přístup ve vašem agentovi:

class MyAgent extends Agent {
	async onStart() {
		const apiKey = this.env.OPENAI_API_KEY;
	}
}

class MyAgent extends Agent {
	async onStart() {
		const apiKey = this.env.OPENAI_API_KEY;
	}
}

Produkční tajné klíče

Použijte wrangler secret pro produkci:

# Add a secret
npx wrangler secret put OPENAI_API_KEY
# Enter value when prompted

# List secrets
npx wrangler secret list

# Delete a secret
npx wrangler secret delete OPENAI_API_KEY

Netajné proměnné

Pro necitlivou konfiguraci použijte vars v konfiguračním souboru Wrangler:

{
	"vars": {
		"API_BASE_URL": "https://api.example.com",
		"MAX_RETRIES": "3",
		"DEBUG_MODE": "false",
	},
}

[vars]
API_BASE_URL = "https://api.example.com"
MAX_RETRIES = "3"
DEBUG_MODE = "false"

Všechny hodnoty musí být řetězce. Čísla a booleovské hodnoty parsujte v kódu:

const maxRetries = parseInt(this.env.MAX_RETRIES, 10);
const debugMode = this.env.DEBUG_MODE === "true";

const maxRetries = parseInt(this.env.MAX_RETRIES, 10);
const debugMode = this.env.DEBUG_MODE === "true";

Proměnné specifické pro prostředí

Použijte env sekce pro různá prostředí (například staging, produkce):

{
	"name": "my-agent",
	"vars": {
		"API_URL": "https://api.example.com",
	},

	"env": {
		"staging": {
			"vars": {
				"API_URL": "https://staging-api.example.com",
			},
		},
		"production": {
			"vars": {
				"API_URL": "https://api.example.com",
			},
		},
	},
}

name = "my-agent"

[vars]
API_URL = "https://api.example.com"

[env.staging.vars]
API_URL = "https://staging-api.example.com"

[env.production.vars]
API_URL = "https://api.example.com"

Nasaďte do konkrétního prostředí:

npx wrangler deploy --env staging
npx wrangler deploy --env production

Lokální vývoj

Spuštění vývojového serveru

S Vite (doporučeno pro fullstack aplikace):

npx vite dev

Bez Vite:

npx wrangler dev

Perzistence lokálního stavu

Stav Durable Object se ukládá lokálně v .wrangler/state/:

.wrangler/
- state/
  - v3/
    - d1/
      - miniflare-D1DatabaseObject/
        
        ... (soubory SQLite)

Mazání lokálního stavu

Chcete-li resetovat veškerý lokální stav Durable Object:

rm -rf .wrangler/state

Nebo restartujte s čistým stavem:

npx wrangler dev --persist-to=""

Prohlížení lokální SQLite databáze

Stav agenta můžete zkontrolovat přímo:

# Find the SQLite file
ls .wrangler/state/v3/d1/

# Open with sqlite3
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite

Nastavení dashboardu

Automatické prostředky

Při nasazení Cloudflare automaticky vytvoří:

Worker - Váš nasazený kód
Jmenné prostory Durable Object - Jeden na třídu agenta
Úložiště SQLite - Připojeno ke každému jmennému prostoru

Zobrazování Durable Objects

Přihlaste se do Cloudflare dashboardu a poté přejděte na Durable Objects.

Přejděte na Durable Objects ↗

Zde můžete:

Zobrazit všechny jmenné prostory Durable Object
Zobrazit jednotlivé instance objektů
Prohlížení úložiště (klíče a hodnoty)
Odstranění objektů

Logy v reálném čase

Zobrazte živé protokoly svých agentů:

npx wrangler tail

Nebo v dashboardu:

Přejděte na svůj Worker.
Vyberte Observabilita kartě.
Povolte logy v reálném čase.

Filtrovat podle:

Stav (úspěch, chyba)
Hledaný text
Vzorkovací frekvence

Nasazení do produkce

Základní nasazení

npx wrangler deploy

Toto:

Sbalí váš kód
Nahrávání do Cloudflare
Zajišťuje úložiště jmenného prostoru Durable Object daného Agenta
Zpřístupní ho na *.workers.dev

Vlastní doména

Přidejte trasu do konfiguračního souboru Wrangler:

{
	"routes": [
		{
			"pattern": "agents.example.com/*",
			"zone_name": "example.com",
		},
	],
}

[[routes]]
pattern = "agents.example.com/*"
zone_name = "example.com"

Nebo použijte vlastní doménu (jednodušší):

{
	"routes": [
		{
			"pattern": "agents.example.com",
			"custom_domain": true,
		},
	],
}

[[routes]]
pattern = "agents.example.com"
custom_domain = true

Náhledová nasazení

Nasaďte bez ovlivnění produkčního prostředí:

npx wrangler deploy --dry-run    # See what would be uploaded
npx wrangler versions upload     # Upload new version
npx wrangler versions deploy     # Gradually roll out

Vrácení zpět

Vraťte se k předchozí verzi:

npx wrangler rollback

Nastavení pro více prostředí

Konfigurace prostředí

Definujte prostředí v konfiguračním souboru Wrangler:

{
	"name": "my-agent",
	"main": "src/server.ts",

	// Base configuration (shared)
	// Set this to today's date
	"compatibility_date": "2026-08-28",
	"compatibility_flags": ["nodejs_compat"],
	"durable_objects": {
		"bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
	},
	"exports": {
		"MyAgent": { "type": "durable-object", "storage": "sqlite" },
	},

	// Environment overrides
	"env": {
		"staging": {
			"name": "my-agent-staging",
			"durable_objects": {
				"bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
			},
			"vars": {
				"ENVIRONMENT": "staging",
			},
		},
		"production": {
			"name": "my-agent-production",
			"durable_objects": {
				"bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
			},
			"vars": {
				"ENVIRONMENT": "production",
			},
		},
	},
}

name = "my-agent"
main = "src/server.ts"
# Set this to today's date
compatibility_date = "2026-08-28"
compatibility_flags = [ "nodejs_compat" ]

[[durable_objects.bindings]]
name = "MyAgent"
class_name = "MyAgent"

[exports.MyAgent]
type = "durable-object"
storage = "sqlite"

[env.staging]
name = "my-agent-staging"

[[env.staging.durable_objects.bindings]]
name = "MyAgent"
class_name = "MyAgent"

  [env.staging.vars]
  ENVIRONMENT = "staging"

[env.production]
name = "my-agent-production"

[[env.production.durable_objects.bindings]]
name = "MyAgent"
class_name = "MyAgent"

  [env.production.vars]
  ENVIRONMENT = "production"

Nasazování do prostředí

# Deploy to staging
npx wrangler deploy --env staging

# Deploy to production
npx wrangler deploy --env production

# Set secrets per environment
npx wrangler secret put OPENAI_API_KEY --env staging
npx wrangler secret put OPENAI_API_KEY --env production

Samostatné Durable Objects

Pojmenovaná prostředí nedědí vazby Durable Object. Vazby zopakujte pro každé prostředí, jako v nastavení pro více prostředí. Každé prostředí má vlastní Durable Objects. Staging agenti nesdílejí stav s produkčními agenty.

Chcete-li výslovně oddělit:

{
	"env": {
		"staging": {
			"durable_objects": {
				"bindings": [
					{
						"name": "MyAgent",
						"class_name": "MyAgent",
						"script_name": "my-agent-staging",
					},
				],
			},
		},
	},
}

[[env.staging.durable_objects.bindings]]
name = "MyAgent"
class_name = "MyAgent"
script_name = "my-agent-staging"

Životní cyklus třídy Agent

Každý Agent se mapuje na třídu Durable Object. Životní cyklus těchto tříd (vytváření, přejmenování, mazání, přenos) spravujete pomocí exports pole ve vašem konfiguračním souboru Wrangler.

Přidání nového agenta

Deklarujte novou třídu v exports:

{
	"exports": {
		"NewAgent": { "type": "durable-object", "storage": "sqlite" },
	},
}

[exports.NewAgent]
type = "durable-object"
storage = "sqlite"

Přejmenování třídy agenta

Nahraďte položku pro staré jméno za renamed tombstone a přidat aktivní záznam pro nový název:

{
	"exports": {
		"OldName": {
			"type": "durable-object",
			"state": "renamed",
			"renamed_to": "NewName",
		},
		"NewName": { "type": "durable-object", "storage": "sqlite" },
	},
}

[exports.OldName]
type = "durable-object"
state = "renamed"
renamed_to = "NewName"

[exports.NewName]
type = "durable-object"
storage = "sqlite"

Aktualizujte také:

Název třídy v kódu.
class_name ve vazbách.
Příkazy export.

Odstranění třídy agenta

Nahraďte položku za deleted tombstone:

{
	"exports": {
		"AgentToKeep": { "type": "durable-object", "storage": "sqlite" },
		"AgentToDelete": { "type": "durable-object", "state": "deleted" },
	},
}

[exports.AgentToKeep]
type = "durable-object"
storage = "sqlite"

[exports.AgentToDelete]
type = "durable-object"
state = "deleted"

Osvědčené postupy pro životní cyklus třídy

Zachovejte exports v souladu s vaším kódem. Každá třída Agent, kterou váš Worker exportuje, potřebuje vlastní položku.
Používejte tombstony, ne tiché odstranění. Při rušení třídy ponechte deleted / renamed / transferred tombstone v exports aby Cloudflare tuto změnu výslovně sladil.
Nejprve otestujte lokálně. Změny životního cyklu se projeví při wrangler deploy.
Zálohujte produkční data před přejmenováním nebo smazáním.

Stávající Workers používající starší migrations pole nadále fungují, podrobnosti najdete v Migrace tříd Durable Object (zastaralé) pro starší referenci, nebo Migrovat ze staršího migrations tok k přesunutí do exports.

Řešení potíží

No such Durable Object class

Třída chybí v exports. Deklarujte třídu a její úložiště:

{
	"exports": {
		"MissingClassName": { "type": "durable-object", "storage": "sqlite" },
	},
}

[exports.MissingClassName]
type = "durable-object"
storage = "sqlite"

Modul nelze najít v typech

Znovu vygenerujte typy:

npx wrangler types env.d.ts --include-runtime false

Tajné klíče se lokálně nenačítají

Zkontrolujte, že .env existuje a obsahuje proměnnou:

cat .env
# Should show: MY_SECRET=value

Konflikt migračního tagu (starší `migrations` pouze)

Pokud váš Worker používá starší migrations pole musí mít každá položka jedinečný tag:

{
	// Wrong - duplicate tags
	"migrations": [
		{ "tag": "v1", "new_sqlite_classes": ["A"] },
		{ "tag": "v1", "new_sqlite_classes": ["B"] },
	],
}

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "A" ]

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "B" ]

{
	// Correct - sequential tags
	"migrations": [
		{ "tag": "v1", "new_sqlite_classes": ["A"] },
		{ "tag": "v2", "new_sqlite_classes": ["B"] },
	],
}

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "A" ]

[[migrations]]
tag = "v2"
new_sqlite_classes = [ "B" ]

Zvažte převod na deklarativní exports .