Claude Agent SDK, autonóm ügynökök építése a gyakorlatban

Az utóbbi fél évben három KKV ügyfélnél tettünk éles ügynököket a Claude Agent SDK-ra. Az egyik egy ajánlat-előkészítő, a másik egy számlafeldolgozó, a harmadik egy belső dokumentum-kereső. Mind a három működik, és egyik sem azért működik, mert mágia van benne, hanem mert az SDK épp annyi struktúrát ad amennyi kell.

Mi az Agent SDK és mi nem

Az SDK egy tool-loop wrapper a Claude API köré. Definiálsz tool-okat (TypeScript függvényeket), a modell hívja őket, az SDK levezényli a ciklust. Nem LangChain, nincs benne agent típus, nincs benne chain, nincs benne prompt template rendszer. Egy session, egy modell, eszközök, leállási feltétel.

• Tool definition: név, leírás, JSON schema input, async handler.
• Session: rendszerüzenet, üzenettörténet, automatikus tool call kezelés.
• Stop conditions: turn limit, custom callback, idő.
• Streaming: tokenenként vagy tool eseményenként.

Egy minimális agent

import { Agent, tool } from '@anthropic-ai/agent-sdk';
import { z } from 'zod';

const searchInvoices = tool({
  name: 'search_invoices',
  description: 'Számla keresése partner neve alapján',
  input: z.object({ partner: z.string() }),
  handler: async ({ partner }) => {
    return await db.invoices.findByPartner(partner);
  },
});

const agent = new Agent({
  model: 'claude-sonnet-4-5',
  system: 'Magyar nyelvű könyvelési asszisztens vagy. Mindig erősítsd meg a partnernevet mielőtt számlát küldesz.',
  tools: [searchInvoices],
  maxTurns: 8,
});

const result = await agent.run('Küldd át a Bauer Kft. legutóbbi három számláját.');

Amit a gyakorlatban tanultunk

• A tool description fontosabb mint a system prompt. A modell ott dönti el, hogy egyáltalán nyúl-e az eszközhöz. Konkrét példa-inputtal írd.
• maxTurns mindig legyen, láttunk 40 fordulós ciklust egy rossz tool hibaüzenet miatt.
• A tool hibakezelése user-facing: ha hibát dobsz, a modell látja és visszaszól a felhasználónak. Ezt használd ki, ne csendes catch.
• Naplózz minden tool hívást Helicone-ba vagy Langfuse-ba. Production agent-et nem lehet figyelés nélkül üzemeltetni.
• A streaming jól néz ki demón, de production-ben gyakran csak a végeredmény kell. Ne over-engineerelj.

Mikor NE Agent SDK-t használj

Ha egy lépéses feladat, pl. „foglald össze ezt a dokumentumot”, akkor nem kell SDK, simán Messages API. Az SDK akkor éri meg, ha legalább 2-3 tool van és a sorrendet a modell dönti el. Egylépéses feladatra az SDK csak overhead.

Mibe kerül

A Sonnet 4.5 input tokenje pár dollár / millió, output sokszorosa. Egy átlagos belső agent session (5-8 tool hívás, közepes context) néhány centtől pár tíz centig fut. Egy 30 fős KKV-nál havi 100-300 USD szintű API költségről beszélünk, ha nincs caching. Promp caching-gel ennek a fele.