Construirea agentilor IA cu Claude Agent SDK: un ghid practic

Claude Agent SDK iti ofera acces programatic la acelasi agent loop care alimenteaza Claude Code. Agentii tai pot citi fisiere, executa comenzi shell, cauta pe web, modifica cod, apela API-uri externe prin servere MCP si orchestra sub-agenti - totul din cateva linii de TypeScript sau Python.

Spre deosebire de Client SDK-ul standard Anthropic, unde iti construiesti propriul tool loop, Agent SDK-ul gestioneaza intern executia tool-urilor, managementul contextului, retry-urile si orchestrarea. Tu descrii ce vrei, furnizezi uneltele, iar agentul se ocupa de restul.

Arhitectura

SDK-ul urmeaza un loop simplu: colecteaza context, actioneaza, verifica, repeta.

Punctul de intrare principal este query(), care returneaza un iterator asincron ce transmite mesaje in streaming pe masura ce agentul lucreaza. Fiecare mesaj iti spune ce face agentul: rationeaza, apeleaza un tool, primeste un rezultat sau livreaza output-ul final.

Pentru inceput

Instalare

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

Ai nevoie de o cheie API Anthropic configurata ca ANTHROPIC_API_KEY in mediul tau.

Primul tau agent

import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Find all TODO comments in the codebase and create a summary",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
});

for await (const message of conversation) {
  if (message.type === "assistant") {
    process.stdout.write(message.content);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("\nDone:", message.result);
  }
}

Atat. Agentul va folosi Glob pentru a gasi fisiere, Grep pentru a cauta pattern-uri TODO, Read pentru a inspecta potrivirile si va returna un sumar structurat. Nu scrii logica de orchestrare - SDK-ul se ocupa de ea.

Echivalent Python

from claude_agent_sdk import query

async for message in query(
    prompt="Find all TODO comments in the codebase and create a summary",
    options={"allowed_tools": ["Read", "Glob", "Grep"]},
):
    if message.type == "assistant":
        print(message.content, end="")
    if message.type == "result" and message.subtype == "success":
        print(f"\nDone: {message.result}")

Tool-uri integrate

SDK-ul vine cu aceleasi tool-uri disponibile in Claude Code:

Controlezi ce tool-uri poate folosi agentul prin allowedTools. Daca un tool nu e in lista, agentul nu il poate apela.

Moduri de permisiune

Deoarece agentii executa comenzi reale pe sisteme reale, permisiunile conteaza.

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",
  },
});

Pentru utilizarea in productie, ruleaza intotdeauna agentii in medii sandbox (containere, VM-uri) si foloseste modul de permisiune cel mai restrictiv care inca permite agentului sa-si faca treaba.

Crearea tool-urilor personalizate cu MCP

Adevarata putere a SDK-ului vine din extinderea agentilor cu propriile tale unelte. Tool-urile personalizate sunt definite ca servere MCP in-process - fara gestionarea subproceselor, fara overhead de retea.

Exemplu: tool meteo

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude"),
    longitude: z.number().describe("Longitude"),
  },
  async ({ latitude, longitude }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
    );
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `Current temperature: ${data.current.temperature_2m}C`,
        },
      ],
    };
  }
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});

for await (const message of query({
  prompt: "What's the weather like in Rome?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Tool-urile personalizate urmeaza conventia de denumire mcp__{nume_server}__{nume_tool}. Poti folosi caractere wildcard in allowedTools: "mcp__weather__*" permite toate tool-urile de pe serverul meteo.

Exemplu: tool de interogare a bazei de date

const queryDb = tool(
  "query_database",
  "Run a read-only SQL query against the application database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Validate: only allow SELECT queries
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

Conectarea serverelor MCP externe

Dincolo de tool-urile in-process, te poti conecta la orice server MCP existent - aceleasi servere care functioneaza cu Claude Desktop, Cursor si alti clienti MCP.

for await (const message of query({
  prompt: "Check the latest issues in the frontend repo and summarize them",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
      },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
  // ...
}

Poti combina mai multe servere MCP. Agentul vede toate tool-urile de pe toate serverele conectate si le foloseste dupa nevoie.

Orchestrare multi-agent

Pentru workflow-uri complexe, poti defini sub-agenti specializati carora agentul principal le deleaga. Fiecare sub-agent are propriul prompt, propriile tool-uri si propria arie de competenta.

for await (const message of query({
  prompt: "Review the PR, check for security issues, and update the changelog",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
    agents: [
      {
        name: "security-reviewer",
        description: "Reviews code for security vulnerabilities",
        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
        allowedTools: ["Read", "Glob", "Grep"],
      },
      {
        name: "changelog-writer",
        description: "Updates the CHANGELOG.md file based on recent changes",
        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
        allowedTools: ["Read", "Edit", "Bash"],
      },
    ],
  },
})) {
  // The parent agent will:
  // 1. Read the PR diff
  // 2. Delegate security review to security-reviewer
  // 3. Delegate changelog update to changelog-writer
  // 4. Synthesize results
}

Include "Agent" in allowedTools al parintelui pentru a activa delegarea. Sub-agentii ruleaza cu propriile tool-uri si nu pot accesa tool-urile parintelui decat daca li se acorda explicit acest drept.

Sesiuni si continuitate

Agentii pot mentine contextul intre mai multe interogari folosind sesiuni. Captureaza session_id din prima interactiune si transmite-l in resume pentru interogarile ulterioare.

let sessionId: string | undefined;

// First query
for await (const message of query({
  prompt: "Read the project structure and understand the architecture",
  options: { allowedTools: ["Read", "Glob", "Grep"] },
})) {
  if (message.type === "init") {
    sessionId = message.session_id;
  }
}

// Follow-up query (same session, full context preserved)
for await (const message of query({
  prompt: "Now refactor the auth module based on what you learned",
  resume: sessionId,
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  // Agent remembers the full project context from the first query
}

Claude Managed Agents

Daca nu vrei sa gazduiesti tu insuti infrastructura agentilor, Claude Managed Agents (lansati in aprilie 2026) ofera un serviciu cloud complet gestionat. Anthropic se ocupa de containere, de scaling si pune la dispozitie un API in streaming.

Diferenta esentiala: cu Agent SDK-ul, rulezi agent loop-ul in propria ta infrastructura. Cu Managed Agents, Anthropic gazduieste si ruleaza agentul pentru tine. Interactionezi printr-un API bazat pe sesiuni si primesti evenimente prin Server-Sent Events.

Preturi:

• Agent SDK: doar tarifele standard per token ale API-ului Claude. Gazduirea e in sarcina ta.
• Managed Agents: tarife per token plus 0,08 $ per ora de sesiune (facturat la milisecunda).

Bune practici pentru productie

1. Foloseste intotdeauna sandbox

Nu rula niciodata agenti cu permisiuni nelimitate pe o masina de productie. Foloseste containere (Docker, Fly.io, Modal) sau medii sandbox (E2B, Vercel Sandbox).

2. Limiteaza accesul la tool-uri

Urmeaza principiul privilegiului minim. Un agent care genereaza rapoarte nu are nevoie de Bash sau Write.

// Too permissive
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

// Better: only what's needed
allowedTools: ["Read", "Glob", "Grep"]

3. Foloseste hook-urile ca guardrails

Hook-urile iti permit sa interceptezi apelurile la tool-uri inainte si dupa executie. Foloseste-le pentru logging, validare si rate limiting.

const conversation = query({
  prompt: "Analyze the codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    hooks: {
      PreToolUse: async (toolName, input) => {
        console.log(`Tool call: ${toolName}`, input);
        // Return false to block the call
        if (toolName === "Bash" && input.command.includes("rm")) {
          return false;
        }
        return true;
      },
    },
  },
});

4. Gestioneaza erorile corespunzator

Agent loop-ul poate produce erori - esecuri ale tool-urilor, limite de rata ale API-ului, depasirea ferestrei de context. Verifica intotdeauna tipurile de mesaje.

for await (const message of conversation) {
  switch (message.type) {
    case "assistant":
      // Agent reasoning
      break;
    case "tool_use":
      // Agent is calling a tool
      break;
    case "result":
      if (message.subtype === "error") {
        console.error("Agent failed:", message.error);
      }
      break;
  }
}

5. Monitorizeaza consumul de token-uri

Agent loop-urile pot consuma o cantitate semnificativa de token-uri, mai ales cu codebase-uri mari. SDK-ul include compactarea automata a contextului, dar ar trebui totusi sa monitorizezi utilizarea.

Concluzie

Claude Agent SDK transforma un LLM dintr-o masina de raspuns la intrebari in ceva mai apropiat de un dezvoltator junior. Agentii tai pot citi, scrie, executa, verifica si itera - acelasi workflow pe care il urmeaza un om.

Incepe la scara mica: construieste un agent cu cateva tool-uri integrate. Apoi adauga tool-uri MCP personalizate pentru domeniul tau specific. Escaleaza catre orchestrarea multi-agent cand workflow-urile tale necesita specializare.

Agent loop-ul este acelasi care alimenteaza Claude Code. Daca poate crea software, agentii tai pot face la fel.

Checklist pentru inceput:

• Instaleaza SDK-ul (npm install @anthropic-ai/claude-agent-sdk)
• Configureaza ANTHROPIC_API_KEY in mediul tau
• Construieste un agent simplu cu tool-urile integrate (Read, Glob, Grep)
• Adauga un tool personalizat prin server MCP in-process
• Conecteaza un server MCP extern (GitHub, PostgreSQL, etc.)
• Implementeaza orchestrarea multi-agent cu sub-agenti
• Configureaza un mediu sandbox pentru productie
• Adauga hook-uri pentru logging si guardrails