Configuration

An Agent is configured like any other Cloudflare Workers project, and uses a wrangler configuration file to define where your code is and what services (bindings) it will use.

The typical file structure for an Agent project created from npm create cloudflare@latest agents-starter -- --template cloudflare/agents-starter follows:

.
|-- package-lock.json
|-- package.json
|-- public
|   `-- index.html
|-- src
|   `-- index.ts // your Agent definition
|-- test
|   |-- index.spec.ts // your tests
|   `-- tsconfig.json
|-- tsconfig.json
|-- vitest.config.mts
|-- worker-configuration.d.ts
`-- wrangler.jsonc // your Workers & Agent configuration

Below is a minimal wrangler.jsonc file that defines the configuration for an Agent, including the entry point, durable_object namespace, and code migrations:

wrangler.jsonc

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "agents-example",
  "main": "src/index.ts",
  "compatibility_date": "2025-02-23",
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [
      {
        // Required:
        "name": "MyAgent", // How your Agent is called from your Worker
        "class_name": "MyAgent", // Must match the class name of the Agent in your code
        // Optional: set this if the Agent is defined in another Worker script
        "script_name": "the-other-worker"
      },
    ],
  },
  "migrations": [
    {
      "tag": "v1",
      // Mandatory for the Agent to store state
      "new_sqlite_classes": ["MyAgent"],
    },
  ],
  "observability": {
    "enabled": true,
  },
}

wrangler.toml

"$schema" = "node_modules/wrangler/config-schema.json"
name = "agents-example"
main = "src/index.ts"
compatibility_date = "2025-02-23"
compatibility_flags = [ "nodejs_compat" ]

[[durable_objects.bindings]]
name = "MyAgent"
class_name = "MyAgent"
script_name = "the-other-worker"

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

[observability]
enabled = true

The configuration includes:

• A main field that points to the entry point of your Agent, which is typically a TypeScript (or JavaScript) file.
• A durable_objects field that defines the Durable Object namespace that your Agents will run within.
• A migrations field that defines the code migrations that your Agent will use. This field is mandatory and must contain at least one migration. The new_sqlite_classes field is mandatory for the Agent to store state.