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

Cloud Agents (Igbo)

🌐 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 · 🇮🇹 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 · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Isi iyi nke eziokwu: src/lib/cloudAgent/ na src/app/api/v1/agents/tasks/ Emelitere ikpeazụ: 2026-06-28 — v3.8.40 (mmelite frontmatter; ndị nnọchi anya 4 gụnyere cursor-cloud)

OmniRoute na-ahazi ndị nnọchi anya ide koodu nke ndị ọzọ na-akwado n'igwe ojii (Codex Cloud, Cursor, Devin, Jules) dị ka ọrụ na-adịte aka. A na-etinye onye nnọchi anya ọ bụla n'azụ otu interface ka ndị ahịa nwee ike izipu prompt + URL repo ma nata nsonaazụ n'enweghị mkpa ijikwa API ndị pụrụ iche nke onye na-eweta ọrụ.

Ọrụ Onye Nnọchi Anya Igwe Ojii abụghị mmecha nkata nkịtị. Ọ bụ ngalaba ọrụ na-adịgide adịgide, nwere ọtụtụ usoro, nke nwere ike iwe nkeji ruo ọtụtụ awa, nwee ike ịmepụta Pull Request dị ka artifact ya, ma na-akwado ozi ndị ọzọ na-esochi na (n'aka ụfọdụ ndị na-eweta ọrụ) ọnụ ụzọ nkwado atụmatụ.

Isi iyi: diagrams/cloud-agent-flow.mmd

Ndị Nnọchi Anya A Na-akwado

ID Onye Na-eweta Ọrụ	Klas	Isi Iyi	URL Ndabere Upstream	Nkwado Atụmatụ
jules	JulesAgent	src/lib/cloudAgent/agents/jules.ts	https://jules.googleapis.com/v1alpha	Ee
devin	DevinAgent	src/lib/cloudAgent/agents/devin.ts	https://api.devin.ai/v1	Ee
codex-cloud	CodexCloudAgent	src/lib/cloudAgent/agents/codex.ts	https://api.openai.com/v1/codex/cloud	Mba (akpaghị aka)
cursor-cloud	CursorCloudAgent	src/lib/cloudAgent/agents/cursor.ts	https://api.cursor.com/v0	Mba (akpaghị aka)

Ndekọ: src/lib/cloudAgent/registry.ts — na-ebupụ getAgent(providerId), getAvailableAgents(), na isCloudAgentProvider(providerId). Ndekọ ahụ bụ Record<string, CloudAgentBase> nkịtị dị na ebe nchekwa nke a na-ejupụta mgbe modul na-ebunye.

Nhazi Sistemụ

Onye ahịa (Dashboard / CLI / API)
  → POST /api/v1/agents/tasks (achọrọ njirimara njikwa)
    → Nnyocha CreateCloudAgentTaskSchema (Zod)
    → registry.getAgent(providerId)
    → getCloudAgentCredentials(providerId)
      └─ na-ewepụta site na getProviderConnections({ provider, isActive: true })
         (apiKey buru ụzọ, laghachi na accessToken ma ọ bụrụ na ọ dịghị)
    → agent.createTask({ prompt, source, options }, credentials)
      └─ HTTP POST gaa na API nke onye na-eweta upstream
      └─ na-eweghachi CloudAgentTask nwere id ime + externalId
    → insertCloudAgentTask(...) n'ime cloud_agent_tasks (SQLite)

Nnyocha ugboro ugboro (mmekọrịta umengwụ mgbe a na-agụ):
  GET /api/v1/agents/tasks/[id]
    → getCloudAgentTaskById(id)
    → agent.getStatus(externalId, credentials)  // na-emelite ọnọdụ + mmemme
    → updateCloudAgentTask(...) site na ọnọdụ ọhụrụ, nsonaazụ, completed_at
    → weghachite ọrụ e mere serialization

Mmekọrịta:
  POST /api/v1/agents/tasks/[id]  ahụ: { action: "approve" | "message" | "cancel" }
    → agent.approvePlan(externalId, credentials)        maka "approve"
    → agent.sendMessage(externalId, message, credentials) maka "message"
    → ọnọdụ na-agbanwe gaa na "cancelled"               maka "cancel" (naanị n'ime sistemụ)

Mmekọrịta bụ umengwụ: a na-eme ka ọnọdụ dị ọhụrụ site na upstream na GET /tasks/[id] ọ bụla. Enweghị poller ndabere. Dashboard ndị chọrọ ọnọdụ ọhụrụ kwesịrị ịna-ajụ endpoint GET n'ogologo oge kwesịrị ekwesị.

Ọdịdị ihu CloudAgentBase

Isi mmalite: 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; // usoro ntule upstream-string → enum
  protected generateTaskId(): string; // `task_<ts>_<rand>`
  protected generateActivityId(): string; // `act_<ts>_<rand>`
}

CodexCloudAgent.approvePlan na-atụpụ njehie ụma — Codex Cloud na-emepụta atụmatụ na-akpaghị aka, ọ nweghịkwa ọnụ ụzọ nkwado. CodexCloudAgent.listSources na-eweghachi [].

CursorCloudAgent na-achịkwa Background / Cloud Agents nke Cursor site na REST API gọọmentị ya (api.cursor.com/v0) site na iji igodo API nke onye ọrụ ma ọ bụ akaụntụ ọrụ — ụzọ ọzọ dị nchebe, nke sitere n'aka ndị nwe ya kama iji nnọkọ OAuth nke Cursor IDE ọzọ (onye na-eweta cursor, nke nwere ịdọ aka ná ntị gbasara ihe ize ndụ nke mmachibido). Ọ bụ ihe nkwụnye REST nkịtị (ọ nweghị ndabere native nke @cursor/sdk). approvePlan na-atụpụ njehie (ndị ọrụ Cursor na-arụ ọrụ n'onwe ha); listSources na-edepụta ebe nchekwa ndị igodo ahụ nwere ike iru. Cursor na-eweghachi enum ọnọdụ e ji mkpụrụedemede ukwu dee (CREATING/RUNNING/FINISHED/ERROR), nke a na-ejikọta n'ụzọ doro anya na CloudAgentStatus a na-ekekọrịta. Enwere ike iji nzere ọ bụla dochie baseUrl ka e nwee ike imezi ụdị/ụzọ API n'agbanweghị koodu.

Ụdị Ngalaba

Isi mmalite: 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; // ga-abụrịrị URL ziri ezi
  branch?: string;
}

export interface CloudAgentResult {
  prUrl?: string;
  prNumber?: number;
  commitMessage?: string;
  diffUrl?: string;
  summary?: string;
  duration?: number; // sekọnd, ọnụọgụ int dị mma
  cost?: number; // ọnụọgụ float dị mma
}

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 ime `task_...`
  providerId: "jules" | "devin" | "codex-cloud" | "cursor-cloud";
  externalId?: string; // id nke onye na-eweta upstream
  status: CloudAgentStatus;
  prompt: string; // mkpụrụedemede 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;
}

A na-ebupụ schema nkwado (CreateCloudAgentTaskSchema, UpdateCloudAgentTaskSchema) n'akụkụ ụdị ndị ahụ, ndị njikwa route na-ejikwa ha.

Ebe nchekwa data

Isi mmalite: src/lib/cloudAgent/db.ts — a na-emepụta tebụl ahụ naanị mgbe achọrọ ya site na createCloudAgentTaskTable() (a na-akpọkwa ya site na src/lib/cloudAgent/index.ts mgbe a na-ebubata modulu).

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 na-amanye ndepụta kọlụm ndị enyere ikike iji gbochie SQL injection: status, prompt, source, options, result, activities, error, completed_at. A na-ewepụ igodo ọ bụla ọzọ dị na mmelite akụkụ ahụ n'enweghị ọkwa.

REST API — Usoro ndụ ọrụ

Nyocha ikike: Endpoint /api/v1/agents/tasks* niile chọrọ nyocha ikike njikwa (requireCloudAgentManagementAuth na-ekpuchi requireManagementAuth sitere na src/lib/api/requireManagementAuth). A malitere ịmanye nke a mgbe commit 588a0333 ("fix(auth): chọọ nyocha ikike njikwa maka API ndị agent na cooldown").

Metọdị	Ụzọ	Ebumnuche
OPTIONS	/api/v1/agents/tasks	Nnyocha mbido CORS
GET	/api/v1/agents/tasks	Depụta ọrụ (nzacha: provider, status, limit≤500)
POST	/api/v1/agents/tasks	Mepụta ọrụ (na-eziga ya upstream ma na-echekwa ya)
DELETE	/api/v1/agents/tasks?id=...	Hichapụ ọrụ site na query id (anaghị akagbu nke upstream)
OPTIONS	/api/v1/agents/tasks/[id]	Nnyocha mbido CORS
GET	/api/v1/agents/tasks/[id]	Gụọ ọrụ + mekọrịta ọkwa site na upstream mgbe achọrọ
POST	/api/v1/agents/tasks/[id]	Omume: approve / message / cancel
DELETE	/api/v1/agents/tasks/[id]	Hichapụ ọrụ site na path id

Mepụta ọrụ

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
    }
  }'

Nzaghachi 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"
  }
}

Kwado atụmatụ

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

Zipụ ozi mgbakwunye

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

Kagbuo (ọkwa mpaghara naanị)

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

cancel na-agbanwe status ka ọ bụrụ "cancelled" na DB mpaghara mana ọ naghị akpọ onye na-eweta upstream — enweghị RPC nkwụsị na CloudAgentBase. Iji kwụsị ịkwụ ụgwọ upstream, kwụsị ọrụ ahụ na console nke onye na-eweta ahụ.

REST API — Nhazi Njikọ nke Ndị Na-enye Cloud

Ndị endpoint enyemaka ndị a dị n'okpuru src/app/api/cloud/ ka ndị ahịa dịpụrụ adịpụ (CLI, ngwa Electron, ma ọ bụ ndị ọrụ mmekọrịta) ji agụ metadata njikọ nke onye na-enye ọrụ ma chọpụta alias nke model. A na-eji API key nkịtị eme nkwenye njirimara ha (site na validateApiKey), ọ bụghị nkwenye njirimara nchịkwa nke endpoint ọrụ na-eji.

Usoro	Ụzọ	Ebumnuche
POST	/api/cloud/auth	Nyochaa API key, weghachite metadata njikọ ezoro akụkụ ya + alias model
PUT	/api/cloud/credentials/update	Mee accessToken / refreshToken / expiresAt ka ha dị ọhụrụ
POST	/api/cloud/model/resolve	Chọpụta alias model ka ọ bụrụ { provider, model }
GET	/api/cloud/models/alias	Depụta alias model niile
PUT	/api/cloud/models/alias	Tọọ alias model (ma mekọrịta ya na Cloud na-akpaghị aka ma ọ bụrụ na agbanyere ya)

/api/cloud/auth anaghị eweghachite apiKey / accessToken / refreshToken ndị na-ezoghị ezo. Ọ na-eweghachite hasApiKey, hasAccessToken, hasRefreshToken, na nlele ezoro akụkụ ya (maskedApiKey: mkpụrụedemede 4 mbụ + **** + mkpụrụedemede 4 ikpeazụ).

Nchọpụta Credentials

getCloudAgentCredentials(providerId) dị na src/lib/cloudAgent/api.ts:

1. Ọ na-ebunye njikọ ndị na-enye ọrụ na-arụ ọrụ site na getProviderConnections({ provider: providerId, isActive: true }).
2. Maka njikọ ọ bụla, ọ na-ebu ụzọ họrọ apiKey (e wepụla oghere ndị dị na nsọtụ ya). Ọ bụrụ na nke ahụ adịghị, ọ na-eji accessToken.
3. Ọ na-eweghachite token mbụ na-adịghị efu n'ụdị { apiKey: token }.
4. Ọ na-eweghachite null ma ọ bụrụ na ahụghị token a pụrụ iji — API ahụ na-aza 400 na "No active credentials configured for cloud agent provider: <id>".

Nke a pụtara na Cloud Agents na-ejikwa otu tebụl Provider Connection ahụ ndị na-enye LLM nkịtị na-eji. Iji gbanye Jules, mepụta njikọ na-arụ ọrụ nke nwere provider: "jules" na apiKey e dejupụtara.

Dashboard

Ebe mmalite: src/app/(dashboard)/dashboard/cloud-agents/page.tsx

Peeji React nwere "use client" nke:

• Na-edepụta ọrụ (a na-enyocha ha ugboro ugboro site na GET /api/v1/agents/tasks).
• Na-eziga ọrụ ọhụrụ site na fọm dabara na CreateCloudAgentTaskSchema.
• Na-egosi akara ọnọdụ (queued, running, awaiting_approval, completed, failed, cancelled) ma na-egosipụta usoro oge activities[].
• Na-egosipụta result.prUrl / commitMessage / summary mgbe status === "completed".

Njikọta na A2A

Enwere ike ikpughe Cloud Agents dịka nka A2A site n'ịdebanye aha nka A2A nke na-enyefe handler tasks/send ya n'aka getAgent(...).createTask(...) ma na-atụgharị event ọnọdụ ọrụ A2A ka ha kwekọọ na protocol JSON-RPC 2.0. Lee A2A-SERVER.md.

Ịgbakwunye Cloud Agent Ọhụrụ

1. Mepụta src/lib/cloudAgent/agents/<name>.ts nke na-agbatị CloudAgentBase.
2. Mejuputa createTask, getStatus, approvePlan (ma ọ bụ tụpụ njehie ma ọ bụrụ na ọ dịghị mkpa), sendMessage, listSources. Jiri this.mapStatus(...) maka ime ka ọnọdụ bụrụ otu ụdị.
3. Debanye ya aha na src/lib/cloudAgent/registry.ts n'okpuru providerId na-adịghị agbanwe agbanwe.
4. Gbatịa njikọ literal nke providerId na src/lib/cloudAgent/types.ts (CloudAgentTask.providerId na CreateCloudAgentTaskSchema).
5. Tinye onye na-enye ọrụ ahụ na src/shared/constants/providers.ts ma ọ bụrụ na ọ chọrọ ndekọ njikọ. Ndị na-enye ọrụ dabere na OAuth chọkwara src/lib/oauth/providers/.
6. Tinye ule n'okpuru tests/unit/cloud-agent-*.test.ts.
7. Melite akwụkwọ a na constant CLOUD_AGENTS nke dashboard.

Nhazi

Ihe Mgbanwe Gburuguru	Ebumnuche
DATA_DIR	Ebe nchekwa data SQLite nke nwere cloud_agent_tasks dị
JWT_SECRET	Achọrọ maka nkwenye njikwa na njedebe ọrụ
API_KEY_SECRET	Achọrọ iji zoo nzere njikọ ndị na-eweta ọrụ mgbe echekwara ha

Enweghị ihe mgbanwe gburugburu ebe obibi ọ bụla akọwapụtara maka Cloud-Agent ugbu a — ihe nzuzo niile dị na tebụl provider_connections.

Hụkwa

• A2A-SERVER.md
• API_REFERENCE.md
• SKILLS.md
• MEMORY.md
• Isi mmalite: src/lib/cloudAgent/
• Ụzọ: src/app/api/v1/agents/tasks/, src/app/api/cloud/
• Ogwe njikwa: src/app/(dashboard)/dashboard/cloud-agents/page.tsx