Claude Agent SDK — pierwsze starcie z budową własnego agenta

Anthropic Agent SDK to zestaw narzędzi do budowy własnego agenta na Claude API. Nie zastępuje Claude Code, ale daje go zbudować od zera dla konkretnego use case'u. Po tygodniu eksperymentów mam pierwsze obserwacje.

Co to jest

Agent SDK opakowuje Claude API + tool use + state management w wygodne API. Zamiast klepać własną pętlę "send message → tool call → response → continue", dostajesz Agent class:

from anthropic.agent import Agent
 
agent = Agent(
    model="claude-opus-4-7",
    tools=[bash_tool, file_tool, web_search],
    system="You are a code reviewer. Focus on security."
)
 
result = await agent.run(
    "Review the auth flow in my repo",
    max_turns=20
)

SDK zarządza:

• pętlą tool use
• prompt cachingiem
• compactowaniem konwersacji gdy się robi długa
• error handlingiem
• streamem outputów

Dlaczego nie Claude Code

Claude Code = uniwersalny agent dla developerów. Agent SDK = budujesz wąskiego specjalistę.

Wybierasz SDK gdy budujesz produkt który ma swój narrow scope. Np. "agent który robi research dla cold outreach" albo "agent który analizuje screenshoty UI i sugeruje poprawki".

Mój pierwszy use case: outreach researcher

Zbudowałem prostego agenta który dla podanej firmy zbiera research:

from anthropic.agent import Agent
from anthropic.tools import web_search, bash, file_write
 
researcher = Agent(
    model="claude-sonnet-4-6",
    tools=[web_search, bash, file_write],
    system="""You research companies for cold outreach.
    For each input company:
    1. Search web for their site, social media, recent news
    2. Extract: name, address, services, brand voice signals
    3. Save to /tmp/research/{slug}.json
 
    Return ONLY the JSON path. No commentary."""
)
 
result = await researcher.run(
    "Research: Pasieka Przygórze, Mszana Dolna, Polska"
)
print(result.output)  # /tmp/research/pasieka-przygorze.json

Agent dostaje minimalny system prompt + 3 narzędzia. Nie ma Bash z dostępem do całego systemu, nie ma file editing, tylko search, write i bash.

Customowe narzędzia

SDK pozwala definiować własne tools:

from anthropic.tools import tool
 
@tool
async def vikunja_create_task(
    title: str,
    project_id: int,
    due_date: str | None = None
) -> dict:
    """Create a task in Vikunja."""
    response = await httpx.post(
        f"{VIKUNJA_URL}/api/v1/projects/{project_id}/tasks",
        json={"title": title, "due_date": due_date},
        headers={"Authorization": f"Bearer {VIKUNJA_TOKEN}"}
    )
    return response.json()
 
agent = Agent(
    tools=[vikunja_create_task],
    system="..."
)

Decorator @tool generuje JSON schema dla Claude API. Type hints są używane do walidacji argumentów.

Hooks — pre/post tool execution

Mogę interceptować każde wywołanie narzędzia:

@agent.before_tool
async def log_tool_use(tool_name: str, args: dict):
    print(f"[{datetime.now()}] {tool_name}({args})")
 
@agent.after_tool
async def validate_result(tool_name: str, result):
    if tool_name == "bash" and "rm -rf" in str(result.command):
        raise ValueError("Destructive command blocked")

Podobnie do hooków w Claude Code, tylko w Pythonie i ja kontroluję integrację.

Cost: jak to się ma

Per request agent SDK liczy się tak samo jak Claude Code, to ten sam underlying API. Różnica: w SDK widzisz każdy turn, możesz batch'ować, możesz limit'ować max_turns aggressively.

result = await agent.run(
    "Research 50 companies in batch",
    max_turns=200,  # cap
    model="claude-haiku-4-5"  # taniej dla batch
)
 
print(f"Total cost: ${result.usage.total_cost}")

Mój researcher: ~$0.05 per company. Dla batch 50 = $2.50. Sensowne.

Czego SDK NIE robi

1. Nie ma magicznej memory. Każdy agent.run() to fresh session domyślnie. Jak chcesz persistence, zapisujesz result.history i podajesz w następnym wywołaniu.

2. Nie ma plan mode. Plan mode to feature Claude Code, nie SDK. Możesz zaimplementować podobny flow ręcznie, ale boilerplate.

3. Nie ma sub-agentów out-of-box. Możesz robić zagnieżdżone wywołania agent.run(), ale nie ma wbudowanego "spawn child agent" jak Agent(...) w Claude Code.

Kiedy NIE używać SDK

1. Personal workflow. Claude Code wystarcza. SDK = overhead bez wartości dodanej.

2. One-off scripts. API direct call jest prostszy.

3. Jeśli nie masz konkretnego user-faceing use case'u. SDK ma sens gdy budujesz produkt. Bez produktu = przerost formy nad treścią.

Kiedy TAK używać

1. SaaS feature napędzany agentem. Np. dodajesz "AI assistant" do swojej aplikacji.

2. Wąski domain agent. Cold outreach researcher, code review bot, customer support agent.

3. Multi-tenant z różnymi user'ami. Każdy z innym contextem, SDK daje state management.

Co bym zrobił inaczej

Po tygodniu eksperymentów:

1. Zacząłbym od Sonnet 4.6, nie Opus. Dla wąskich tasków różnica jakościowa jest mała, koszt 3x niższy.

2. Pisałbym tools defensywnie. Każdy tool dostaje walidację argumentów. Agent czasem wpuszcza dziwne wartości.

3. Logowałbym KAŻDY tool call. W produkcji bez tego nie zdebugujesz dlaczego coś poszło źle. Hook before_tool to standardowy pattern.

Agent SDK to nie konkurent Claude Code, to komplement. Claude Code do osobistej pracy, SDK do produktu. Pierwszy tydzień eksperymentów dał mi działającego cold outreach researchera. Próg wejścia: ~3 godziny dokumentacji + ~5 godzin pisania.