> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare Agents integration

> Connect Cloudflare Agents to Orq.ai's AI Gateway for routing across providers, and export Workers traces and logs to Orq.ai over OpenTelemetry.

<CardGroup cols={2}>
  <Card title="AI Gateway" icon="arrow-right-arrow-left" href="#ai-gateway">
    Route agent model calls through the **AI Gateway** with a single base URL change. Zero vendor lock-in: always run on the best model at the lowest cost for the workload.
  </Card>

  <Card title="Observability" icon="chart-line" href="#observability">
    Export the traces and logs Workers emit to **Orq.ai** over OpenTelemetry, straight from the Workers runtime.
  </Card>
</CardGroup>

## AI Gateway

### Overview

[Cloudflare Agents](https://developers.cloudflare.com/agents/) run on Workers and Durable Objects, and call models through the [AI SDK](https://ai-sdk.dev/docs/introduction). Pointing that provider at **Orq.ai**'s **AI Gateway** sends every model call that uses it through the gateway, so routing, fallbacks, and cost tracking apply to those calls. Calls that read the Workers AI binding directly keep going to Cloudflare.

### Key Benefits

Connecting Cloudflare Agents to **Orq.ai**'s **AI Gateway** adds:

<CardGroup cols={2}>
  <Card title="Complete Observability" icon="chart-line">
    Track model calls and their token usage with detailed traces and analytics
  </Card>

  <Card title="Built-in Reliability" icon="shield-check">
    Automatic fallbacks, retries, and load balancing for production resilience
  </Card>

  <Card title="Cost Optimization" icon="chart-pie">
    Real-time cost tracking and spend management across every AI operation
  </Card>

  <Card title="Multi-Provider Access" icon="cubes">
    Access 500+ LLMs and 30+ providers through a single, unified integration
  </Card>
</CardGroup>

### Prerequisites

Before integrating Cloudflare Agents with **Orq.ai**, confirm:

* An **Orq.ai** account and [API Key](/ai-studio/organization/api-keys)
* A Cloudflare account with a Worker created from the [Cloudflare Agents](https://developers.cloudflare.com/agents/) starter
* `wrangler` installed and authenticated

### Installation

Install the Agents SDK and the AI SDK with the OpenAI-compatible provider:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install agents ai @ai-sdk/openai @cloudflare/ai-chat
```

Store the **Orq.ai** API key as a Worker secret:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx wrangler secret put ORQ_API_KEY
```

### Configure the Gateway

Create the provider once and pass it the gateway base URL. `this.env` carries the secret stored above:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { createOpenAI } from "@ai-sdk/openai";

export interface Env {
  ORQ_API_KEY: string;
}

export const gateway = ({ ORQ_API_KEY }: Env) =>
  createOpenAI({
    baseURL: "https://my.orq.ai/v3/router",
    apiKey: ORQ_API_KEY,
  });
```

> **baseURL**: `https://my.orq.ai/v3/router`

### Basic Agent Example

Every model call in an `Agent` subclass goes through the gateway with that provider:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { Agent } from "agents";
import { generateText } from "ai";

import { gateway, type Env } from "./gateway";

export class Assistant extends Agent<Env> {
  async onRequest(request: Request): Promise<Response> {
    const prompt = new URL(request.url).searchParams.get("prompt") ?? "Explain quantum computing in simple terms.";
    const orq = gateway(this.env);

    const { text } = await generateText({
      model: orq("openai/gpt-5.6-sol"),
      prompt,
    });

    return Response.json({ text });
  }
}
```

For a streaming chat agent, the starter's `AIChatAgent` takes the same provider in `onChatMessage`:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { AIChatAgent } from "@cloudflare/ai-chat";
import { convertToModelMessages, streamText } from "ai";

import { gateway } from "./gateway";

export class ChatAgent extends AIChatAgent {
  async onChatMessage() {
    const result = streamText({
      model: gateway(this.env)("openai/gpt-5.6-sol"),
      messages: await convertToModelMessages(this.messages),
    });

    return result.toUIMessageStreamResponse();
  }
}
```

### Model Selection

With **Orq.ai**, use any supported model from 30+ providers by changing the model id:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { generateText } from "ai";

import { gateway, type Env } from "./gateway";

// Swap the model id for any provider in the catalog:
// anthropic/claude-sonnet-5, google/gemini-2.5-pro, openai/gpt-5.6-luna
export async function ask(env: Env, modelId: string, prompt: string) {
  const orq = gateway(env);

  const { text } = await generateText({
    model: orq(modelId),
    prompt,
  });

  return text;
}
```

See [Supported Models](/ai-gateway/supported-models) for the catalog.

## Observability

### Getting Started

Cloudflare exports Workers telemetry to any OpenTelemetry-compliant destination, and **Orq.ai** is one of them, so traces and logs arrive from the Workers runtime itself.

### Create the destination

Cloudflare keeps destinations at the account level, so the same destination serves every Worker in the account.

1. In the Cloudflare dashboard, open **Observability** > **Destinations** and select **Add destination**.
2. Name the destination, for example `orq-traces`, and set **Destination type** to **Traces**.
3. Set **OTLP endpoint** to `https://my.orq.ai/v2/otel/v1/traces`.
4. Add an **Authorization** entry under **Custom headers** with the value `Bearer <ORQ_API_KEY>`.
5. Save, then repeat with the name `orq-logs`, the type **Logs**, and the endpoint `https://my.orq.ai/v2/otel/v1/logs`.

Both destinations use the same header, and the exporter accepts the base path or the full path. See the [Observability quickstart](/ai-studio/observability/quickstart) for the general OTLP contract and [Base URLs](/reference/base-urls) for self-hosted deployments.

### Reference the destination in Wrangler

Name the destinations in the Worker configuration, then redeploy:

```json wrangler.jsonc theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "observability": {
    "traces": {
      "enabled": true,
      "destinations": ["orq-traces"],
      "head_sampling_rate": 1,
      "persist": false
    },
    "logs": {
      "enabled": true,
      "destinations": ["orq-logs"],
      "head_sampling_rate": 1,
      "persist": false
    }
  }
}
```

* **Sample rate**: `head_sampling_rate` is the share of requests exported, from `0` to `1`. Lower it on high-volume Workers.
* **Persist**: `persist` keeps a copy in Cloudflare as well. Persisted traces and logs count toward Cloudflare Observability usage from 1 December 2026, so the value above exports to **Orq.ai** alone.

Events can take several minutes to reach the destination after the first deploy.

### View Traces

Open **Traces** for the path each request takes through the Worker and its connected services, and **Logs** for the `console.log` output the Worker emits. Model calls are recorded by the gateway, so they appear in the trace of the request that made them.

<CardGroup cols={2}>
  <Card title="Traces" icon="chart-line" href="/ai-studio/observability/traces">
    See each request through the Worker and the services it calls.
  </Card>

  <Card title="Logs" icon="file-lines" href="/ai-studio/observability/logs">
    Search the `console.log` output a Worker emits during a run.
  </Card>
</CardGroup>

## Evaluations & Experiments

Once agents are running, use **Evaluatorq** to score outputs across a dataset and **Experiments** to compare configurations side-by-side.

<CardGroup cols={2}>
  <Card title="Run Evaluations with Evaluatorq" icon="flask" href="/ai-studio/optimize/evaluators#evaluatorq">
    Run parallel evaluations across a set of agents and compare results.
  </Card>

  <Card title="Run Experiments via the API" icon="flask-vial" href="/ai-studio/optimize/experiments">
    Compare agent configurations and view results in the AI Studio.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.