Agenți

Rulezi un agent server-side sincron sau ca run asincron pe care îl interoghezi, îl urmărești în stream sau îl anulezi.

API-ul de agenți împachetează bucla proprie a gateway-ului cu tool-uri. Rulările sincrone returnează răspunsul inline; cele asincrone returnează 202 cu un id pe care îl interoghezi, îl urmărești peste SSE (replay complet la reconectare — fără Last-Event-ID) sau îl anulezi. Concepte și limite: ghidul de agenți.

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul cererii

application/json

Definiții TypeScript

Folosește tipul request body în TypeScript.

Corpul lui POST /v1/agents/run.

task*string

Obiectivul, în limbaj natural. Devine tura utilizatorului.

Lungime1 <= length <= 64000

context?string

Material de sprijin opțional, adăugat după task sub un titlu ## Context.

Lungimelength <= 256000

system?string

Suprascriere opțională a prompt-ului de sistem, trimisă ca prim mesaj înaintea scheletului de agent.

Lungimelength <= 32000

model?string

Aliasul de model prin care se rutează.

Lungimelength <= 128

Implicit"codai"

max_steps?integer

Plafonul cerut pentru adâncimea buclei de agent. Validat, dar neaplicat — se folosește adâncimea de agent-mode a tier-ului.

Interval1 <= value <= 16

Corpul răspunsului

`application/json`

curl -X POST "https://example.com/v1/agents/run" \  -H "Content-Type: application/json" \  -d '{    "task": "Find the three most recent BNR EUR/RON rates and summarise the trend."  }'

{  "result": "string",  "status": "completed",  "usage": {    "prompt_tokens": 0,    "completion_tokens": 0  },  "model": "string",  "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7"}

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul cererii

application/json

Definiții TypeScript

Folosește tipul request body în TypeScript.

Corpul lui POST /v1/agents/runs; extinde cererea sincronă.

task*string

Obiectivul, în limbaj natural. Devine tura utilizatorului.

Lungime1 <= length <= 64000

context?string

Material de sprijin opțional, adăugat după task sub un titlu ## Context.

Lungimelength <= 256000

system?string

Suprascriere opțională a prompt-ului de sistem, trimisă ca prim mesaj înaintea scheletului de agent.

Lungimelength <= 32000

model?string

Aliasul de model prin care se rutează.

Lungimelength <= 128

Implicit"codai"

max_steps?integer

Plafonul cerut pentru adâncimea buclei de agent. Validat, dar neaplicat — se folosește adâncimea de agent-mode a tier-ului.

Interval1 <= value <= 16

budget_seconds?integer

Bugetul de timp cerut. Stocat (implicit 300), dar neaplicat.

Interval10 <= value <= 1800

client_request_id?string

Cheie de idempotență limitată la utilizatorul tău — o repetare întoarce id-ul rulării existente.

Lungimelength <= 200

Corpul răspunsului

`application/json`

curl -X POST "https://example.com/v1/agents/runs" \  -H "Content-Type: application/json" \  -d '{    "task": "Find the three most recent BNR EUR/RON rates and summarise the trend."  }'

{  "id": "3f9d2c1e-7b4a-4e0f-9a1d-2c5b6e7f8a90",  "status": "queued",  "poll": "/v1/agents/runs/3f9d2c1e-7b4a-4e0f-9a1d-2c5b6e7f8a90"}

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri query

days?integer

Lungimea ferestrei în zile, limitată la 1–90.

Interval1 <= value <= 90

Implicit7

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

`application/json`

curl -X GET "https://example.com/v1/agents/runs/stats"

{  "window_days": 1,  "total": 0,  "completed": 0,  "failed": 0,  "cancelled": 0,  "in_flight": 0,  "prompt_tokens": 0,  "completion_tokens": 0,  "avg_steps": 0,  "avg_latency_ms": 0}

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri de cale

id*string

UUID-ul rulării de agent întors de POST /v1/agents/runs.

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

`application/json`

curl -X GET "https://example.com/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "queued",  "task": "string",  "model": "string",  "result": "string",  "error": "string",  "step_count": 0,  "usage": {    "prompt_tokens": 0,    "completion_tokens": 0  },  "created_at": "2019-08-24T14:15:22Z",  "started_at": "2019-08-24T14:15:22Z",  "finished_at": "2019-08-24T14:15:22Z"}

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri de cale

id*string

UUID-ul rulării de agent întors de POST /v1/agents/runs.

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

`application/json`

curl -X GET "https://example.com/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/steps"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "steps": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "runId": "78c33d18-170c-44d3-a227-b3194f134f73",      "seq": 0,      "kind": "plan",      "summary": "string",      "detail": null,      "latencyMs": 0,      "createdAt": "2019-08-24T14:15:22Z"    }  ]}

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri de cale

id*string

UUID-ul rulării de agent întors de POST /v1/agents/runs.

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

`text/event-stream`

`application/json`

curl -X GET "https://example.com/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/stream"

"string"

Autorizare

bearerAuth

AutorizareBearer <token>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de /v1/realtime.

În: header

Parametri de cale

id*string

UUID-ul rulării de agent întors de POST /v1/agents/runs.

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

`application/json`

curl -X POST "https://example.com/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "cancelled"}

200application/json

400application/json

401application/json

402application/json

403application/json

429application/json

502application/json

202application/json

400application/json

401application/json

402application/json

403application/json

200application/json

401application/json

402application/json

200application/json

401application/json

402application/json

404application/json

200application/json

401application/json

402application/json

404application/json

200text/event-stream

401application/json

402application/json

404application/json

200application/json

401application/json

402application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`text/event-stream`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`