# Run-uri de agent (/ro/docs/agents)

Dai gateway-ului un obiectiv și îl lași să ruleze întreaga buclă de unelte server-side — routing, unelte built-in, sub-agenți, memorie.

`POST /v1/chat/completions` este un pass-through pur: codai nu injectează niciodată propriile unelte, tu deții bucla de unelte. Un **run de agent** inversează lucrurile. Tu trimiți o sarcină, gateway-ul rulează bucla — alege modelul, execută [uneltele built-in](./tools.mdx), 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 | Sarcini scurte, integrări simple, one-linere în SDK. | Sarcini 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](./async-runs.mdx). |
| 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 unelte; altfel gateway-ul răspunde `403 forbidden` — *The agents API requires a tier with sub-agents and tools (Pro or above).* (în mesajul gateway-ului, „Pro” înseamnă planul Starter sau mai sus.)

## Corpul cererii [#corpul-cererii]

<TypeTable
  type={{
    [`task`]: { type: 'string', description: 'Obiectivul. 1 – 64 000 de caractere.', required: true },
    context: { type: 'string', description: 'Material suplimentar adăugat după task sub un heading "## Context". Până la 256 000 de caractere.' },
    system: { type: 'string', description: 'Prompt-ul de sistem pentru run. Până la 32 000 de caractere.' },
    model: { type: 'string', description: 'Orice alias pe care îl poți apela. Run-ul se facturează ca acel alias.', default: "'codai'" },
    max_steps: { type: 'integer', description: 'Acceptat 1 – 16 pentru compatibilitate viitoare; gateway-ul aplică momentan propriul buget de pași și nu impune această valoare.' },
  }}
/>

Un corp invalid este `400 bad_request`, cu raportul pe câmpuri în `error.details`.

## Un run sincron [#un-run-sincron]

<Tabs items={['curl', 'TypeScript', 'Python']}>
<Tab value="curl">

```bash
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"
  }'
```

</Tab>
<Tab value="TypeScript">

```ts
import { Codai } from 'codai-sdk';

const codai = new Codai({ apiKey: process.env.CODAI_API_KEY! });

const run = await codai.agents.run({
  task: 'Ce s-a schimbat în release notes-urile Node.js 24 și afectează loader-ele ESM? Citează secțiunea.',
});

console.log(run.result);
console.log(run.model, run.usage, run.eventId);
```

</Tab>
<Tab value="Python">

```python
import os
from codai import Codai

client = Codai(api_key=os.environ["CODAI_API_KEY"])

run = client.agents_run(
    "Ce s-a schimbat în release notes-urile Node.js 24 și afectează loader-ele ESM? Citează secțiunea."
)

print(run.result)
print(run.model, run.usage, run.event_id)
```

</Tab>
</Tabs>

Răspuns:

```json
{
  "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`.

<Callout type="info">
Un run sincron contează ca **o sarcină** pentru plafonul de sarcini al planului tău, verificat înainte să pornească bucla. Dacă ai depășit plafonul, cererea este `429 quota_exceeded` și nu rulează nimic — vezi [sarcini și cheltuieli](./tasks-and-spend.mdx).
</Callout>

## Ce face bucla [#ce-face-bucla]

În interiorul unui run, modelul are [uneltele built-in](./tools.mdx) — `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 unealtă 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 [#când-să-nu-îl-folosești]

- Ai deja o buclă de unelte (un IDE, un framework, propriul tău agent) — apelezi `/v1/chat/completions` și ții uneltele 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](../sessions/index.mdx), o suprafață diferită.