Claude Agent SDK

Короткая версия

Claude Agent SDK в 2026 лучше всего понимать так:

• это официальный Anthropic SDK для агентных runtime-сценариев;
• он работает в Python и TypeScript;
• он заточен под Claude Code как встроенного суб-агента;
• ключевые primitives здесь: query(), persistent client/session, permissions, hooks, Skills и MCP.

Когда он особенно уместен:

• coding agents;
• repo assistants;
• internal automation с filesystem/terminal tools;
• MCP-centric workflows;
• long-running multi-turn Claude sessions.

Что важно относительно старых обзоров:

• отдельный Agent SDK теперь действительно есть;
• article больше не должна сводить всё к "Anthropic SDK + ручной while loop";
• Skills и permission modes стали first-class частью official stack;
• extended thinking и tool use остаются важными, но это только часть общей картины.

Когда брать Claude Agent SDK, а не plain Anthropic Messages API?

1. Что такое Claude Agent SDK в 2026

Current official docs описывают SDK как отдельный agent layer для Claude Code.

По practical смыслу это значит:

• вы не просто вызываете модель;
• вы встраиваете Claude-based agent runtime;
• SDK уже знает про conversation continuity;
• может работать с tools и MCP;
• умеет жить в governed environment через permissions и hooks.

Это и есть его главное отличие от plain anthropic SDK.

2. Два базовых режима работы

query()

query() подходит, когда нужен one-off или bounded run:

• один task;
• отдельная новая session;
• простой automation script;
• короткий sub-agent call из другого orchestration layer.

Persistent client

Official docs отдельно разводят query() и client-based path для многотуровых диалогов.

Это полезно, когда вам нужны:

• сохранение контекста между turns;
• более длинная interactive session;
• interrupts и hooks;
• контроль над жизненным циклом агента.

Проще говоря:

• query() ближе к bounded agent task;
• persistent client ближе к embedded agent session.

3. Permissions, hooks и governance

Это одна из самых важных частей current Anthropic framing.

Permissions

Claude Agent SDK даёт explicit permission layer. Это критично, если агент умеет:

• читать и менять файлы;
• запускать команды;
• работать с MCP tools;
• делать действия, которые нельзя оставлять полностью без контроля.

Старая статья, где agent описывался почти только через tools и MCP, уже не покрывает engineering reality. Реальный coding or ops agent без permission model быстро становится unsafe.

Hooks

Hooks нужны, когда вы хотите встроить в run свои policy points:

• проверку действий;
• логирование;
• side-channel validation;
• custom approvals;
• audit behavior.

Именно здесь Anthropic stack становится интересен для production coding agents, а не просто для demo scripts.

4. Skills как отдельный слой

В current docs Skills уже оформлены как first-class primitive.

Что важно:

• Skills packaged as SKILL.md;
• грузятся из filesystem;
• обнаруживаются автоматически;
• подключают специализированные capabilities без раздувания основного system prompt.

Это сильная practical idea для agent engineering:

• не тащить всё знание в один giant prompt;
• выносить domain behavior в skill artifacts;
• загружать нужное по trigger, а не всегда.

Для coding и internal ops agents это особенно полезно:

• repo-specific conventions;
• deploy policies;
• incident playbooks;
• migration checklists;
• support/debug recipes.

5. MCP и Claude-centric tool stack

Anthropic ecosystem по-прежнему очень тесно связан с MCP.

В Agent SDK это означает, что MCP уже не выглядит "внешним протоколом, который когда-нибудь пригодится", а становится нормальной частью agent runtime.

Практические use cases:

• GitHub и issue management;
• repo search;
• internal docs access;
• database admin helpers;
• browser/computer-use adjacent tooling.

Если ваш stack уже думает категориями MCP servers, Claude Agent SDK обычно ощущается более естественным, чем generic framework с отдельным MCP adaptation layer.

6. Связь с extended thinking

Extended thinking не равно Agent SDK, но для Anthropic stack это важная adjacent capability.

Current docs по thinking уточняют:

• extended thinking даёт enhanced reasoning for complex tasks;
• на Claude Opus 4.6 manual thinking mode deprecated;
• для Opus 4.6 нужен adaptive thinking.

Практический вывод:

• agent runtime отвечает за execution loop и tools;
• thinking mode отвечает за качество reasoning на сложных шагах;
• смешивать эти уровни в одну сущность не надо.

7. Когда брать Claude Agent SDK

SDK обычно оправдан, если вам нужен:

• Claude-first coding agent;
• filesystem and terminal oriented agent;
• MCP-centric runtime;
• session continuity;
• governance через permissions;
• reusable Skills.

Типовые сценарии:

• internal repo assistant;
• code review and migration helper;
• incident triage agent;
• ops/copilot for engineering teams;
• bounded sub-agent inside larger orchestration system.

8. Когда лучше plain Anthropic SDK или другой runtime

Claude Agent SDK не всегда нужен.

Лучше взять plain anthropic SDK, если:

• вам нужен просто tool use поверх Messages API;
• у вас свой orchestration runtime;
• агентный loop очень узкий и deterministic;
• Claude Code style environment вам не нужен.

Лучше смотреть на LangGraph или другой framework, если:

• нужен provider-neutral graph runtime;
• нужен сложный state machine;
• важнее portability, чем Claude-native ergonomics.

Python path

from claude_agent_sdk import query, ClaudeAgentOptions


async def run_repo_helper():
    async for message in query(
        prompt="Inspect this repository and summarize risky migration points.",
        options=ClaudeAgentOptions(
            cwd="/workspace/project",
            max_turns=12,
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            permission_mode="acceptEdits",
        ),
    ):
        print(message)

Это хороший baseline, если нужен bounded coding/repo run.

TypeScript path

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

for await (const message of query({
  prompt: 'Find all database migrations and summarize rollback risk.',
  options: {
    cwd: '/workspace/project',
    maxTurns: 12,
    allowedTools: ['Read', 'Glob', 'Grep', 'Bash'],
    permissionMode: 'acceptEdits',
  },
})) {
  console.log(message);
}

Главный practical плюс тут не в синтаксисе, а в том, что тот же runtime нормально заходит в Node-based internal tooling.

Где plain Messages API всё ещё лучше

Если вам нужен обычный Claude tool loop, этого часто достаточно:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    tools=[...],
    messages=[{"role": "user", "content": "Check the latest deployment status"}],
)

То есть выбор надо делать по runtime job:

• нужен API loop с вашими правилами -> plain SDK;
• нужен embedded agent runtime -> Agent SDK.

Частые ошибки

У нас Claude-first coding assistant с MCP, repo edits и approval rules. Что смотреть первым?

Проверьте себя