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

Cloud Agents (Հայերեն)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇮🇩 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 · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Ճշմարտության աղբյուր՝ src/lib/cloudAgent/ և src/app/api/v1/agents/tasks/ Վերջին թարմացումը՝ 2026-06-28 — v3.8.40 (frontmatter-ի թարմացում, 4 գործակալ՝ ներառյալ cursor-cloud-ը)

OmniRoute-ը երկարատև առաջադրանքների տեսքով համակարգում է երրորդ կողմերի ամպային կոդավորման գործակալները (Codex Cloud, Cursor, Devin, Jules)։ Յուրաքանչյուր գործակալ հասանելի է միասնական միջերեսի միջոցով, որպեսզի հաճախորդները կարողանան ուղարկել հուշում + պահոցի URL և ստանալ արդյունքները՝ առանց մատակարարին հատուկ API-ների հետ աշխատելու։

Cloud Agent-ի առաջադրանքը սովորական զրույցի ամբողջացում չէ։ Այն կայուն, բազմաքայլ աշխատանքի միավոր է, որը կարող է տևել րոպեներից մինչև ժամեր, որպես արդյունք կարող է ստեղծել Pull Request և աջակցում է հետագա հաղորդագրություններին ու (որոշ մատակարարների դեպքում) պլանի հաստատման փուլերին։

Աղբյուր՝ diagrams/cloud-agent-flow.mmd

Աջակցվող գործակալներ

Մատակարարի ID	Դաս	Աղբյուր	Վերին հոսքի բազային URL	Պլանի հաստատում
jules	JulesAgent	src/lib/cloudAgent/agents/jules.ts	https://jules.googleapis.com/v1alpha	Այո
devin	DevinAgent	src/lib/cloudAgent/agents/devin.ts	https://api.devin.ai/v1	Այո
codex-cloud	CodexCloudAgent	src/lib/cloudAgent/agents/codex.ts	https://api.openai.com/v1/codex/cloud	Ոչ (ավտոմատ)
cursor-cloud	CursorCloudAgent	src/lib/cloudAgent/agents/cursor.ts	https://api.cursor.com/v0	Ոչ (ավտոմատ)

Ռեեստր՝ src/lib/cloudAgent/registry.ts — արտահանում է getAgent(providerId), getAvailableAgents() և isCloudAgentProvider(providerId)։ Ռեեստրը սովորական հիշողության մեջ պահվող Record<string, CloudAgentBase> է, որը լրացվում է մոդուլի բեռնման ժամանակ։

Ճարտարապետություն

Հաճախորդ (կառավարման վահանակ / CLI / API)
  → POST /api/v1/agents/tasks (պահանջվում է կառավարման նույնականացում)
    → CreateCloudAgentTaskSchema վավերացում (Zod)
    → registry.getAgent(providerId)
    → getCloudAgentCredentials(providerId)
      └─ ստանում է getProviderConnections({ provider, isActive: true })-ից
         (նախ apiKey, չլինելու դեպքում՝ accessToken)
    → agent.createTask({ prompt, source, options }, credentials)
      └─ HTTP POST հարցում վերին հոսքի մատակարարի API-ին
      └─ վերադարձնում է CloudAgentTask՝ ներքին id-ով + externalId-ով
    → insertCloudAgentTask(...)՝ cloud_agent_tasks-ում (SQLite)

Հարցումներ (ընթերցման ժամանակ ծույլ համաժամացում).
  GET /api/v1/agents/tasks/[id]
    → getCloudAgentTaskById(id)
    → agent.getStatus(externalId, credentials)  // թարմացնում է կարգավիճակը + գործողությունները
    → updateCloudAgentTask(...)՝ նոր կարգավիճակով, արդյունքով և completed_at-ով
    → վերադարձնում է սերիալացված առաջադրանքը

Փոխազդեցություններ.
  POST /api/v1/agents/tasks/[id]  մարմին՝ { action: "approve" | "message" | "cancel" }
    → agent.approvePlan(externalId, credentials)        «approve»-ի համար
    → agent.sendMessage(externalId, message, credentials) «message»-ի համար
    → կարգավիճակը փոխվում է «cancelled»-ի                 «cancel»-ի համար (միայն տեղային)

Համաժամացումը ծույլ է. յուրաքանչյուր GET /tasks/[id] հարցման ժամանակ կարգավիճակը թարմացվում է վերին հոսքի ծառայությունից։ Ֆոնային հարցումներ կատարող մեխանիզմ չկա։ Թարմ վիճակի կարիք ունեցող կառավարման վահանակները պետք է ողջամիտ պարբերականությամբ հարցումներ ուղարկեն GET վերջնակետին։

CloudAgentBase ինտերֆեյս

Աղբյուր՝ 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; // էվրիստիկ փոխակերպում՝ վերին հոսքի տողից → enum
  protected generateTaskId(): string; // `task_<ts>_<rand>`
  protected generateActivityId(): string; // `act_<ts>_<rand>`
}

CodexCloudAgent.approvePlan-ը միտումնավոր բացառություն է նետում․ Codex Cloud-ն ավտոմատ կերպով պլանավորում է և հաստատման փուլ չունի։ CodexCloudAgent.listSources-ը վերադարձնում է []։

CursorCloudAgent-ը կառավարում է Cursor-ի Background / Cloud Agents-ը դրա պաշտոնական REST API-ի (api.cursor.com/v0) միջոցով՝ օգտագործելով օգտատիրոջ կամ ծառայողական հաշվի API բանալի․ սա ավելի անվտանգ, առաջնային կողմի այլընտրանք է Cursor IDE-ի OAuth աշխատաշրջանի վերօգտագործմանը (պրովայդեր՝ cursor, որը պարունակում է արգելափակման ռիսկի մասին զգուշացում)։ Այն սովորական REST ադապտեր է (առանց @cursor/sdk բնիկ կախվածության)։ approvePlan-ը բացառություն է նետում (Cursor-ի գործակալներն աշխատում են ինքնավար կերպով), իսկ listSources-ը ցուցակում է բանալու միջոցով հասանելի պահոցները։ Cursor-ը վերադարձնում է ՄԵԾԱՏԱՌ կարգավիճակի enum-ներ (CREATING/RUNNING/FINISHED/ERROR), որոնք բացահայտ կերպով համապատասխանեցվում են ընդհանուր CloudAgentStatus-ին։ baseUrl-ը կարող է վերասահմանվել յուրաքանչյուր հավատարմագրի համար, որպեսզի API-ի տարբերակը/ուղին հնարավոր լինի ուղղել առանց կոդը փոխելու։

Տիրույթի տիպեր

Աղբյուր՝ 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; // պետք է վավեր URL լինի
  branch?: string;
}

export interface CloudAgentResult {
  prUrl?: string;
  prNumber?: number;
  commitMessage?: string;
  diffUrl?: string;
  summary?: string;
  duration?: number; // վայրկյաններ, դրական ամբողջ թիվ
  cost?: number; // դրական տասնորդական թիվ
}

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; // ներքին `task_...` id
  providerId: "jules" | "devin" | "codex-cloud" | "cursor-cloud";
  externalId?: string; // վերին հոսքի պրովայդերի id-ն
  status: CloudAgentStatus;
  prompt: string; // 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;
}

Վավերացման սխեմաները (CreateCloudAgentTaskSchema, UpdateCloudAgentTaskSchema) արտահանվում են տիպերի հետ միասին և օգտագործվում են երթուղիների մշակիչների կողմից։

Տվյալների բազա

Աղբյուր՝ src/lib/cloudAgent/db.ts — աղյուսակը ստեղծվում է ըստ անհրաժեշտության՝ createCloudAgentTaskTable()-ի միջոցով (այն նաև կանչվում է src/lib/cloudAgent/index.ts-ից՝ մոդուլի ներմուծման ժամանակ)։

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);

SQL ներարկումը կանխելու համար updateCloudAgentTask-ը կիրառում է սյունակների թույլատրելի ցանկ՝ status, prompt, source, options, result, activities, error, completed_at։ Մասնակի թարմացման մեջ առկա ցանկացած այլ բանալի աննկատ անտեսվում է։

REST API — Առաջադրանքի կենսացիկլ

Նույնականացում․ Բոլոր /api/v1/agents/tasks* վերջնակետերը պահանջում են կառավարման նույնականացում (requireCloudAgentManagementAuth-ը փաթաթում է src/lib/api/requireManagementAuth-ի requireManagementAuth-ը)։ Սա պարտադրվում է 588a0333 կոմիթից հետո («fix(auth): գործակալների և դադարի API-ների համար պահանջել կառավարման նույնականացում»)։

Մեթոդ	Ուղի	Նպատակ
OPTIONS	/api/v1/agents/tasks	CORS նախնական հարցում
GET	/api/v1/agents/tasks	Առաջադրանքների ցանկ (զտիչ՝ provider, status, limit≤500)
POST	/api/v1/agents/tasks	Առաջադրանքի ստեղծում (ուղարկում է վերին ծառայություն + պահպանում)
DELETE	/api/v1/agents/tasks?id=...	Առաջադրանքի ջնջում՝ ըստ հարցման id-ի (չի չեղարկում վերին ծառայությունում)
OPTIONS	/api/v1/agents/tasks/[id]	CORS նախնական հարցում
GET	/api/v1/agents/tasks/[id]	Առաջադրանքի ընթերցում + կարգավիճակի հետաձգված համաժամացում վերին ծառայությունից
POST	/api/v1/agents/tasks/[id]	Գործողություն՝ approve / message / cancel
DELETE	/api/v1/agents/tasks/[id]	Առաջադրանքի ջնջում՝ ըստ ուղու id-ի

Առաջադրանքի ստեղծում

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

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

Պլանի հաստատում

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

Հետագա հաղորդագրության ուղարկում

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

Չեղարկում (միայն տեղային կարգավիճակը)

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

cancel-ը տեղային տվյալների բազայում status-ը փոխում է "cancelled"-ի, սակայն չի կանչում վերին մատակարարին․ CloudAgentBase-ում ընդհատման RPC չկա։ Վերին ծառայությունում հաշվարկումը դադարեցնելու համար ավարտեք առաջադրանքը մատակարարի սեփական կառավարման վահանակում։

REST API — ամպային մատակարարի ենթակառուցվածք

src/app/api/cloud/-ում գտնվող այս օժանդակ վերջնակետերն օգտագործվում են հեռակա հաճախորդների (CLI-ի, Electron հավելվածի կամ համաժամացման աշխատողների) կողմից՝ մատակարարի միացման մետատվյալները կարդալու և մոդելների այլանունները լուծելու համար։ Դրանք վավերացվում են սովորական API բանալիով (validateApiKey-ի միջոցով), այլ ոչ թե առաջադրանքների վերջնակետերի կողմից օգտագործվող կառավարման վավերացմամբ։

Մեթոդ	Ուղի	Նպատակ
POST	/api/cloud/auth	Վավերացնել API բանալին, վերադարձնել քողարկված միացման մետատվյալները և մոդելների այլանունները
PUT	/api/cloud/credentials/update	Թարմացնել accessToken / refreshToken / expiresAt արժեքները
POST	/api/cloud/model/resolve	Մոդելի այլանունը լուծել որպես { provider, model }
GET	/api/cloud/models/alias	Թվարկել մոդելների բոլոր այլանունները
PUT	/api/cloud/models/alias	Սահմանել մոդելի այլանունը (և ավտոմատ համաժամացնել Cloud-ի հետ, եթե միացված է)

/api/cloud/auth-ը երբեք չի վերադարձնում չքողարկված apiKey / accessToken / refreshToken արժեքներ։ Այն վերադարձնում է hasApiKey, hasAccessToken, hasRefreshToken և քողարկված նախադիտում (maskedApiKey՝ առաջին 4-ը + **** + վերջին 4-ը)։

Հավատարմագրերի որոշում

getCloudAgentCredentials(providerId)-ը src/lib/cloudAgent/api.ts-ում՝

1. Բեռնում է մատակարարի ակտիվ միացումները՝ getProviderConnections({ provider: providerId, isActive: true })-ի միջոցով։
2. Յուրաքանչյուր միացման համար նախապատվությունը տալիս է apiKey-ին (սկզբի և վերջի բացատները հեռացված)։ Դրա բացակայության դեպքում օգտագործում է accessToken-ը։
3. Վերադարձնում է առաջին ոչ դատարկ թոքենը՝ փաթեթավորված որպես { apiKey: token }։
4. Վերադարձնում է null, եթե օգտագործելի թոքեն չի գտնվել. API-ն պատասխանում է 400 կոդով և "Ամպային գործակալի մատակարարի համար ակտիվ հավատարմագրեր կազմաձևված չեն՝ <id>" հաղորդագրությամբ։

Սա նշանակում է, որ Cloud Agents-ը կրկին օգտագործում է Provider Connection-ի նույն աղյուսակը, ինչ սովորական LLM մատակարարները։ Jules-ը միացնելու համար ստեղծեք ակտիվ միացում՝ provider: "jules" և լրացված apiKey արժեքով։

Վահանակ

Աղբյուր՝ src/app/(dashboard)/dashboard/cloud-agents/page.tsx

"use client" React էջ, որը՝

• Ցուցադրում է առաջադրանքները (GET /api/v1/agents/tasks-ի միջոցով պարբերաբար հարցում կատարելով)։
• Նոր առաջադրանքներ է ուղարկում ձևի միջոցով, որը համապատասխանեցվում է CreateCloudAgentTaskSchema-ին։
• Ցուցադրում է կարգավիճակի նշանները (queued, running, awaiting_approval, completed, failed, cancelled) և արտապատկերում activities[] ժամանակագիծը։
• Ցուցադրում է result.prUrl / commitMessage / summary արժեքները, երբ status === "completed"։

Ինտեգրում A2A-ի հետ

Cloud Agents-ը կարող է ներկայացվել որպես A2A հմտություններ՝ գրանցելով A2A հմտություն, որն իր tasks/send մշակիչը պատվիրակում է getAgent(...).createTask(...)-ին և A2A առաջադրանքի կարգավիճակի իրադարձությունները փոխակերպում JSON-RPC 2.0 արձանագրության։ Տե՛ս A2A-SERVER.md։

Նոր Cloud Agent-ի ավելացում

1. Ստեղծեք src/lib/cloudAgent/agents/<name>.ts, որը ժառանգում է CloudAgentBase-ը։
2. Իրականացրեք createTask, getStatus, approvePlan (կամ բացառություն նետեք, եթե կիրառելի չէ), sendMessage, listSources։ Կարգավիճակի նորմալացման համար օգտագործեք this.mapStatus(...)։
3. Գրանցեք src/lib/cloudAgent/registry.ts-ում՝ կայուն providerId-ի ներքո։
4. Ընդլայնեք src/lib/cloudAgent/types.ts-ում գտնվող providerId լիտերալների միավորումը (CloudAgentTask.providerId և CreateCloudAgentTaskSchema)։
5. Ավելացրեք մատակարարը src/shared/constants/providers.ts-ում, եթե դրա համար միացման գրառում է անհրաժեշտ։ OAuth-ի վրա հիմնված մատակարարներին անհրաժեշտ է նաև src/lib/oauth/providers/։
6. Ավելացրեք թեստեր tests/unit/cloud-agent-*.test.ts-ում։
7. Թարմացրեք այս փաստաթուղթը և վահանակի CLOUD_AGENTS հաստատունը։

Կազմաձևում

Միջավայրի փոփոխական	Նպատակ
DATA_DIR	cloud_agent_tasks-ը պարունակող SQLite տվյալների բազայի տեղադրությունը
JWT_SECRET	Պահանջվում է առաջադրանքների վերջնակետերում կառավարման նույնականացման համար
API_KEY_SECRET	Պահանջվում է մատակարարի կապի հավատարմագրերը պահեստում գաղտնագրելու համար

Այսօր Cloud-Agent-ին հատուկ միջավայրի փոփոխականներ չկան. յուրաքանչյուր գաղտնիք պահվում է provider_connections աղյուսակում։

Տես նաև

• A2A-SERVER.md
• API_REFERENCE.md
• SKILLS.md
• MEMORY.md
• Աղբյուր՝ src/lib/cloudAgent/
• Երթուղիներ՝ src/app/api/v1/agents/tasks/, src/app/api/cloud/
• Կառավարման վահանակ՝ src/app/(dashboard)/dashboard/cloud-agents/page.tsx