Unelte ș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 unelte executate de gateway. Le apelează ca pe orice unealtă de tip funcție; gateway-ul rulează în paralel fiecare apel dintr-o tură și trimite rezultatele înapoi. Nu vezi niciodată traficul de unelte decât dacă citești pașii run-ului.

Unelte built-inCopiază linkul secțiunii

Nivelul de unelte este o proprietate a cheii tale. none dezactivează orice unealtă executată; l1_http permite citiri din rețea; l3_sandbox (sandbox în cloud: shell, Python, fișiere) și l4_browser deblochează rolurile mai grele de sub-agent.

spawn_agentCopiază linkul secțiunii

Când uneltele 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 unelte ș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 o sarcină 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ă unelte client-side proprii — dacă trimiți tools, tu deții bucla și gateway-ul stă deoparte.

Unelte web: un singur contract peste totCopiază linkul secțiunii

codai are trei unelte web, iar fiecare suprafață de agent le expune exact pe acestea — aceleași nume, aceleași scheme JSON, aceleași limite, aceleași endpoint-uri de gateway și aceeași redare a textului pentru model. Sursa unică este packages/agent-core/spec/tools-web.json; un test de paritate oprește build-ul când o suprafață se abate de la ea.

Reguli pe care le respectă fiecare suprafață:

• Gateway-ul este singurul backend de căutare pentru un utilizator autentificat. Un răspuns 4xx (refuz de regulă, argumente greșite, limită de rată) este final: modelul vede o linie ERROR <code>: <message> și nimic nu reîncearcă printr-un alt furnizor sau printr-un LLM.
• lang și country rămân nesetate dacă utilizatorul nu a cerut o anumită piață; gateway-ul le deduce din interogare.
• published_at nu este niciodată inventat: când o pagină nu are o dată de publicare cunoscută, rezultatul nu afișează niciuna. crawled_at este momentul în care codai a descărcat-o.
• Rândurile fundamentate de Google, când rulează fallback-ul automat, formează un bloc separat redat ca [G1]..[Gn], cu linia de atribuire.

PrețuriCopiază linkul secțiunii

Uneltele web nu sunt apeluri de model, deci nu scriu rând de usage; fiecare apel este contorizat separat și debitat în EUR din portofel:

Primele 1.000 de apeluri pe utilizator pe lună calendaristică UTC sunt gratuite, iar apelurile făcute în cadrul unei ture de agent codai (orice suprafață unde codai este modelul) nu se taxează niciodată. Erorile și răspunsurile din cache nu se taxează niciodată.

Search și fetch independente — /v1/toolsCopiază linkul secțiunii

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 — sunt contorizate ca apeluri de unelte web (vezi prețurile).

POST /v1/tools/searchCopiază linkul secțiunii

Orice filtru de dată (freshness, published_after, published_before) elimină paginile a căror dată de publicare nu se cunoaște — data descărcării nu este folosită niciodată în locul ei. Merg și operatorii de interogare: site:, -site:, filetype:, intitle:, inurl:, "frază exactă", -termen, A OR B, after:, before:, lang:xx.

curl https://ai.codai.ro/v1/tools/search \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "react compiler release", "include_domains": ["react.dev"], "published_after": "2026-01-01" }'

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

{
  "results": [
    {
      "title": "React Compiler v1.0",
      "url": "https://react.dev/blog/…",
      "snippet": "React Compiler is now stable …",
      "source": "docs",
      "verified": true,
      "published_at": "2026-02-10T00:00:00Z",
      "crawled_at": "2026-10-18T07:12:44Z"
    }
  ],
  "provider": "codai",
  "took_ms": 412,
  "cached": false,
  "coverage": 1,
  "sources_tried": ["docs", "index"],
  "degraded": [],
  "intent": "docs"
}

published_at este null când pagina nu are o dată de publicare cunoscută; page_age este un alias vechi, păstrat doar când data e cunoscută. degraded listează doar eșecurile reale ale surselor; codurile informative ale pipeline-ului ajung în notes. 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/fetchCopiază linkul secțiunii

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.

Textul descărcat este conținut terț. Suprafețele de agent îl încadrează ca nesigur și îi spun modelului să nu urmeze niciodată instrucțiunile găsite în el; fă la fel dacă îl dai tu unui model.

Cercetare aprofundată — /v1/researchCopiază linkul secțiunii

POST /v1/research pornește un job asincron: codai planifică mai multe căutări, citește cele mai bune pagini și scrie un raport în care fiecare afirmație citează [Sn], urmat de surse. Durează între 20 s și câteva minute. Referința completă: API-ul de cercetare.

const job = await codai.research.run({ question: 'Ce țări UE impun facturarea electronică B2B în 2026?', max_sources: 15 });
console.log(job.report, job.sources);