Tool-uri și sub-agenți

În interiorul unui run de agent — sau al unui chat completion cu x-codai-server-tools: 1 — modelul primește un set de tool-uri executate de gateway. Le apelează ca pe orice function tool; gateway-ul rulează în paralel fiecare apel dintr-o tură și trimite rezultatele înapoi. Nu vezi niciodată traficul de tool-uri decât dacă citești pașii run-ului.

Tool-uri built-in

Nivelul de tool-uri este o proprietate a cheii tale. none dezactivează orice tool executat; l1_http permite citiri din rețea; l3_shell și l4_browser deblochează rolurile mai grele de sub-agent.

spawn_agent

Când tool-urile server-side sunt pornite, modelul primește și spawn_agent. Spre deosebire de delegate_to_model (un singur completion), un copil pornit rulează propria buclă cu propriul context. Modelul alege un rol; gateway-ul alege tier-ul, nivelul de tool-uri și bugetul de pași pentru el.

Semantică:

• Paralel prin design. Fiecare apel spawn_agent dintr-o tură de asistent rulează concurent, și concurent cu celelalte apeluri de tool ale turei. Fan-out-ul e plafonat per tură (implicit 4); apelurile peste plafon primesc {"error":"delegation_fanout_capped"} ca rezultat de tool.
• Copiii nu pornesc niciodată alți copii. Un copil are spawn_agent eliminat, rulează pe alias-ul părintelui cu max_tokens: 4096 și se facturează ca o continuare a turei părintelui — nu pornește un task nou.
• Plafon de cost. Cheltuiala copiilor contează în plafonul de cost al cererii (implicit 5 USD); odată atins, spawn-urile ulterioare returnează {"error":"request_cost_ceiling"}.
• Forma rezultatului. Răspunsul copilului ajunge la părinte ca un mesaj tool obișnuit, prefixat cu SUB-AGENT[<role>] RESULT:.
• Cadre de progres. Pe un chat completion în stream, gateway-ul emite cadre vendor în delta SSE ca un UI să poată afișa carduri live de sub-agent: {"codai":{"event":"subagent_started","id","role","task"}} și {"codai":{"event":"subagent_done","id","role","ok","preview"}}. Le ignori dacă vrei doar text.
• Argumente invalide → {"error":"invalid_arguments"}; un copil care eșuează → {"error":"sub_agent_failed"}.

spawn_agent e injectat doar când cererea nu poartă tool-uri client-side proprii — dacă trimiți tools, tu deții bucla și gateway-ul stă deoparte.

Search și fetch independente — /v1/tools

Aceleași motoare de search și fetch sunt expuse ca endpoint-uri simple, ca un agent client-side să le poată folosi fără să treacă printr-un model. Ambele au nevoie doar de cheia ta codai_, contează în limitele tale de cereri per minut / per oră (header-ele X-RateLimit-*, 429 rate_limit_exceeded) și nu creează un rând de usage — nu sunt apeluri de model.

POST /v1/tools/search

curl https://ai.codai.ro/v1/tools/search \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "curs BNR euro azi", "max_results": 3, "freshness": "day" }'

Răspuns — fiecare rezultat este verificat: snippet-ul a fost găsit pe pagina live înainte să fie returnat.

{
  "results": [
    { "title": "Curs valutar BNR – 23 septembrie 2026", "url": "https://www.bnr.ro/…", "snippet": "1 EUR = 5,0912 RON …", "source": "bnr", "verified": true, "page_age": "2026-09-23" }
  ],
  "provider": "codai",
  "took_ms": 412,
  "cached": false,
  "coverage": 1,
  "sources_tried": ["bnr", "index"],
  "degraded": [],
  "intent": "currency"
}

Dacă serviciul de căutare nu e accesibil, gateway-ul răspunde 503 search_unavailable (type: server_error) — reîncearcă mai târziu; nu s-a taxat nimic.

POST /v1/tools/fetch

curl https://ai.codai.ro/v1/tools/fetch \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://nodejs.org/en/blog/release/v24.0.0", "max_chars": 4000, "focus": "ESM loader hooks" }'

{
  "url": "https://nodejs.org/en/blog/release/v24.0.0",
  "final_url": "https://nodejs.org/en/blog/release/v24.0.0",
  "title": "Node.js 24.0.0 (Current)",
  "byline": "The Node.js Project",
  "description": "…",
  "canonical": "https://nodejs.org/en/blog/release/v24.0.0",
  "lang": "en",
  "content_type": "text/html",
  "content": "## Module customization hooks\n\n…",
  "chars": 3811,
  "truncated": true,
  "took_ms": 688,
  "cached": false
}

Limite: timeout de 10 s, plafon de 3 MB pe corp, cel mult 3 redirect-uri și un guard SSRF la fiecare hop — URL-urile private, loopback sau cu credențiale, ori schemele non-HTTP, sunt 400 bad_request. Tipurile de conținut acceptate sunt HTML, text simplu, JSON, XHTML, Markdown și XML; un upstream non-2xx este 502 upstream_error cu details: { status, url }. Fetch-urile sunt puse în cache 15 minute, căutările 10.