Claude Agent SDK: codul pentru un agent AI propriu, de la primul script la producție

Claude Agent SDK îți dă codul pentru un agent AI propriu. Câteva linii de Python sau TypeScript pornesc aceeași buclă de agent care rulează în Claude Code. Pentru producție mai adaugi trei lucruri: instrumentele potrivite, permisiuni stricte și legătura cu sistemele firmei prin MCP.

Claude Agent SDK este o bibliotecă Anthropic care rulează binarul Claude Code. Îți dă aceleași instrumente, aceeași buclă de agent și aceeași gestionare a contextului, programabile din Python și TypeScript. Un agent, în sensul folosit de Anthropic, este o aplicație care duce la capăt o sarcină. Agentul își planifică singur pașii și apelează instrumente care citesc fișiere, rulează comenzi sau editează cod.

Postarea de față este partea a doua dintr-o serie de trei despre agenți AI în practică. Prima parte arată cum faci primul agent AI cu Claude, fără cod. A treia parte va trata rularea agenților în producție. Ghidul acesta e scris pentru firmele care au un programator în echipă sau un partener tehnic.

Parcurgi, în ordine, instalarea, agentul minim, conectarea unui server MCP și aprobarea unui om înainte de acțiunile sensibile. La final vezi cum arată în SDK agentul pentru e-mailurile furnizorilor din prima parte.

Claude Agent SDK îți dă gata făcută partea grea a unui agent: bucla de lucru. Anthropic descrie bucla în patru pași: adună contextul, acționează, verifică munca, apoi repetă. SDK-ul se ocupă de orchestrare, de rularea instrumentelor, de gestionarea contextului și de reîncercări. Codul tău doar citește fluxul de mesaje.

Principiul de proiectare, spune Anthropic, este să le dai agenților un calculator, ca să lucreze cum lucrează oamenii. SDK-ul s-a numit inițial Claude Code SDK și a fost redenumit pe 29 septembrie 2025. Anthropic îl folosea deja intern și pentru cercetare, video și notițe, nu doar pentru cod.

Piesele pe care le primești în SDK sunt acestea:

• Instrumente încorporate, precum Read, Edit, Bash, Glob și Grep, pe care Claude le rulează direct, fără să le implementezi tu.
• Hooks, adică bucăți de cod propriu care rulează în momente cheie din viața agentului.
• Subagenți, porniți de agentul principal, fiecare cu propria fereastră de context, care trimit înapoi doar informația relevantă.
• Servere MCP, prin care agentul ajunge la instrumente și date din afara lui.
• Permisiuni și sesiuni, care controlează ce are voie agentul și îi păstrează istoricul.

Când contextul se apropie de limită, funcția de compactare rezumă automat mesajele anterioare. Skills, comenzile și memoria se încarcă automat din folderul .claude/ al proiectului și din ~/.claude/, la fel ca în Claude Code.

Instalarea Claude Agent SDK cere o singură comandă și o variabilă de mediu. Ai nevoie de Python 3.10 sau mai nou, ori de Node.js 18 sau mai nou, și de un cont Anthropic. Pachetul Python se numește claude-agent-sdk, pe PyPI. Varianta TypeScript este @anthropic-ai/claude-agent-sdk, pe npm.

Comenzile de mai jos instalează pachetul Python și pun cheia API în mediul terminalului. Le rulezi în terminal, din folderul proiectului.

pip install claude-agent-sdk
export ANTHROPIC_API_KEY=your-api-key

În locul textului your-api-key pui cheia ta API. SDK-ul citește cheia din mediul procesului care rulează agentul. SDK-ul nu încarcă automat fișiere .env, deci pe server setezi cheia explicit. Ambele pachete includ un binar Claude Code nativ, așa că de obicei nu instalezi separat Claude Code. Excepția apare când pip instalează sursa în loc de pachetul pentru platformă, de exemplu pe Windows ARM64.

Pe partea de contract, folosirea SDK-ului intră sub Termenii Comerciali Anthropic, inclusiv când agentul servește clienții tăi. Nu poți oferi utilizatorilor autentificare cu contul claude.ai, decât cu aprobare prealabilă. Poți numi produsul „Numele tău Powered by Claude”, dar nu „Claude Code” sau „Claude Code Agent”. SDK-ul acceptă și autentificarea prin Amazon Bedrock, Claude Platform on AWS, Google Cloud și Microsoft Foundry.

Agentul minim din documentația Claude Agent SDK citește un fișier de cod, caută erori care l-ar bloca și le repară. Nu e un caz de business, dar arată toate piesele de bază într-un singur loc.

Scriptul de mai jos este exemplul din quickstart, cu comentariile traduse. Îl salvezi, de exemplu, ca agent.py, în folderul unde se află utils.py, și îl rulezi cu python agent.py.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # Bucla agentică: transmite mesajele pe măsură ce Claude lucrează
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Aprobă automat aceste instrumente
            permission_mode="acceptEdits",  # Aprobă automat editările de fișiere
        ),
    ):
        # Afișează textul lizibil
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Raționamentul lui Claude
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # Instrumentul apelat
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Rezultatul final


asyncio.run(main())

Funcția query este punctul de intrare: pornește bucla agentului și întoarce mesajele pe măsură ce Claude lucrează. Parametrul prompt spune ce vrei, iar Claude alege singur instrumentele. În options stă configurarea.

Liniile pe care le schimbi în scriptul minim sunt trei:

• prompt, cu sarcina ta, scrisă ca pentru un coleg.
• allowed_tools, lista instrumentelor aprobate automat. Read, Glob și Grep dau doar citire și analiză. Cu Edit, agentul poate și modifica. Cu Bash în plus, ai automatizare completă.
• permission_mode. Modul acceptEdits aprobă automat editările de fișiere din folderul de lucru.

Implicit, agentul vede fișierele din folderul din care rulează și din subfolderele lui. Pentru un agent de business, începe cu o listă doar de citire. Adaugi dreptul de scriere după ce ai văzut ce face agentul.

Un agent devine util în firmă când ajunge la datele ei, iar calea standard este MCP. Model Context Protocol (MCP) este un standard deschis prin care agenții AI se conectează la instrumente și surse de date externe. Un server MCP poate rula ca proces local, poate fi accesat prin HTTP sau poate fi definit direct în codul aplicației.

Scriptul următor, din pagina Anthropic despre MCP, conectează agentul la serverul de documentație Claude Code prin HTTP. Îl rulezi la fel ca primul agent.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "claude-code-docs": {
                "type": "http",
                "url": "https://code.claude.com/docs/mcp",
            }
        },
        allowed_tools=["mcp__claude-code-docs__*"],
    )

    async for message in query(
        prompt="Use the docs MCP server to explain what hooks are in Claude Code",
        options=options,
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

În practică, în locul serverului de documentație pui serverul MCP al CRM-ului tău, de exemplu Zoho CRM, sau pe cel al căsuței de e-mail. Schimbi cheia „claude-code-docs” cu un nume scurt, de exemplu „crm”, și adresa din url. Numele instrumentelor urmează tiparul mcp__<server>__<instrument>, deci linia allowed_tools se schimbă odată cu numele serverului.

Câteva reguli MCP contează în producție. Instrumentele MCP cer permisiune explicită: fără ea, Claude le vede, dar nu le poate apela. Modul acceptEdits nu le aprobă automat. O intrare neancorată, precum mcp__*, este ignorată la pornire și nu aprobă nimic. Steluța de după numele serverului aprobă toate instrumentele lui, deci la un CRM e mai sigur să enumeri doar instrumentele de citire.

Autentificarea la serverul MCP o rezolvi dinainte. SDK-ul nu deschide un browser și nu rulează un flux OAuth interactiv, deși specificația MCP acceptă OAuth 2.1. Conexiunea expiră implicit după 30 de secunde. După cinci încercări de reconectare eșuate, serverul raportează „failed” sau „needs-auth”.

Permisiunile decid ce face agentul fără să întrebe pe nimeni, iar SDK-ul le verifică într-o ordine fixă, în șase pași. Întâi rulează hooks. Urmează regulile deny, regulile ask, modul de permisiune și regulile allow. Ce nu s-a rezolvat până aici ajunge la callback-ul canUseTool, adică la decizia unui om sau a codului tău.

Modul de permisiune stabilește cât control uman are agentul. Tabelul compară modurile pe care le vei întâlni:

Regula de bază: nu folosi bypassPermissions pentru nimic care atinge clienți sau bani. Lista allowed_tools nu limitează acest mod. Cu allowed_tools=["Read"] și bypassPermissions, SDK-ul aprobă tot, inclusiv Bash, Write și Edit.

Regulile deny rămân frâna sigură. O regulă deny care se potrivește blochează instrumentul chiar și în bypassPermissions. O regulă pe numele simplu, precum disallowed_tools=["Bash"], scoate instrumentul din cerere, așa că Claude nici nu îl vede. Modul se poate schimba și în timpul sesiunii, cu set_permission_mode() în Python.

Callback-ul canUseTool este funcția prin care un om aprobă sau refuză o acțiune a agentului înainte să ruleze. Primește numele instrumentului și datele de intrare și oprește agentul până primește un răspuns. Tot el prinde întrebările de clarificare pe care Claude le pune prin instrumentul AskUserQuestion.

Fragmentul de mai jos, în TypeScript, este partea de decizie din exemplul Anthropic. Îl pui în obiectul de opțiuni al funcției query. Partea omisă, marcată cu comentariu, afișează acțiunea unui om și citește răspunsul în variabila response.

canUseTool: async (toolName, input) => {
  // ... arată acțiunea propusă unui om și citește răspunsul ...
  if (response.toLowerCase() === "y") {
    return { behavior: "allow", updatedInput: input };
  } else {
    return { behavior: "deny", message: "User denied this action" };
  }
}

Dacă răspunsul este „y”, agentul primește behavior: "allow" și datele neschimbate. Altfel primește "deny" și un mesaj. Claude citește mesajul și își poate schimba abordarea, deci scrie acolo motivul real, de exemplu „prețul nu e confirmat”. Poți înlocui „y” cu butoanele din aplicația ta.

Trei detalii despre canUseTool contează în producție. Callback-ul nu pornește niciodată pentru instrumentele aprobate automat, deci ce pui în allowed_tools nu ajunge la om. Callback-ul poate aștepta la nesfârșit, iar agentul rămâne oprit. Pentru aprobări care durează ore, un hook PreToolUse poate întoarce decizia defer, ca procesul să se închidă și să reia mai târziu din sesiunea salvată. Hook-ul PermissionRequest poate trimite o notificare pe Slack, e-mail sau push când agentul așteaptă.

Agentul pentru furnizori din prima parte a seriei citește e-mailurile primite, caută datele furnizorului în CRM și redactează un răspuns. În Claude Agent SDK, același agent se construiește din piesele prezentate mai sus: servere MCP, o listă scurtă de instrumente aprobate și aprobarea unui om.

Configurarea agentului pentru furnizori arată astfel, descrisă în cuvinte:

1. În mcp_servers declari două servere: cel al CRM-ului și cel al căsuței de e-mail, de exemplu Zoho Mail.
2. În allowed_tools pui doar instrumentele de citire: căutarea furnizorului, a comenzilor și citirea e-mailului.
3. Instrumentul care trimite e-mailul rămâne în afara listei, așa că fiecare trimitere ajunge la canUseTool și la un om.
4. Dacă vrei ca agentul doar să redacteze, pui trimiterea în disallowed_tools, iar Claude nu o mai vede deloc.
5. Lași modul de permisiune pe default, nu pe bypassPermissions.

Instrucțiunile de ton și regulile firmei merg în opțiunea systemPrompt. Un e-mail de la furnizor este text venit din afară, deci poate conține instrucțiuni ascunse pentru agent. Ghidul despre cum protejezi agenții Claude de prompt injection arată ce verificări adaugi.

La Svennis, la un agent de acest fel scoatem trimiterea de e-mail din lista de instrumente aprobate și o lăsăm la aprobarea unui om din echipă. Mutăm trimiterea în lista aprobată abia după ce echipa a verificat o perioadă răspunsurile redactate și nu mai are corecturi de fond.

Costul unui agent construit cu Claude Agent SDK vine din tokenii consumați de model. Un token este o bucată de text procesată de model, cam 4 caractere sau 0,75 cuvinte în engleză. Prețurile Anthropic sunt în dolari americani, pe milion de tokeni, fără taxe:

Două reduceri contează la agenți. Batch API, pentru cereri procesate asincron, oferă 50% reducere la intrare și la ieșire. O citire din cache-ul de prompt costă 10% din prețul standard de intrare.

Alternativa găzduită este Claude Managed Agents, aflat în beta. Serviciul este un cadru de agent gata construit, rulat de Anthropic, potrivit pentru sarcini lungi și asincrone. Sesiunile rulează într-un sandbox din cloud-ul Anthropic sau într-un sandbox găzduit la tine. Plătești tokenii la prețul standard plus 0,08 USD pe oră de sesiune, cât timp sesiunea rulează. Rulările recurente pot fi programate după un orar cron.

Claude Managed Agents are și limite clare. Toate cererile au nevoie de antetul beta managed-agents-2026-04-01. Serviciul nu este eligibil acum pentru Zero Data Retention, adică păstrarea zero a datelor, pentru că reține starea sesiunilor. Dacă păstrarea datelor contează, SDK-ul pe serverul tău îți lasă mai mult control.

Pentru o firmă din România, întrebarea practică despre Claude Agent SDK este cine scrie, rulează și întreține codul. SDK-ul cere un programator sau un partener tehnic care administrează un server cu Python 3.10 sau Node.js 18, cheia API și conexiunile MCP. Fără acest om, agentul rămâne un demo.

Bugetul se face în dolari. Prețurile Anthropic sunt în USD, fără TVA, deci costul în lei variază cu cursul. Relația contractuală se bazează pe Termenii Comerciali Anthropic, așa că îi citești cu juristul înainte ca agentul să atingă date de clienți.

Datele personale cer o decizie înainte de cod. Stabilește ce date are voie agentul să vadă, la fel cum ai stabili pentru un angajat nou. Politica AI pe categorii de date e un punct bun de pornire. Dacă agentul ia decizii care afectează oameni, verifică obligațiile din AI Act, Regulamentul UE 2024/1689, adnotat în română.

Modelele Claude sunt disponibile și pe Amazon Bedrock și Google Cloud, iar SDK-ul se poate autentifica prin aceste platforme. Dacă firma are deja un cont de cloud la unul dintre ei, discută varianta cu partenerul tehnic înainte să alegi.

Drumul de la demo la un agent Claude Agent SDK în producție poate fi parcurs în câțiva pași mici, fiecare verificabil:

1. Rulează agentul minim din quickstart pe un folder de test, ca să vezi bucla la lucru.
2. Alege un singur proces, de exemplu răspunsurile către furnizori, și scrie ce are voie agentul să citească și să facă.
3. Conectează serverul MCP al CRM-ului doar cu instrumente de citire în allowed_tools.
4. Lasă orice acțiune spre clienți sau bani la canUseTool, cu mesaje de refuz clare.
5. Alege modelul după volum și calculează costul pe o lună de trafic real.
6. Păstrează modul default și regulile deny; nu folosi bypassPermissions în afara testelor.

Dacă nu știi încă dacă firma are datele și procesele pregătite pentru un agent, începe cu evaluarea pregătirii companiei pentru AI. A treia parte a seriei va arăta cum rulezi agenții în producție.