Run-uri de agent
Dai gateway-ului un obiectiv și îl lași să ruleze întreaga buclă de tool-uri server-side — routing, tool-uri built-in, sub-agenți, memorie.
POST /v1/chat/completions este un pass-through pur: codai nu injectează niciodată propriile tool-uri, tu deții bucla de tool-uri. Un run de agent inversează lucrurile. Tu trimiți un task, gateway-ul rulează bucla — alege modelul, execută tool-urile built-in, pornește sub-agenți tipizați, își amintește din memorie — și îți întoarce rezultatul.
Două forme, același corp de cerere:
Sincron — POST /v1/agents/run | Asincron — POST /v1/agents/runs | |
|---|---|---|
| Returnează | Răspunsul final într-un singur 200. | 202 { id, status: "queued" } imediat. |
| Potrivit pentru | Task-uri scurte, integrări simple, one-linere în SDK. | Task-uri lungi, orice vrei să interoghezi (poll), să urmărești în stream sau să anulezi. |
| Supraviețuiește unei deconectări a clientului | Nu — cererea HTTP este run-ul. | Da — run-ul e persistat; vezi run-uri asincrone. |
| Tip de cheie | Orice cheie codai_. | O cheie care aparține unui cont codai (nu o cheie compat legacy). |
Ambele au nevoie de un plan care include sub-agenți și tool-uri; altfel gateway-ul răspunde 403 forbidden — The agents API requires a tier with sub-agents and tools (Pro or above).
Corpul cererii
Proprietate
Tip
Un corp invalid este 400 bad_request, cu raportul pe câmpuri în error.details.
Un run sincron
curl https://ai.codai.ro/v1/agents/run \
-H "Authorization: Bearer $CODAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Ce s-a schimbat în release notes-urile Node.js 24 și afectează loader-ele ESM? Citează secțiunea.",
"model": "codai"
}'Răspuns:
{
"result": "Node.js 24 a mutat hook-urile loader-ului ESM off-thread implicit …",
"status": "completed",
"usage": { "prompt_tokens": 18422, "completion_tokens": 611 },
"model": "codai",
"event_id": "8b3f6d1e-…"
}event_id este rândul de usage pentru întregul run — îl trimiți la POST /v1/feedback sau îl cauți în hub. Răspunsul poartă și x-codai-upstream-model (ce model upstream a servit tura finală) și x-codai-event-id.
Un run sincron contează ca un task pentru plafonul de task-uri al planului tău, verificat înainte să pornească bucla. Dacă ai depășit plafonul, cererea este 429 quota_exceeded și nu rulează nimic — vezi task-uri și cheltuieli.
Ce face bucla
În interiorul unui run, modelul are tool-urile built-in — http_fetch, json_query, exec_python, web_search, memorie, skill-uri, orice servere MCP atașate cheii tale — plus spawn_agent pentru sub-agenți tipizați care rulează în paralel cu propriul lor context. Gateway-ul execută concurent fiecare apel de tool dintr-o tură, trimite rezultatele înapoi și se oprește când modelul produce un răspuns final. Cheltuiala sub-agenților contează în plafonul de cost al run-ului, iar copiii nu pornesc niciodată alți copii.
Aceeași buclă este cea pe care o activează x-codai-server-tools: 1 pentru POST /v1/chat/completions — run-urile de agent sunt pur și simplu ambalarea ei cu obiectivul pe primul loc.
Când să nu îl folosești
- Ai deja o buclă de tool-uri (un IDE, un framework, propriul tău agent) — apelezi
/v1/chat/completionsși ții tool-urile client-side. - Trebuie să trimiți tokeni în stream unui utilizator în timp real — chat completions cu
stream: true. Run-urile de agent transmit în stream pași, nu tokeni. - Trebuie să conduci o sesiune pe mai multe dispozitive — asta înseamnă sesiuni partajate, o suprafață diferită.