# How Cloud Agents (Codex, Devin, and Jules) Integrate with OmniRoute: A Complete Technical Guide

> Learn how cloud agents Codex Devin and Jules integrate with OmniRoute. Discover the three layer architecture enabling seamless discovery registration and invocation for your LLM providers.

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

---

**Cloud agents like Codex Cloud, Devin, and Jules integrate with OmniRoute through a three-layer architecture that treats each agent as a first-class provider, enabling discovery, registration, and invocation via the same pipelines as native LLM providers.**

OmniRoute unifies access to specialized AI coding agents by abstracting them behind a consistent provider interface. This guide examines how the framework discovers, authenticates, routes, and executes requests for Google Jules, Cognition Devin, and OpenAI Codex Cloud—using actual source paths and implementation details from the diegosouzapw/OmniRoute codebase.

## The Three-Layer Integration Architecture

OmniRoute's cloud-agent support is built on three tightly coupled layers that mirror the patterns used for standard LLM providers.

### Agent Definition Layer: Concrete API Clients

Each cloud agent has a dedicated class that handles remote API communication—building URLs, signing requests, and parsing responses.

| Agent | Implementation File | Core Responsibility |
|-------|---------------------|---------------------|
| **Jules** | [`src/lib/cloudAgent/agents/jules.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/jules.ts) | Google Labs coding agent integration with `buildJulesApiUrl()` and `julesHeaders` |
| **Devin** | [`src/lib/cloudAgent/agents/devin.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/devin.ts) | Cognition AI autonomous engineer integration |
| **Codex Cloud** | [`src/lib/cloudAgent/agents/codex-cloud.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/codex-cloud.ts) | OpenAI cloud-hosted Codex integration |

These classes implement a common interface defined in [`src/lib/cloudAgent/types.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/types.ts), ensuring polymorphic handling across the routing pipeline.

### Agent Registry Layer: Global Provider Discovery

The [`src/lib/cloudAgent/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/registry.ts) singleton maps provider IDs to instantiated agent objects. Routing code never hardcodes agent references—it always resolves through `getAgent("jules")` or `getAgent("devin")`.

The registry builds this mapping at module init:

```typescript
// src/lib/cloudAgent/registry.ts (conceptual structure)
import { JulesAgent } from './agents/jules';
import { DevinAgent } from './agents/devin';
import { CodexCloudAgent } from './agents/codex-cloud';

const registry = {
  jules: new JulesAgent(),
  devin: new DevinAgent(),
  "codex-cloud": new CodexCloudAgent(),
};

export const getAgent = (id: string) => registry[id];

```

This design allows dynamic agent addition without modifying routing logic throughout the codebase.

### Provider-Level Wiring: Catalog, Validation, and Static Models

Cloud agents appear in all provider-facing systems so UI, auto-complete, and routing treat them identically to native LLMs:

- **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 display 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 a Zod validator for `"jules"`
- **Static model catalog**: [`src/lib/providers/staticModels.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/providers/staticModels.ts) adds a factory function returning Jules metadata:

```typescript
// src/lib/providers/staticModels.ts
jules: () => [{ 
  id: "jules", 
  name: "Jules (Google Labs coding agent)" 
}]

```

## REST API Exposure for Agent Operations

OmniRoute exposes full CRUD capabilities for cloud agent management through dedicated REST endpoints.

### Health and Discovery

The `GET /api/v1/agents/health` endpoint (implemented in [`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:

```typescript
// Response from /api/v1/agents/health
["jules", "devin", "codex-cloud", "cursor-cloud"]

```

### Credential Management

The credentials API ([`src/app/api/v1/agents/credentials/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/agents/credentials/route.ts)) persists API keys and base URLs via [`src/lib/cloudAgent/credentials.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/credentials.ts):

```typescript
// Example: Creating a new Jules credential
import { saveCloudAgentCredential } from "@/lib/cloudAgent/credentials";

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

```

### Task Management

Per-agent task endpoints at [`/api/v1/agents/tasks/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main//api/v1/agents/tasks/route.ts) and `/api/v1/agents/tasks/[id]/route.ts` enable lifecycle management of agent sessions.

## Request Execution Pipeline

When a client targets a cloud-agent provider, OmniRoute resolves execution through a specialized path that preserves compatibility with standard OpenAI-style clients.

### Step-by-Step Flow

1. **Entry**: Client POSTs to `/v1/chat/completions` with `provider: "jules"` or `{"model": "codex-cloud", ...}`

2. **Validation**: Zod schemas in route handlers validate payload structure

3. **Provider resolution**: Core handler ([`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts)) calls `getAgent(req.body.provider)`

4. **Credential injection**: `getCloudAgentCredentialFromDb(agent.providerId)` retrieves stored keys

5. **Request translation**: Agent-specific translator shapes the payload for the remote API

6. **Execution**: `DefaultExecutor` performs the fetch (cloud agents lack specialized executors)

7. **Response normalization**: Agent-specific response translator converts to OpenAI-compatible JSON or SSE

### Executor Selection and Current Limitations

The executor selection logic in [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts) contains a `CHAT_UNSUPPORTED_CLOUD_AGENT_PROVIDERS` set that currently lists `"jules"` as unsupported for chat, forcing an early error. This guard enables gradual rollout while the architecture supports full integration.

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

const agent = getAgent(req.body.provider);        // "jules" | "devin" | "codex-cloud"
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(agent.translateRequest(req.body)) 
});
return agent.translateResponse(await response.json());

```

## Resilience and Routing Benefits

Because cloud agents register in the same provider catalog as native LLMs, they automatically inherit:

- **Auto-combo routing**: Fallback and load-balancing across agent and non-agent providers
- **Circuit-breaker protection**: Automatic detection of agent unavailability
- **Connection cool-down**: Rate limiting and backoff consistent with other providers

This unified resilience model ensures graceful degradation when Jules, Devin, or Codex Cloud experience outages—without custom error handling in application code.

## Client-Side Usage Examples

### Standard Chat Completion Request

```typescript
// Sending a chat request to Codex Cloud (client side)
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 in Python." 
    }],
  }),
});

```

### Direct Agent Task API

```typescript
// Creating a task via the agent-specific endpoint
await fetch("/api/v1/agents/tasks", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    provider: "devin",
    prompt: "Implement a React component for a data table with sorting",
    repositoryUrl: "https://github.com/org/project"
  }),
});

```

## Key Source Files Reference

| Component | Path |
|-----------|------|
| Type definitions | [`src/lib/cloudAgent/types.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/types.ts) |
| Registry singleton | [`src/lib/cloudAgent/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/registry.ts) |
| Jules implementation | [`src/lib/cloudAgent/agents/jules.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/jules.ts) |
| Devin implementation | [`src/lib/cloudAgent/agents/devin.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/devin.ts) |
| Codex Cloud implementation | [`src/lib/cloudAgent/agents/codex-cloud.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/agents/codex-cloud.ts) |
| Provider UI constants | [`src/shared/constants/providers/cloud-agent.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/providers/cloud-agent.ts) |
| Validation logic | [`src/lib/providers/validation/webProvidersB.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/providers/validation/webProvidersB.ts) |
| Static model catalog | [`src/lib/providers/staticModels.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/providers/staticModels.ts) |
| Health endpoint | [`src/app/api/v1/agents/health/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/agents/health/route.ts) |
| Credential storage | [`src/app/api/v1/agents/credentials/route.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/v1/agents/credentials/route.ts) |
| Executor selection | [`open-sse/executors/index.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/executors/index.ts) |

## Summary

- **Cloud agents integrate as first-class providers** through the `Agent Definition → Registry → Provider Wiring` three-layer architecture in `diegosouzapw/OmniRoute`

- **Concrete agent classes** in `src/lib/cloudAgent/agents/` encapsulate API-specific logic for Jules, Devin, and Codex Cloud

- **Global registry pattern** in [`src/lib/cloudAgent/registry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/registry.ts) enables polymorphic agent resolution without hardcoded references

- **Unified REST API** supports health checks, credential management, and task lifecycle operations

- **OpenAI-compatible execution pipeline** translates requests/responses while preserving standard client interfaces

- **Inherited resilience features** include circuit-breakers, auto-combo routing, and connection cool-down—no custom handling required

## Frequently Asked Questions

### What distinguishes cloud agents from standard LLM providers in OmniRoute?

Cloud agents implement specialized request building and response parsing for autonomous coding agents rather than simple text completion. The `JulesAgent`, `DevinAgent`, and `CodexCloudAgent` classes in `src/lib/cloudAgent/agents/` handle agent-specific authentication schemes, pagination, and result formats that differ from OpenAI-compatible APIs.

### Why is Jules currently marked as unsupported for chat in the codebase?

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) explicitly lists `"jules"` to prevent incomplete chat integrations from reaching production. This guard allows the architecture—registry, credentials, translation layers—to be fully implemented while the chat-specific protocol negotiation remains under development.

### How does credential storage handle multiple API keys for the same agent type?

The `saveCloudAgentCredential` function in [`src/lib/cloudAgent/credentials.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/cloudAgent/credentials.ts) stores credentials with a composite key of `providerId` plus optional environment or workspace identifiers. The database schema supports multiple credential sets per agent, with selection logic in `getCloudAgentCredentialFromDb` resolving based on request context or fallback defaults.

### Can cloud agents participate in model routing alongside standard LLMs?

Yes—because agents register in [`src/lib/providers/staticModels.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/providers/staticModels.ts) and validate through [`src/lib/providers/validation/webProvidersB.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/providers/validation/webProvidersB.ts), they appear identically to routing logic. Auto-combo configurations can include `"jules"` or `"devin"` in provider lists, enabling intelligent fallback between cloud agents and traditional models based on availability and cost policies.