Claude Agent SDK — produkční agenti bez přepisování smyčky | Blog

Shrnutí

Claude Agent SDK je toolkit od Anthropicu pro stavbu agentů, kteří běží na stejné smyčce jako Claude Code — tool use, oprávnění, hooks, subagenty, správa kontextu, streaming. Pokud jste někdy obalili messages.create do while smyčky a dolepili si vlastní routování nástrojů, SDK tenhle kód nahradí primitivy, které už jsou ověřené v boji. Tenhle post projde, co SDK dává, kdy ho nasadit a jak bych strukturoval první produkční agent.

Co SDK reálně je

Claude Agent SDK je knihovna (TypeScript i Python), která vystavuje primitivy, které Claude Code používá interně:

Agent loop — plánuj, jednej, pozoruj, opakuj, dokud úkol není hotový
Definice nástrojů — typované nástroje se schématy, handlery a bránami oprávnění
Hooks — pre/post intercepty, stejné tři typy, které vystavuje Claude Code
Subagenty — spawn izolovaných potomků s vlastním kontextem a nástroji
Paměť a komprese kontextu — automatická sumarizace, jak konverzace rostou
Streaming — token-po-tokenu výstup pro responzivní UI

Pokud jste dřív stavěli agentní frameworky, není to revoluce. Užitečné je, že to kodifikuje Anthropicův pohled na to, jak se má Claude-backed agent chovat — a ten pohled je stejný, který stojí za spolehlivostí Claude Code.

Kdy ho nasadit (a kdy ne)

Agent SDK má smysl, když:

Chcete chování agenta zabudované ve vlastním produktu (chatbot, autonomní worker, CI automatizace)
Stavíte něco, kam Claude Code nedosáhne — webhook handler, Slack bot, Kubernetes operátor
Potřebujete customizovat dostupnost nástrojů per-uživatel nebo per-tenant
Chcete agent loop, ale vlastní UI nebo pattern volání

Agent SDK nenasazujte, když:

Jste vývojář a chcete kódovat rychleji — to je Claude Code, ne SDK
Váš use case je jediný messages.create se statickým promptem — použijte základní Anthropic SDK
Potřebujete jen retrieval nad sadou dokumentů bez reálného tool use — obyčejný RAG setup je jednodušší

SDK se vyplatí ve chvíli, kdy váš agent potřebuje něco dělat — zapisovat soubory, volat API, spouštět příkazy, koordinovat podúkoly. Pokud potřebuje jen něco říct, přeplácíte komplexitou.

Jádro smyčky v ~30 řádcích

Minimální produkční agent v TypeScriptu:

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

const agent = new ClaudeAgent({
  model: 'claude-opus-4-7',
  systemPrompt: 'You are a support triage agent. Classify issues and open tickets.',
  tools: [
    tool({
      name: 'open_ticket',
      description: 'Open a support ticket in Linear.',
      input: z.object({
        title: z.string(),
        severity: z.enum(['low', 'medium', 'high']),
        body: z.string(),
      }),
      handler: async ({ title, severity, body }) => {
        const ticket = await linear.createIssue({ title, body, priority: severity });
        return { ticket_id: ticket.id, url: ticket.url };
      },
    }),
  ],
});

for await (const event of agent.run('User reports the dashboard is blank after login.')) {
  if (event.type === 'message') console.log(event.text);
  if (event.type === 'tool_call') console.log('→', event.name, event.input);
}

Tři věci, které stojí za zmínku:

Typované nástroje. Každý nástroj má Zod schema (nebo Pydantic v Pythonu). SDK validuje volání nástroje od modelu proti schématu ještě před spuštěním vašeho handleru. Nevalidní volání se zamítne a agent to zkusí znovu — váš kód nikdy neuvidí špatný vstup.

Streamované události. agent.run vrací async iterátor. V reálném čase dostanete události message, tool_call, tool_result, thinking a end. Napojte je na UI, log nebo Slack thread.

Jeden agent, mnoho runů. Jednou nakonfigurovaný agent umí opakovaně volat agent.run(...). Každý run je izolovaný, pokud explicitně nepředáte conversation id.

Hooks — stejný mechanismus jako Claude Code

SDK vystavuje PreToolUse, PostToolUse a Notification hooks se stejnou sémantikou jako Claude Code:

agent.addHook('PreToolUse', async ({ tool, input }) => {
  if (tool === 'open_ticket' && input.severity === 'high' && !isBusinessHours()) {
    return { decision: 'deny', reason: 'High-severity tickets require human approval outside business hours.' };
  }
  return { decision: 'approve' };
});

agent.addHook('PostToolUse', async ({ tool, result }) => {
  await auditLog.write({ tool, result, ts: Date.now() });
});

Je to ten samý vzor, který používám v Claude Code — systémové guardraily, které model nemůže obejít. Pravidlo je stejné: prompty jsou doporučení, hooks jsou smlouvy.

Subagenty — když jeden agent nestačí

Pokud váš úkol má podúlohy, kterým prospívá izolovaný kontext (jiné nástroje, jiný system prompt, jiný model), spawnujte subagenta:

const researcher = agent.subagent({
  systemPrompt: 'Research mode. Use web_search, return structured findings.',
  tools: [webSearchTool],
  model: 'claude-haiku-4-5-20251001',
});

const result = await agent.runWithSubagent(
  'Find the three most reliable sources on <topic> and summarize them.',
  researcher
);

Subagenti nevidí konverzaci rodiče, takže se nemohou rozejít. Vracejí jen informaci, kterou rodič potřebuje. Pro náklady: rodič na Opusu, subagenti na Haiku pro levný throughput — standardní vzor.

Správa kontextu

Dlouho běžící agent akumuluje tokeny. SDK posílá automatickou kompresi — když se kontext blíží limitu, starší tahy se sumarizují do stlačené formy, zatímco nejnovější aktivita zůstává doslovná.

const agent = new ClaudeAgent({
  model: 'claude-opus-4-7',
  // compaction: 'auto',  (default)
  contextWindowStrategy: {
    compactAt: 0.8,           // trigger na 80 % okna
    keepRecent: 10,           // posledních 10 zpráv nech doslovně
  },
});

Nevypínejte to, pokud nemáte důvod. Nestlačení agenti degradují predikovatelně — ztrácí instrukce z úvodních tahů, halucinují minulá rozhodnutí, „zapomínají" cíl.

Prompt caching — největší úspora nákladů

Jakákoli Agent SDK aplikace by měla mít zapnutý prompt caching. Velký system prompt + schémata nástrojů + CLAUDE.md-like kontext se na cache hitech účtuje za 10 % ceny input tokenu. Druhé a třetí volání v konverzaci se dramaticky zlevňují.

const agent = new ClaudeAgent({
  model: 'claude-opus-4-7',
  systemPrompt: [
    { type: 'text', text: loadLongSystemPrompt(), cache_control: { type: 'ephemeral' } },
  ],
  tools,  // definice nástrojů jsou taky cache-eligible
});

V praxi je to rozdíl mezi „agent SDK je drahý" a „agent SDK je levnější než najmout dalšího člověka na ten úkol". Měřte cache hit rate. Cílem je >70 % na tahu 2+.

Produkční checklist

Když pouštím Agent SDK službu do produkce, tohle jsou non-negotiables:

Hooks pro každý destruktivní nástroj. Cokoli, co zapisuje, maže nebo účtuje peníze, má PreToolUse bránu.
Audit log přes PostToolUse. Každé volání nástroje perzistované s inputem, outputem, ts a agent session id.
Timeouty na každé úrovni. Per tool call, per agent run, per session. Agenti umí smyčkovat — nedovolte jim smyčkovat navždy.
Prompt caching. Viz výše. Měřte, iterujte.
Mapování model tierů. Opus na těžké úkoly, Sonnet pro default loop, Haiku na klasifikaci a subagenty.
Strukturované chyby. Když nástroj selže, vraťte strukturovanou chybu, nad kterou agent může uvažovat, ne raw exception message.
Resumovatelné session. Ukládejte stav konverzace, aby přerušený run mohl pokračovat, ne startovat znovu.
Per-uživatelské scopování oprávnění. Nenasazujte jednoho god-agenta se všemi nástroji dostupnými každému volajícímu.

Zanedbejte cokoli z tohohle a poučíte se draze.

Kam to zapadá v širším obrazu

Agent SDK je „roll-your-own" větev stejného frameworku, na kterém stojí Claude Code. Claude Code je koncový produkt, SDK je primitiv. Pokud rozumíte, jak fungují Claude Code hooks a model subagentů, SDK vám přijde okamžitě povědomé — protože je to ta samá věc, jen vystavená jako knihovna.

Pokud plánujete agenta zabudovat do produktu a chcete druhý pár očí před nasazením, vedu workshopy přesně na tohle. me@jakubkontra.com

Claude Agent SDK — produkční agenti bez přepisování smyčky