# How Cloud Agents Like Codex Cloud, Devin, and Jules Integrate with OmniRoute

> Learn how cloud agents like Codex Cloud Devin and Jules integrate with OmniRoute. Discover how OmniRoute's unified registry pattern enables seamless routing for these advanced AI agents.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-16

---

**OmniRoute treats Codex Cloud, Devin, and Jules as first‑class providers through a unified registry pattern that maps provider IDs to agent‑specific implementations, enabling seamless routing via the same pipelines that power native LLM providers.**

The **OmniRoute** repository (`diegosouzapw/OmniRoute`) provides a unified routing layer for LLM providers. When you integrate cloud agents with OmniRoute, the system discovers, registers, and invokes remote agents through the same abstraction layers that handle local models and OAuth providers. This architecture ensures that cloud agents participate fully in auto‑combo routing, circuit breakers, and connection cooldown mechanisms.

## The Three-Layer Integration Architecture

Cloud agents integrate through three tightly coupled layers that normalize external agent APIs into OmniRoute’s internal provider interface.

### Agent Definition Layer

Each cloud agent implements a concrete class that handles remote API specifics. In [`src/lib/cloudAgent/agents/jules.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/jules.ts), the agent class defines methods to build URLs, sign requests, and parse responses. Parallel implementations exist for **Devin** ([`src/lib/cloudAgent/agents/devin.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/devin.ts)) and **Codex Cloud** ([`src/lib/cloudAgent/agents/codex-cloud.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/codex-cloud.ts)).

### Agent Registry Layer

The global singleton registry in [`src/lib/cloudAgent/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/registry.ts) maps provider IDs—`"jules"`, `"devin"`, and `"codex-cloud"`—to instantiated agent objects. Routing code resolves agents via `getAgent(providerId)`, ensuring consistent lookup semantics across the codebase.

### Provider-Level Wiring

Cloud agents appear in the provider catalog through several integration points:

- **Provider constants**: [`src/shared/constants/providers/cloud-agent.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/cloud-agent.ts) declares IDs and UI strings.
- **Validation**: [`src/lib/providers/validation/webProvidersB.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/providers/validation/webProvidersB.ts) imports `buildJulesApiUrl` and registers validators for cloud agent payloads.
- **Static model catalog**: [`src/lib/providers/staticModels.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/providers/staticModels.ts) exposes static entries such as `jules: () => [{ id: "jules", name: "Jules (Google Labs coding agent)" }]`.

## Runtime Execution Flow

When a request targets a cloud agent provider, OmniRoute follows a standardized pipeline that transforms requests into agent‑specific formats before execution.

### Request Routing and Validation

Incoming requests to `/v1/chat/completions` or `/v1/agents/tasks` include a `provider` field set to `"jules"`, `"devin"`, or `"codex-cloud"`. The handler validates payloads using Zod schemas, then forwards to the core handler in [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts).

### Credential Management

The system retrieves stored credentials via `getCloudAgentCredentialFromDb`, defined in [`src/lib/cloudAgent/credentials.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/credentials.ts). API keys and base URLs are stored through the REST endpoint at [`src/app/api/v1/agents/credentials/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/agents/credentials/route.ts), then injected into request headers using agent‑specific builders.

### Translation and Execution

Because cloud agents lack specialized executors, they fall back to the **DefaultExecutor** as implemented in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts). However, the request body first passes through an agent‑specific translator that shapes the payload according to the remote API’s contract. The executor performs the actual `fetch` against the cloud endpoint, and the response translator converts the agent‑specific format back into OpenAI‑compatible JSON or SSE streams.

Note that the `CHAT_UNSUPPORTED_CLOUD_AGENT_PROVIDERS` set in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts) currently lists `"jules"` as unsupported for chat, forcing an early error if invoked through standard chat endpoints.

## API Endpoints for Cloud Agent Management

OmniRoute exposes REST endpoints for operational control:

- **Health monitoring**: [`src/app/api/v1/agents/health/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/agents/health/route.ts) returns available agents (`["jules","devin","codex-cloud","cursor-cloud"]`).
- **Credential lifecycle**: [`src/app/api/v1/agents/credentials/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/agents/credentials/route.ts) handles CRUD operations for API keys and base URLs.
- **Task management**: [`src/app/api/v1/agents/tasks/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/agents/tasks/route.ts) and `[id]/route.ts` expose per‑agent task creation and status tracking.

## Implementation Examples

The following patterns demonstrate how to interact with cloud agents programmatically.

Store a Jules credential:

```typescript
import { saveCloudAgentCredential } from "@/lib/cloudAgent/credentials";

await saveCloudAgentCredential({
  providerId: "jules",
  apiKey: "sk-your-jules-key",
  baseUrl: "https://jules.googleapis.com/v1alpha",
});

```

Send a chat request to Codex Cloud:

```typescript
await fetch("/api/v1/chat/completions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "codex-cloud",
    messages: [{ role: "user", content: "Write a hello-world script." }],
  }),
});

```

Internal request pipeline resolution:

```typescript
import { getAgent } from "@/lib/cloudAgent/registry";

const agent = getAgent(req.body.provider); // e.g., "jules"
const cred = await getCloudAgentCredentialFromDb(agent.providerId);
const url = agent.buildUrl(req.body);          // e.g., buildJulesApiUrl(...)
const headers = agent.buildHeaders(cred.apiKey); 
const response = await fetch(url, { method: "POST", headers, body: JSON.stringify(payload) });
const normalized = agent.translateResponse(await response.json());
return normalized; // OpenAI-compatible shape

```

## Summary

- OmniRoute registers cloud agents as first‑class providers through [`src/lib/cloudAgent/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/registry.ts), mapping IDs like `"jules"` and `"devin"` to concrete implementations.
- Agent classes in `src/lib/cloudAgent/agents/*.ts` encapsulate remote API specifics including URL construction, header signing, and response parsing.
- The system reuses existing validation, static model catalogs, and execution pipelines, ensuring cloud agents benefit from circuit breakers and auto‑combo routing.
- Credentials are managed via [`src/app/api/v1/agents/credentials/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/agents/credentials/route.ts) and injected at request time through `getCloudAgentCredentialFromDb`.
- DefaultExecutor handles cloud agent requests after agent‑specific translators normalize payloads, though certain agents like Jules are currently blocked from chat endpoints via `CHAT_UNSUPPORTED_CLOUD_AGENT_PROVIDERS`.

## Frequently Asked Questions

### What file contains the agent registry in OmniRoute?

The global agent registry is implemented in [`src/lib/cloudAgent/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/registry.ts). This file imports each agent class—`JulesAgent`, `DevinAgent`, and `CodexCloudAgent`—and constructs a mapping object that routes provider IDs to instantiated agents.

### How does OmniRoute store API keys for cloud agents?

API keys and base URLs are persisted through [`src/lib/cloudAgent/credentials.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/credentials.ts) using `saveCloudAgentCredential`. The REST endpoint at [`src/app/api/v1/agents/credentials/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/agents/credentials/route.ts) exposes these operations to clients, allowing operators to create, read, update, and delete credentials for each cloud agent provider.

### Why does Jules return an error when used with chat completions?

The executor selection logic in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts) maintains a `CHAT_UNSUPPORTED_CLOUD_AGENT_PROVIDERS` set that currently includes `"jules"`. When a request specifies this provider, the system raises an early error before reaching the execution phase, indicating that Jules must be accessed through the dedicated task endpoints rather than standard chat completions.

### Can cloud agents participate in OmniRoute's auto‑combo routing?

Yes. Because cloud agents register in the same provider catalog as native LLMs—through [`src/shared/constants/providers/cloud-agent.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/cloud-agent.ts) and [`src/lib/providers/staticModels.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/providers/staticModels.ts)—they automatically inherit resilience features including auto‑combo routing, circuit breakers, and connection cooldown mechanisms.