Cloudflare
Use Cloudflare AI Gateway models with Agno agents.
Cloudflare AI Gateway exposes an OpenAI-compatible unified API, so you reach multiple vendors through a single endpoint by setting the model ID to a vendor/model route. The default vendor is Workers AI, which needs only a Cloudflare token and account ID.
The Cloudflare class defaults to @cf/meta/llama-3.3-70b-instruct-fp8-fast. Agno rewrites any @cf/... ID to workers-ai/@cf/... for the gateway.
Agno's adapter builds the /compat endpoint. Cloudflare deprecates it for single-model calls, while continuing to support existing integrations and requiring it for Dynamic Routes. The examples here document that compatibility endpoint and its route syntax.
Authentication
Cloudflare needs an API token and your account ID. The AI Gateway ID is optional and falls back to default.
| Variable | Required | Description |
|---|---|---|
CLOUDFLARE_API_TOKEN | Yes | API token. Create one at dash.cloudflare.com. |
CLOUDFLARE_ACCOUNT_ID | Yes | Your account ID, found in the Cloudflare dashboard. |
CLOUDFLARE_AI_GATEWAY_ID | No | AI Gateway ID. Defaults to default. |
export CLOUDFLARE_API_TOKEN="your_value_here"
export CLOUDFLARE_ACCOUNT_ID="your_value_here"
export CLOUDFLARE_AI_GATEWAY_ID="your_value_here" # optionalExample
Install the openai package, which Cloudflare uses as its client:
uv pip install -U agno openaiUse Cloudflare with your Agent:
from agno.agent import Agent
from agno.models.cloudflare import Cloudflare
agent = Agent(
model=Cloudflare(id="@cf/meta/llama-3.3-70b-instruct-fp8-fast"),
markdown=True,
)
# Print the response in the terminal
agent.print_response("Share a 2 sentence horror story.")Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
id | str | "@cf/meta/llama-3.3-70b-instruct-fp8-fast" | The gateway model ID. See Model selection. |
name | str | "Cloudflare" | The name of the model |
provider | str | "Cloudflare" | The provider of the model |
api_key | Optional[str] | None | API token (defaults to CLOUDFLARE_API_TOKEN env var) |
account_id | Optional[str] | None | Account ID (defaults to CLOUDFLARE_ACCOUNT_ID env var) |
gateway_id | Optional[str] | None | AI Gateway ID (defaults to CLOUDFLARE_AI_GATEWAY_ID, or default) |
base_url | Optional[str] | None | Override the gateway URL. When set, account_id and gateway_id are not used. |
max_tokens | Optional[int] | None | Maximum tokens to generate |
Cloudflare extends the OpenAI-compatible interface and supports most parameters from the OpenAI model. For structured output on models without native support, set use_json_mode=True on the Agent.
Model selection
Pick the route by setting id:
| Vendor | ID format | Notes |
|---|---|---|
| Workers AI | @cf/<org>/<model> | Copy the binding ID from the model catalog. Agno prepends workers-ai/. |
| OpenAI, Google, etc | openai/<model>, google/<model> | Requires the vendor's BYOK key stored in the AI Gateway dashboard. |
| Dynamic route | dynamic/<route> | A route configured in the dashboard for fallbacks. |
from agno.agent import Agent
from agno.models.cloudflare import Cloudflare
# Workers AI (Agno rewrites to workers-ai/@cf/...)
agent = Agent(model=Cloudflare(id="@cf/google/gemma-4-26b-a4b-it"), markdown=True)Workers AI serves Google's open-weight Gemma models, not the standard Gemini API. Invented IDs such as @cf/.../gemini-... return HTTP 400. For Gemini, use a google/... route with BYOK credentials. Vendor routes also need a model ID from the Cloudflare docs.