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

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, the agent class defines methods to build URLs, sign requests, and parse responses. Parallel implementations exist for Devin (src/lib/cloudAgent/agents/devin.ts) and Codex Cloud (src/lib/cloudAgent/agents/codex-cloud.ts).

Agent Registry Layer

The global singleton registry in 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 declares IDs and UI strings.
• Validation: src/lib/providers/validation/webProvidersB.ts imports buildJulesApiUrl and registers validators for cloud agent payloads.
• Static model catalog: 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.

Credential Management

The system retrieves stored credentials via getCloudAgentCredentialFromDb, defined in 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, 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. 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 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 returns available agents (["jules","devin","codex-cloud","cursor-cloud"]).
• Credential lifecycle: 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 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:

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:

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:

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, 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 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. 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 using saveCloudAgentCredential. The REST endpoint at 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 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 and src/lib/providers/staticModels.ts—they automatically inherit resilience features including auto‑combo routing, circuit breakers, and connection cooldown mechanisms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}