# @standardagents/cloudflare

Cloudflare Workers AI provider package for Standard Agents using the OpenAI-compatible Chat Completions API

> **Info:**
>
> For direct access, set `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID` in your environment. A model can instead configure `providerOptions.baseUrl`. Standard Agents Builder can use hosted routing through `STANDARD_AGENTS_API_KEY` when the provider token is absent. Hosted access depends on platform configuration.

## Overview

The `@standardagents/cloudflare` package provides a Cloudflare Workers AI provider factory for Standard Agents. It targets Cloudflare's OpenAI-compatible Chat Completions endpoint and adds typed `providerOptions`, model discovery via Cloudflare's models API, and request inspection support in the admin UI.

- Key Features

  - Direct integration with Cloudflare's account-scoped `/ai/v1/chat/completions` endpoint
  - Typed `providerOptions` for Workers AI request parameters
  - Remote model discovery with search and pagination for `@cf/...` chat models in the builder UI
  - Tool calling, structured outputs, streaming, and multimodal model support where documented

## Installation

```bash npm
npm install @standardagents/cloudflare
```

```bash pnpm
pnpm add @standardagents/cloudflare
```

```bash yarn
yarn add @standardagents/cloudflare
```

## Quick Start

```typescript agents/models/workers_fast.ts
import { defineModel } from '@standardagents/spec';
import { cloudflare } from '@standardagents/cloudflare';

export default defineModel({
  name: 'workers-fast',
  provider: cloudflare,
  model: '@cf/google/gemma-4-26b-a4b-it',
  // Prices change. Check https://developers.cloudflare.com/workers-ai/platform/pricing/
  inputPrice: 0.1,
  outputPrice: 0.3,
});
```

## Provider Factory

```typescript
import { cloudflare } from '@standardagents/cloudflare';

defineModel({
  name: 'workers-reasoning',
  provider: cloudflare,
  model: '@cf/openai/gpt-oss-120b',
});
```

## Provider Options

```typescript
import { defineModel } from '@standardagents/spec';
import { cloudflare } from '@standardagents/cloudflare';

export default defineModel({
  name: 'workers-reasoning',
  provider: cloudflare,
  model: '@cf/openai/gpt-oss-120b',
  providerOptions: {
    seed: 42,
    user: 'user-123',
    logprobs: true,
    top_logprobs: 5,
  },
});
```

### Available Options

| Option              | Type      | Description                                      |
| ------------------- | --------- | ------------------------------------------------ |
| `baseUrl`           | `string`  | Override the default OpenAI-compatible base URL  |
| `seed`              | `number`  | Best-effort deterministic sampling seed          |
| `user`              | `string`  | End-user identifier                              |
| `logprobs`          | `boolean` | Return token log probabilities                   |
| `top_logprobs`      | `number`  | Number of top logprobs to return                 |
| `frequency_penalty` | `number`  | Frequency penalty forwarded to the chat endpoint |
| `presence_penalty`  | `number`  | Presence penalty forwarded to the chat endpoint  |

> **Note:**
>
> By default, the provider builds the base URL from `CLOUDFLARE_ACCOUNT_ID`. Set `providerOptions.baseUrl` if you want to route through a different OpenAI-compatible endpoint such as AI Gateway.

## Model IDs

Workers AI model IDs are sent directly, for example:

- `@cf/meta/llama-3.1-8b-instruct`
- `@cf/meta/llama-4-scout-17b-16e-instruct`
- `@cf/openai/gpt-oss-120b`
- `@cf/qwen/qwen3-30b-a3b-fp8`
- `@cf/zhipu-ai/glm-4.7-flash`

The builder fetches available models from Cloudflare's account-scoped models API, so the model picker can search and paginate through the live Workers AI catalog. The provider keeps a small static fallback catalog for capability hints and as a fallback if the models API is unavailable.

## Capabilities

The provider exposes model capabilities for the bundled Workers AI fallback catalog, including:

- `supportsImages` for multimodal models like Llama 3.2 Vision and Llama 4 Scout
- `supportsToolCalls` for models Cloudflare documents with function calling
- `supportsJsonMode` and `supportsStreaming` for the OpenAI-compatible chat API
- `reasoningLevels` for reasoning-focused models like `@cf/openai/gpt-oss-120b`

## Environment Setup

```bash .dev.vars
CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_ACCOUNT_ID=...
```

For a deployed project, set `CLOUDFLARE_API_TOKEN` in your project's environment settings on the Standard Agents platform.

Set `CLOUDFLARE_ACCOUNT_ID` in the same place.

## Notes

- The provider uses Cloudflare's OpenAI-compatible `/chat/completions` API.
- Authentication uses a Cloudflare API token, not a traditional provider-specific API key.
- The current package focuses on text-generation/chat-completions models, not embeddings or image generation.

## Related

- [Models](/docs/core-concepts/models)

  Core model concepts

* [Cerebras Provider](/docs/providers/cerebras)

  Compare with Cerebras

- [OpenRouter Provider](/docs/providers/openrouter)

  Compare with OpenRouter