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 unelte. 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.

POST

/v1/agents/run

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

Corpul cererii

application/json

body

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

Rularea finalizată.

application/json

response

Răspunsul lui POST /v1/agents/run.

result*string

Răspunsul final al asistentului (șir gol când modelul nu a produs conținut).

status*"completed"

Valoare din"completed"

usage*

Numărul agregat de tokeni pentru întreaga rulare.

model*string

Modelul upstream concret care a servit tura finală.

event_id*|

Id-ul evenimentului de usage pentru corelarea feedback-ului; null când nu s-a scris niciunul.

Formatuuid

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

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

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

POST

/v1/agents/runs

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

Corpul cererii

application/json

body

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

Rularea a fost acceptată și pusă în coadă.

application/json

response

Răspunsul lui POST /v1/agents/runs (HTTP 202).

id*string

Formatuuid

status*"queued"

Întotdeauna queued la trimitere, chiar și când o repetare idempotentă nimerește o rulare care a avansat între timp.

Valoare din"queued"

poll*string

URL-ul relativ al endpoint-ului de interogare pentru această rulare.

Exemplu de cerere

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

Exemplu de cerere

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

Exemplu de răspunsSchemă

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

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

GET

/v1/agents/runs/stats

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri query

days?integer

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

Interval1 <= value <= 90

Implicit7

Parametri header

Corpul răspunsului

Agregatele pentru fereastră.

application/json

response

Agregate peste rulările tale din fereastră. Doar window_days și total sunt garantate; celelalte câmpuri lipsesc pentru cheile legacy de compatibilitate, care nu pot deține rulări persistate.

window_days*integer

Interval1 <= value <= 90

total*integer

Interval0 <= value

completed?integer

Interval0 <= value

failed?integer

Interval0 <= value

cancelled?integer

Interval0 <= value

in_flight?integer

Rulări aflate acum în queued sau running.

Interval0 <= value

prompt_tokens?integer

Interval0 <= value

completion_tokens?integer

Interval0 <= value

avg_steps?integer

Media rotunjită a lui step_count.

Interval0 <= value

avg_latency_ms?integer

Media rotunjită a lui finished_at - started_at peste rulările terminate.

Interval0 <= value

Exemplu de cerere

curl -X GET 'https://ai.codai.ro/v1/agents/runs/stats'

Exemplu de cerere

curl -X GET 'https://ai.codai.ro/v1/agents/runs/stats'

Exemplu de răspunsSchemă

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

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

GET

/v1/agents/runs/{id}

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

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

Formatuuid

Parametri header

Corpul răspunsului

Rularea.

application/json

response

Vederea de interogare a unei rulări persistate (GET /v1/agents/runs/{id}).

id*string

Formatuuid

status*AgentRunStatus

Ciclul de viață al rulării — queued → running → una dintre completed, failed, cancelled.

Valoare din"queued""running""completed""failed""cancelled"

task*string

Obiectivul trimis, neschimbat.

model*|

Aliasul de model cerut (codai când a fost omis la trimitere).

result*|

Răspunsul final; setat doar după ce status devine completed.

error*|

Mesajul de eșec (≤ 2000 de caractere); setat doar când status este failed.

step_count*integer

Pașii de buclă executați până acum. Nu este incrementat de executorul curent.

Interval0 <= value

usage*

Numărul agregat de tokeni pentru întreaga rulare.

created_at*string

Formatdate-time

started_at*|

Când a fost preluată execuția; null cât timp e queued.

Formatdate-time

finished_at*|

Setat la completed, failed și cancelled.

Formatdate-time

Exemplu de cerere

curl -X GET 'https://ai.codai.ro/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08'

Exemplu de cerere

curl -X GET 'https://ai.codai.ro/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08'

Exemplu de răspunsSchemă

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

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

GET

/v1/agents/runs/{id}/steps

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

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

Formatuuid

Parametri header

Corpul răspunsului

Urma de pași.

application/json

response

id*string

Id-ul rulării.

Formatuuid

steps*array<>

Exemplu de cerere

curl -X GET 'https://ai.codai.ro/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/steps'

Exemplu de cerere

curl -X GET 'https://ai.codai.ro/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/steps'

Exemplu de răspunsSchemă

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

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

GET

/v1/agents/runs/{id}/stream

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

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

Formatuuid

Parametri header

Corpul răspunsului

Stream SSE; vezi descrierea pentru numele evenimentelor și payload-uri.

response?stringtext/event-stream

Exemplu de cerere

curl -X GET 'https://ai.codai.ro/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/stream'

Exemplu de cerere

curl -X GET 'https://ai.codai.ro/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/stream'

Exemplu de răspunsSchemă

"string"

"string"

POST

/v1/agents/runs/{id}/cancel

Autorizare

bearerAuth

headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

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

Formatuuid

Parametri header

Corpul răspunsului

Rularea este acum anulată.

application/json

response

id*string

Formatuuid

status*"cancelled"

Valoare din"cancelled"

Exemplu de cerere

curl -X POST 'https://ai.codai.ro/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel'

Exemplu de cerere

curl -X POST 'https://ai.codai.ro/v1/agents/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel'

Exemplu de răspunsSchemă

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

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

Agenți

AutorizareCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul cereriiCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri queryCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

AutorizareCopiază linkul secțiunii

Parametri de caleCopiază linkul secțiunii

Parametri headerCopiază linkul secțiunii

Corpul răspunsuluiCopiază linkul secțiunii

Autorizare

Parametri header

Corpul cererii

Corpul răspunsului

Autorizare

Parametri header

Corpul cererii

Corpul răspunsului

Autorizare

Parametri query

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul răspunsului

Autorizare

Parametri de cale

Parametri header

Corpul răspunsului