OmniRoute/docs/i18n/yo/docs/frameworks/CLOUD_AGENT.md

Cloud Agents (Yorùbá)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Orísun òtítọ́: src/lib/cloudAgent/ àti src/app/api/v1/agents/tasks/ Ìmúdójúìwọ̀n tó kẹ́yìn: 2026-06-28 — v3.8.40 (ìmúdójúìwọ̀n frontmatter; àwọn agent 4 pẹ̀lú cursor-cloud)

OmniRoute ń ṣètò àwọn agent ìkọ́ kóòdù tí àwọn ẹlòmíràn gbàlejò lórí cloud (Codex Cloud, Cursor, Devin, Jules) gẹ́gẹ́ bí àwọn iṣẹ́ tó ń ṣiṣẹ́ fún ìgbà pípẹ́. Agent kọ̀ọ̀kan ni a fi pamọ́ sẹ́yìn interface kan náà kí àwọn client lè fi prompt + URL repo ránṣẹ́, kí wọ́n sì gba àbájáde láìní láti bójú tó àwọn API tó jẹ́ ti provider kọ̀ọ̀kan.

Iṣẹ́ Cloud Agent kì í ṣe ìparí chat déédéé. Ó jẹ́ ẹ̀ka iṣẹ́ tó dúró pẹ́, tó sì ní ọ̀pọ̀ ìgbésẹ̀, tó lè gba láti ìṣẹ́jú dé wákàtí, tó lè ṣe Pull Request gẹ́gẹ́ bí artifact rẹ̀, tó sì ń ṣe àtìlẹ́yìn fún àwọn ìfiránṣẹ́ àfikún àti (nínú àwọn provider kan) àwọn ẹnu-ọ̀nà ìfọwọ́sí ètò.

Orísun: diagrams/cloud-agent-flow.mmd

Àwọn Agent Tí A Ṣe Àtìlẹ́yìn Fún

ID Provider	Class	Orísun	URL Ìpìlẹ̀ Upstream	Ìfọwọ́sí Ètò
jules	JulesAgent	src/lib/cloudAgent/agents/jules.ts	https://jules.googleapis.com/v1alpha	Bẹ́ẹ̀ni
devin	DevinAgent	src/lib/cloudAgent/agents/devin.ts	https://api.devin.ai/v1	Bẹ́ẹ̀ni
codex-cloud	CodexCloudAgent	src/lib/cloudAgent/agents/codex.ts	https://api.openai.com/v1/codex/cloud	Rárá (aládàáṣiṣẹ́)
cursor-cloud	CursorCloudAgent	src/lib/cloudAgent/agents/cursor.ts	https://api.cursor.com/v0	Rárá (aládàáṣiṣẹ́)

Registry: src/lib/cloudAgent/registry.ts — ń export getAgent(providerId), getAvailableAgents(), àti isCloudAgentProvider(providerId). Registry náà jẹ́ Record<string, CloudAgentBase> inú memory lásán tí a kún nígbà tí module bá ń load.

Àgbékalẹ̀

Client (Dashboard / CLI / API)
  → POST /api/v1/agents/tasks (management auth jẹ́ dandan)
    → Ìfàṣẹsí CreateCloudAgentTaskSchema (Zod)
    → registry.getAgent(providerId)
    → getCloudAgentCredentials(providerId)
      └─ ń fà á láti inú getProviderConnections({ provider, isActive: true })
         (apiKey lákọ̀ọ́kọ́, accessToken ni àfidípò)
    → agent.createTask({ prompt, source, options }, credentials)
      └─ HTTP POST sí API provider upstream
      └─ ń dá CloudAgentTask padà pẹ̀lú id inú ètò + externalId
    → insertCloudAgentTask(...) sínú cloud_agent_tasks (SQLite)

Ìṣàyẹ̀wò léraléra (lazy sync nígbà kíkà):
  GET /api/v1/agents/tasks/[id]
    → getCloudAgentTaskById(id)
    → agent.getStatus(externalId, credentials)  // ń sọ status + activities di tuntun
    → updateCloudAgentTask(...) pẹ̀lú status, result, completed_at tuntun
    → dá iṣẹ́ tí a ti serialize padà

Àwọn ìbáṣepọ̀:
  POST /api/v1/agents/tasks/[id]  body: { action: "approve" | "message" | "cancel" }
    → agent.approvePlan(externalId, credentials)        fún "approve"
    → agent.sendMessage(externalId, message, credentials) fún "message"
    → status yí padà sí "cancelled"                     fún "cancel" (local-only)

Sync jẹ́ lazy: a ń sọ status di tuntun láti upstream ní gbogbo GET /tasks/[id]. Kò sí poller abẹ́lẹ̀. Àwọn dashboard tó nílò state tuntun yẹ kí wọ́n máa poll endpoint GET ní àárín àkókò tó bójú mu.

Ìṣàlàyé CloudAgentBase

Orísun: src/lib/cloudAgent/baseAgent.ts

export interface AgentCredentials {
  apiKey: string;
  baseUrl?: string;
}

export interface CreateTaskParams {
  prompt: string;
  source: CloudAgentSource;
  options: {
    autoCreatePr?: boolean;
    planApprovalRequired?: boolean;
    environment?: Record<string, string>;
  };
}

export interface GetStatusResult {
  status: CloudAgentStatus;
  externalId?: string;
  result?: CloudAgentResult;
  activities: CloudAgentActivity[];
  error?: string;
}

export abstract class CloudAgentBase {
  abstract readonly providerId: string;
  abstract readonly baseUrl: string;

  abstract createTask(p: CreateTaskParams, c: AgentCredentials): Promise<CloudAgentTask>;
  abstract getStatus(externalId: string, c: AgentCredentials): Promise<GetStatusResult>;
  abstract approvePlan(externalId: string, c: AgentCredentials): Promise<void>;
  abstract sendMessage(
    externalId: string,
    message: string,
    c: AgentCredentials
  ): Promise<CloudAgentActivity>;
  abstract listSources(
    c: AgentCredentials
  ): Promise<{ name: string; url: string; branch?: string }[]>;

  protected mapStatus(raw: string): CloudAgentStatus; // ìfojúrí okun-ọ̀rọ̀ láti upstream → enum
  protected generateTaskId(): string; // `task_<ts>_<rand>`
  protected generateActivityId(): string; // `act_<ts>_<rand>`
}

CodexCloudAgent.approvePlan máa ń ju àṣìṣe jáde ní ìmọ̀ọ́mọ̀ — Codex Cloud máa ń ṣe ètò fúnra rẹ̀, kò sì ní ibodè ìfọwọ́sí. CodexCloudAgent.listSources máa ń dá [] padà.

CursorCloudAgent ń darí Background / Cloud Agents ti Cursor nípasẹ̀ REST API oníṣẹ́ rẹ̀ (api.cursor.com/v0) pẹ̀lú kọ́kọ́rọ́ API olumulo tàbí àkọọ́lẹ̀-iṣẹ́ — àṣàyàn ẹgbẹ́-àkọ́kọ́ tó ní ààbò jù fún lílo session OAuth Cursor IDE padà (olùpèsè cursor, èyí tó ní ìkìlọ̀ ewu ìfòfindè). Ó jẹ́ adapter REST lásán (kò ní dependency abinibi @cursor/sdk). approvePlan máa ń ju àṣìṣe jáde (àwọn agent Cursor máa ń ṣiṣẹ́ láìsí ìdarí); listSources máa ń ṣe àkójọ àwọn repository tí kọ́kọ́rọ́ náà lè dé sí. Cursor máa ń dá àwọn enum ipò UPPERCASE padà (CREATING/RUNNING/FINISHED/ERROR), tí a sì yí wọn padà ní kedere sí CloudAgentStatus tí gbogbo wọn ń lò. A lè ṣàtúnṣe baseUrl fún credential kọ̀ọ̀kan, kí a lè ṣe àtúnṣe ẹ̀yà/ipa-ọ̀nà API láìyí kóòdù padà.

Àwọn Irú Domain

Orísun: src/lib/cloudAgent/types.ts

export const CLOUD_AGENT_STATUS = {
  QUEUED: "queued",
  RUNNING: "running",
  AWAITING_APPROVAL: "awaiting_approval",
  COMPLETED: "completed",
  FAILED: "failed",
  CANCELLED: "cancelled",
} as const;

export interface CloudAgentSource {
  repoName: string;
  repoUrl: string; // ó gbọ́dọ̀ jẹ́ URL tó fẹsẹ̀ múlẹ̀
  branch?: string;
}

export interface CloudAgentResult {
  prUrl?: string;
  prNumber?: number;
  commitMessage?: string;
  diffUrl?: string;
  summary?: string;
  duration?: number; // ìṣẹ́jú-àáyá, integer rere
  cost?: number; // float rere
}

export interface CloudAgentActivity {
  id: string;
  type: "plan" | "command" | "code_change" | "message" | "error" | "completion";
  content: string;
  timestamp: string; // ISO 8601
  metadata?: Record<string, unknown>;
}

export interface CloudAgentTask {
  id: string; // id inú ètò `task_...`
  providerId: "jules" | "devin" | "codex-cloud" | "cursor-cloud";
  externalId?: string; // id olùpèsè upstream
  status: CloudAgentStatus;
  prompt: string; // àwọn lẹ́tà 1..10000
  source: CloudAgentSource;
  options: {
    autoCreatePr?: boolean;
    planApprovalRequired?: boolean;
    environment?: Record<string, string>;
  };
  result?: CloudAgentResult;
  activities: CloudAgentActivity[];
  error?: string;
  createdAt: string;
  updatedAt: string;
  completedAt?: string;
}

Àwọn schema ìfọwọ́sí (CreateCloudAgentTaskSchema, UpdateCloudAgentTaskSchema) ni a export pẹ̀lú àwọn irú náà, àwọn route handler sì ń lò wọ́n.

Ìpamọ́ dátà

Orísun: src/lib/cloudAgent/db.ts — a máa ń ṣẹ̀dá tábìlì náà nígbà tí a bá kọ́kọ́ nílò rẹ̀ nípasẹ̀ createCloudAgentTaskTable() (a tún ń pè é láti src/lib/cloudAgent/index.ts nígbà ìmúwọlé módù).

CREATE TABLE IF NOT EXISTS cloud_agent_tasks (
  id           TEXT PRIMARY KEY,
  provider_id  TEXT NOT NULL,
  external_id  TEXT,
  status       TEXT NOT NULL DEFAULT 'queued',
  prompt       TEXT NOT NULL,
  source       TEXT NOT NULL,             -- JSON
  options      TEXT DEFAULT '{}',         -- JSON
  result       TEXT,                       -- JSON
  activities   TEXT DEFAULT '[]',          -- JSON
  error        TEXT,
  created_at   TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at   TEXT NOT NULL DEFAULT (datetime('now')),
  completed_at TEXT
);
CREATE INDEX IF NOT EXISTS idx_cloud_agent_tasks_provider ON cloud_agent_tasks(provider_id);
CREATE INDEX IF NOT EXISTS idx_cloud_agent_tasks_status   ON cloud_agent_tasks(status);
CREATE INDEX IF NOT EXISTS idx_cloud_agent_tasks_created  ON cloud_agent_tasks(created_at DESC);

updateCloudAgentTask ń fipá mú lílo àtòjọ àwọn kọ́lámù tí a fọwọ́ sí láti dènà ìkọlù abẹrẹ SQL: status, prompt, source, options, result, activities, error, completed_at. Bọ́tìnì mìíràn èyíkéyìí nínú ìmúdójúìwọ̀n apá kan ni a máa yọ kúrò láìsọ ohunkóhun.

REST API — Ìgbésí-ayé Iṣẹ́

Ìfàṣẹsí: Gbogbo ibi ìwọlé /api/v1/agents/tasks* nílò ìfàṣẹsí ìṣàkóso (requireCloudAgentManagementAuth yí requireManagementAuth láti src/lib/api/requireManagementAuth ká). A ti ń fipá mú èyí lẹ́yìn commit 588a0333 ("àtúnṣe(auth): béèrè ìfàṣẹsí ìṣàkóso fún àwọn API aṣojú àti àkókò ìsinmi").

Ọ̀nà	Ipa-ọ̀nà	Ète
OPTIONS	/api/v1/agents/tasks	Ìbéèrè àkọ́kọ́ CORS
GET	/api/v1/agents/tasks	Ṣàtòjọ àwọn iṣẹ́ (àsẹ̀: provider, status, limit≤500)
POST	/api/v1/agents/tasks	Ṣẹ̀dá iṣẹ́ (ránṣẹ́ sí upstream + tọ́jú rẹ̀)
DELETE	/api/v1/agents/tasks?id=...	Pa iṣẹ́ rẹ́ nípasẹ̀ id ìbéèrè (kò fagilé upstream)
OPTIONS	/api/v1/agents/tasks/[id]	Ìbéèrè àkọ́kọ́ CORS
GET	/api/v1/agents/tasks/[id]	Ka iṣẹ́ + mú ipò ṣiṣẹ́pọ̀ pẹ̀lẹ́pẹ̀lẹ́ láti upstream
POST	/api/v1/agents/tasks/[id]	Ìgbésẹ̀: approve / message / cancel
DELETE	/api/v1/agents/tasks/[id]	Pa iṣẹ́ rẹ́ nípasẹ̀ id inú ipa-ọ̀nà

Ṣẹ̀dá iṣẹ́

curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "devin",
    "prompt": "Fix the bug in src/foo.ts where the parser returns null",
    "source": {
      "repoName": "user/repo",
      "repoUrl": "https://github.com/user/repo",
      "branch": "main"
    },
    "options": {
      "autoCreatePr": true,
      "planApprovalRequired": false
    }
  }'

Ìdáhùn 201:

{
  "data": {
    "id": "task_1731512345678_abc123def",
    "providerId": "devin",
    "externalId": "session_xyz",
    "status": "queued",
    "prompt": "...",
    "source": { "repoName": "user/repo", "repoUrl": "...", "branch": "main" },
    "options": { "autoCreatePr": true },
    "createdAt": "2026-05-13T12:34:56.789Z"
  }
}

Fọwọ́ sí ètò kan

curl -X POST http://localhost:20128/api/v1/agents/tasks/<id> \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"action":"approve"}'

Fi ìfiránṣẹ́ àfikún ránṣẹ́

curl -X POST http://localhost:20128/api/v1/agents/tasks/<id> \
  -d '{"action":"message","message":"Also add a unit test for the parser"}'

Fagilé (ipò agbègbè nìkan)

curl -X POST http://localhost:20128/api/v1/agents/tasks/<id> \
  -d '{"action":"cancel"}'

cancel yí status padà sí "cancelled" nínú DB agbègbè, ṣùgbọ́n kò pe olùpèsè upstream — kò sí RPC ìdádúró nínú CloudAgentBase. Láti dá ìdíyelé upstream dúró, parí iṣẹ́ náà nínú console ti olùpèsè fúnra rẹ̀.

REST API — Ìsopọ̀ Abẹ́lẹ̀ Olùpèsè Cloud

Àwọn endpoint àfikún wọ̀nyí lábẹ́ src/app/api/cloud/ ni àwọn client jíjìnnà (CLI, app Electron, tàbí àwọn worker ìmúdọ́gba) ń lò láti ka metadata ìsopọ̀ olùpèsè àti láti yanjú àwọn alias model. Wọ́n jẹ́rìísí pẹ̀lú API key déédéé (nípasẹ̀ validateApiKey), kì í ṣe ìjẹ́rìísí ìṣàkóso tí àwọn endpoint task ń lò.

Ọ̀nà	Path	Ète
POST	/api/cloud/auth	Ṣàyẹ̀wò API key, dá metadata ìsopọ̀ tí a bo + àwọn alias model padà
PUT	/api/cloud/credentials/update	Ṣe ìmúdójúìwọ̀n accessToken / refreshToken / expiresAt
POST	/api/cloud/model/resolve	Yanjú alias model kan sí { provider, model }
GET	/api/cloud/models/alias	Ṣàkójọ gbogbo àwọn alias model
PUT	/api/cloud/models/alias	Ṣètò alias model kan (kí o sì múdọ́gba sí Cloud láìfọwọ́ṣe bí ó bá ṣiṣẹ́)

/api/cloud/auth kì í dá apiKey / accessToken / refreshToken àìlábò padà láé. Ó máa ń dá hasApiKey, hasAccessToken, hasRefreshToken, àti àwòrán àkọ́kọ́ tí a bo padà (maskedApiKey: 4 àkọ́kọ́ + **** + 4 ìkẹyìn).

Ìyanjú Credentials

getCloudAgentCredentials(providerId) nínú src/lib/cloudAgent/api.ts:

1. Ó gbé àwọn ìsopọ̀ olùpèsè tó ń ṣiṣẹ́ wọlé nípasẹ̀ getProviderConnections({ provider: providerId, isActive: true }).
2. Fún ìsopọ̀ kọ̀ọ̀kan, ó kọ́kọ́ yan apiKey (tí a gé àyè rẹ̀ kúrò). Bí kò bá sí, ó máa ń lo accessToken.
3. Ó dá token àkọ́kọ́ tí kò ṣófo padà, tí a dì sínú { apiKey: token }.
4. Ó dá null padà bí kò bá rí token tó ṣeé lò — API náà máa dá 400 padà pẹ̀lú "No active credentials configured for cloud agent provider: <id>".

Èyí túmọ̀ sí pé àwọn Cloud Agent tún ń lo tábìlì Provider Connection kan náà tí àwọn olùpèsè LLM déédéé ń lò. Láti mú Jules ṣiṣẹ́, ṣẹ̀dá ìsopọ̀ tó ń ṣiṣẹ́ pẹ̀lú provider: "jules" àti apiKey tí a ti kún.

Dashboard

Orísun: src/app/(dashboard)/dashboard/cloud-agents/page.tsx

Ojú-ìwé React "use client" kan tí ó:

• Ṣàkójọ àwọn task (tí a ń yẹ̀wò léraléra nípasẹ̀ GET /api/v1/agents/tasks).
• Fi àwọn task tuntun ránṣẹ́ nípasẹ̀ fọ́ọ̀mù kan tí a so mọ́ CreateCloudAgentTaskSchema.
• Ṣàfihàn àwọn badge ipò (queued, running, awaiting_approval, completed, failed, cancelled) ó sì ṣe àfihàn ìtòlẹ́sẹẹsẹ activities[].
• Ṣàfihàn result.prUrl / commitMessage / summary nígbà tí status === "completed".

Ìsopọ̀ pẹ̀lú A2A

A lè ṣàfihàn àwọn Cloud Agent gẹ́gẹ́ bí àwọn ọgbọ́n A2A nípa fíforúkọsílẹ̀ ọgbọ́n A2A kan tí ó fi handler tasks/send rẹ̀ lé getAgent(...).createTask(...) lọ́wọ́, tí ó sì túmọ̀ àwọn event ipò task A2A sí protocol JSON-RPC 2.0. Wo A2A-SERVER.md.

Fífi Cloud Agent Tuntun Kún Un

1. Ṣẹ̀dá src/lib/cloudAgent/agents/<name>.ts tí ó fa CloudAgentBase gùn.
2. Ṣe àgbékalẹ̀ createTask, getStatus, approvePlan (tàbí ju exception bí kò bá wúlò), sendMessage, listSources. Lo this.mapStatus(...) fún ṣíṣe ìṣọ̀kan ipò.
3. Forúkọsílẹ̀ rẹ̀ nínú src/lib/cloudAgent/registry.ts lábẹ́ providerId tó dúró ṣinṣin.
4. Fẹ̀ union literal providerId nínú src/lib/cloudAgent/types.ts sí i (CloudAgentTask.providerId àti CreateCloudAgentTaskSchema).
5. Fi olùpèsè náà kún src/shared/constants/providers.ts bí ó bá nílò record ìsopọ̀. Àwọn olùpèsè tó dá lórí OAuth tún nílò src/lib/oauth/providers/.
6. Fi àwọn test kún abẹ́ tests/unit/cloud-agent-*.test.ts.
7. Ṣe ìmúdójúìwọ̀n doc yìí àti constant CLOUD_AGENTS ti dashboard náà.

Ìṣètò

Àyípadà Àyíká	Ète
DATA_DIR	Ibi tí dátábẹ́ẹ̀sì SQLite tó ní cloud_agent_tasks wà
JWT_SECRET	A nílò rẹ̀ fún ìfàṣẹsí ìṣàkóso lórí àwọn ibi ìdáhùn iṣẹ́
API_KEY_SECRET	A nílò rẹ̀ láti fi ìpamọ́ ọ̀rọ̀ kọ́ àwọn ẹ̀rí ìsopọ̀ olùpèsè níbi ìpamọ́

Kò sí àwọn àyípadà àyíká pàtó fún Cloud-Agent lónìí — gbogbo àṣírí ló wà nínú tábìlì provider_connections.

Tún Wo

• A2A-SERVER.md
• API_REFERENCE.md
• SKILLS.md
• MEMORY.md
• Orísun: src/lib/cloudAgent/
• Àwọn ọ̀nà: src/app/api/v1/agents/tasks/, src/app/api/cloud/
• Pánẹ́ẹ̀lì ìṣàkóso: src/app/(dashboard)/dashboard/cloud-agents/page.tsx