Claude AI Bible, глава 18: Claude Agent SDK
Главная мысль: Agent SDK — библиотека Anthropic, которая ведёт цикл агента за вас: модель решает, инструмент работает, модель видит результат, и так до конца задачи. На этом же движке работает Claude Code. Но агент нужен редко: сначала убедитесь, что задаче мало одного вызова API, а потом дайте агенту узкий набор инструментов и жёсткие границы.
О чём глава
Заголовок раздела «О чём глава»В главе 17 мы отправляли один запрос и получали один ответ. Агент же действует: читает файлы, запускает команды, проверяет итог и решает, что делать дальше. Цикл, инструменты, контекст и защиту можно написать поверх API самому, а можно взять Agent SDK. Автор подчёркивает, что это не игрушка: Anthropic обобщила каркас агента из Claude Code, который прошёл миллионы реальных задач.
Что такое SDK и когда он нужен
Заголовок раздела «Что такое SDK и когда он нужен»Фреймворк для агентов решает одну скучную задачу — цикл. С голым Messages API вы сами проверяете, попросил ли Claude инструмент, запускаете его, отправляете результат обратно и повторяете. Ещё на вас ложатся растущая история разговора, права агента и десяток типичных сбоев, когда программа действует сама. Agent SDK берёт эту механику на себя: вы задаёте цель и инструменты, а он ведёт цикл, следит за контекстом и правами. Ещё он даёт точки, где можно наблюдать за агентом и управлять им.
| Задача | Что брать |
|---|---|
| Одно преобразование: текст на входе, текст на выходе | Messages API |
| Шаги известны заранее | Простая цепочка вызовов в скрипте |
| Каждый шаг зависит от прошлого, число шагов неизвестно | Agent SDK |
Задача «почини упавший тест и повторяй, пока не пройдёт» подходит агенту: сколько будет кругов, заранее не знает никто. А выжимку файла делают одним вызовом.
Ловушка. Самая дорогая ошибка — агент там, где хватило бы одного вызова. Агент медленнее, дороже и менее предсказуем, ведь каждый результат снова идёт через модель. Пусть задача сначала докажет, что ей нужен агент.
Цикл агента
Заголовок раздела «Цикл агента»Всё в SDK крутится вокруг цикла из четырёх тактов:
- Модель решает: отвечает или просит инструмент.
- SDK запускает инструмент: читает файл, выполняет команду, делает запрос к базе.
- Модель видит результат: данные или ошибку.
- Цикл повторяется до финального ответа или до вашего лимита.

Схему читают по кругу: от решения к инструменту, к результату и снова к решению. Выход из круга один — финальный ответ, а красный блок справа показывает аварийный стоп.
Claude Code — тот же цикл с инструментами для файлов и shell. Главный сдвиг в том, что вы больше не пишете шаги: вы задаёте цель и инструменты, а путь выбирает Claude. Поэтому агент силён и поэтому же непредсказуем.
Инструменты агента
Заголовок раздела «Инструменты агента»Агент умеет столько, сколько дают его инструменты, и безопасен настолько, насколько они ограничены. Для модели инструмент — это имя, описание простыми словами и схема параметров. Сама модель код не запускает: она просит инструмент по имени, а SDK вызывает функцию. Подробно о схемах — в главе 19.
Кроме встроенных инструментов, как в Claude Code, можно добавить свои. Пример из книги — lookup_inventory: по артикулу он возвращает остаток и склад, а docstring функции служит описанием. Модель выбирает инструмент в основном по имени и описанию, поэтому пишите их для толкового новичка, который не видел вашу систему.
Совет автора. На каждый инструмент записи дайте инструмент чтения. Агент, который перечитывает исправленный файл, ловит свои ошибки внутри цикла, а не оставляет их вам.
Ещё Agent SDK работает с MCP server (глава 16), и трекер, база или хранилище подключаются без кода интеграции. Свои инструменты пишите для того, что уникально в задаче, а общее берите у готовых серверов.
Сессии, контекст и память
Заголовок раздела «Сессии, контекст и память»С каждым шагом разговор растёт, и на длинной задаче вы упрётесь в context window. Сессия — это один запуск агента к одной цели со всеми ходами. SDK умеет сжимать старые части разговора в выжимки, чтобы агент помнил суть.
Внутри сессии агент помнит всё. Между сессиями он не помнит ничего, пока вы сами не сохраните нужное: например, в файл заметок, который агент читает в начале. На этой границе информацию либо теряют, либо тащат лишнее. Теряют, когда верят, что агент «помнит» вчерашний разговор. Лишнее тащат, когда каждый раз грузят один растущий файл со всем подряд, а это дорого и приносит устаревшие факты. Правило автора: сохраняйте осознанно, загружайте выборочно и держите сессии узкими.
Права и guardrails
Заголовок раздела «Права и guardrails»Агент, который может действовать, может действовать плохо: удалить не тот файл, зайти в боевую базу, сжечь бюджет в цикле. SDK делали те же люди, что пустили Claude Code в реальные кодовые базы, поэтому guardrails здесь — основа, а не добавка. Вы явно решаете, что агент делает сам, на что просит разрешения и чего не делает никогда:
| Слой | Как работает |
|---|---|
| Набор инструментов | Нет инструмента — нет действия. Самый сильный слой, потому что абсолютный |
| Одобрение | Человек или код подтверждает опасное действие, как Claude Code перед рискованной командой |
| Песочница | Контейнер без сети и только со своей папкой. С вашими полными правами агент опасен |
| Жёсткие лимиты | Максимум шагов и потолок бюджета. Нужны редко, но ставят их всегда |

Каждое действие агента проходит проверки слева направо, а лимиты стоят последним стопом.
Случай из практики. Стартап в Роттердаме разрешил агенту для сверки счетов править записи в боевой базе без одобрения: на тестах тот не ошибался. На третьем запуске агент неверно прочитал необычный счёт и переписал сорок с лишним записей. Данные вернули из бэкапа, но уборка заняла два дня. Решением стала не более умная модель, а проверка, которую сначала пропустили: теперь каждая запись ждёт подтверждения в один клик.
Subagents и orchestration
Заголовок раздела «Subagents и orchestration»Большую или разнородную задачу главный агент-оркестратор делит на части, отдаёт каждую своему subagent и собирает итог. У каждого subagent чистый контекст под одну узкую задачу.
Пример из книги — код-ревью в три независимые линии: безопасность, скорость и стиль кода. Как главный агент раздаёт части и собирает сводки, показывает схема в главе 13. Но несколько агентов дороже и сложнее одного, поэтому orchestration берут, только если части задачи независимы. Подробнее — в главе 20.
Как увидеть ход мыслей агента
Заголовок раздела «Как увидеть ход мыслей агента»Агенту-«чёрному ящику» нельзя доверять, и его нельзя отладить. Поэтому автор сразу включает журнал: SDK вызывает ваши функции или шлёт событие на каждом такте цикла. Пишите, что агент решил, какой инструмент вызвал, с какими аргументами и что получил. Причина странного поведения обычно видна сразу: неудачное описание инструмента, запутанный результат или двусмысленная цель. На сервере этот журнал становится мониторингом.
Совет автора. Если агент ошибается, не берите сразу модель крупнее. Прочитайте журнал и поправьте prompt или описание инструмента: это дешевле, чем ставить Opus там, где Sonnet справился бы с ясной инструкцией.
Локально или на сервере
Заголовок раздела «Локально или на сервере»Агента строят и проверяют на своей машине, и многие личные агенты так и живут. Сервер нужен, когда агент работает без вас. Тогда ключ API хранят в окружении, а не в коде, песочница и журнал обязательны, а лимиты становятся главной защитой: ночью никто не нажмёт «стоп».
| Вид агента | Когда работает | О чём думать |
|---|---|---|
| По расписанию | Каждое утро: сводка, отчёт | Оповещение, если запуск ничего не выдал |
| По событию | Письмо, webhook, новый файл | Всплески и повторные события |
| Сервис | Всегда, отвечает другим программам | Плохой запрос не должен уронить остальные |
Порядок автора: соберите агента локально, много раз прочитайте его шаги, добавьте журнал и лимиты. Только потом запускайте его без присмотра, и с малым blast radius: песочница, запись через одобрение, оповещение при сбое.
Минимальный агент
Заголовок раздела «Минимальный агент»Самый маленький полезный агент разбирает тикеты поддержки. Инструмент read_ticket читает тикет, а log_summary дописывает в журнал строку файл | категория | срочность | итог. System prompt задаёт категории и запрещает выдумывать, а max_iterations=8 не даёт агенту крутиться вечно.
Удалять, писать письма, запускать shell и ходить в сеть агент не может, так что в худшем случае он запишет плохую строку. Именно такие жёсткие рамки позволяют доверить ему тысячу тикетов и не следить за ним. Автор советует собрать похожего агента для своей мелкой рутины и прочитать каждый его шаг на пяти реальных примерах.
Итоги главы
Заголовок раздела «Итоги главы»- Агент нужен, только если шаги нельзя спланировать заранее; иначе скрипт дешевле и предсказуемее.
- Любой агент — это цикл: модель решает, инструмент работает, модель видит результат, повтор.
- Модель выбирает инструмент по имени и описанию, а инструменты чтения помогают ей проверять себя.
- Между сессиями агент ничего не помнит: сохраняйте осознанно, загружайте выборочно.
Guardrails— это набор инструментов, одобрение, песочница и лимиты шагов и бюджета.Subagentоправдан, только если части задачи независимы.- Журнал шагов нужен с первого запуска, а без присмотра агента выпускают после долгой локальной проверки.
Ключевые термины
Заголовок раздела «Ключевые термины»| Термин | Значение |
|---|---|
Agent SDK | Библиотека Anthropic для своих агентов на движке Claude Code |
цикл агента (agent loop) | Модель решает, инструмент работает, модель видит результат, повтор |
| сессия | Один запуск агента к одной цели со всей историей |
guardrails | Инструменты, одобрение, песочница и лимиты вокруг агента |
subagent | Отдельный агент со своим контекстом под часть задачи |
Что это значит на практике
Заголовок раздела «Что это значит на практике»- Если шаги
pipelineможно записать, хватит DAG в Airflow и одного вызова модели на шаге. - Агенту для данных давайте пользователя базы
read-only, аUPDATEиDELETEпускайте через одобрение. - Храните журнал агента как логи
pipelineи ставьте оповещение на пустой или слишком длинный запуск.
Код главы
Заголовок раздела «Код главы»В книге только наброски на вымышленном классе Agent, а точные функции автор советует сверять на docs.claude.com. Наша версия агента для тикетов работает без ключа API (ch18_triage_agent.py): модель заменена правилами, а проверка can_run, журнал on_event и лимит шагов устроены как в книге.
def run_agent(goal: str, tools: dict, max_iterations: int = 8) -> str: history = [] for step in range(1, max_iterations + 1): decision = fake_model(goal, history) # 1. модель решает if "final" in decision: return decision["final"] name, args = decision["tool"], decision["args"] on_event("tool_call", f"шаг {step}: {name}({args})") if not can_run(name, args): result = "Отказано: это действие требует одобрения." else: result = tools[name](**args) # 2. инструмент работает on_event("tool_result", result[:60]) history.append({"tool": name, "args": args, "result": result}) # 3. модель видит итог return f"Остановлен: сработал лимит, max_iterations={max_iterations}." # 4. или повторpython3 -I scripts/claude-ai-bible-code/ch18_triage_agent.pyЦель: Разбери тикет ticket_4471.txt [tool_call] шаг 1: read_ticket({'filename': 'ticket_4471.txt'}) [tool_result] С карты дважды списали оплату за март. Верните лишний платёж [tool_call] шаг 2: log_summary({'line': 'ticket_4471.txt | billing | high | С карты дважды списали оплату за март'}) [tool_result] Записано.Ответ: Тикет разобран, строка записана в журнал.
Цель: Разбери и удали тикет ticket_4472.txt [tool_call] шаг 1: delete_ticket({'filename': 'ticket_4472.txt'}) [gate] агент хочет удалить ticket_4472.txt. Человек ответил: нет [tool_result] Отказано: это действие требует одобрения. [tool_call] шаг 2: read_ticket({'filename': 'ticket_4472.txt'}) [tool_result] Не могу войти в аккаунт после смены пароля. [tool_call] шаг 3: log_summary({'line': 'ticket_4472.txt | account | medium | Не могу войти в аккаунт после смены пароля'}) [tool_result] Записано.Ответ: Тикет разобран, строка записана в журнал.
Цель: Разбери тикет ticket_9999.txt [tool_call] шаг 1: read_ticket({'filename': 'ticket_9999.txt'}) [tool_result] Тикет ticket_9999.txt не найден. [tool_call] шаг 2: read_ticket({'filename': 'ticket_9999.txt'}) [tool_result] Тикет ticket_9999.txt не найден. [tool_call] шаг 3: read_ticket({'filename': 'ticket_9999.txt'}) [tool_result] Тикет ticket_9999.txt не найден.Ответ: Остановлен: сработал лимит, max_iterations=3.
triage_log.txt:ticket_4471.txt | billing | high | С карты дважды списали оплату за мартticket_4472.txt | account | medium | Не могу войти в аккаунт после смены пароляТикетов в папке: 2Во втором запуске проверка не дала удалить тикет, а в третьем «застрявшего» агента остановил лимит.
Тот же агент на настоящем SDK лежит в ch18_real_sdk.py. Этот блок мы не запускали: нужен платный ключ API. Код компилируется, а имена сверены с пакетом claude-agent-sdk==0.2.182.
options = ClaudeAgentOptions( model="claude-sonnet-4-6", system_prompt=("Ты разбираешь тикеты поддержки. Прочитай тикет, выбери категорию " "(billing, technical, account, other) и срочность (low, medium, high). " "Запиши одну строку: '<файл> | <категория> | <срочность> | <итог>'. " "Не выдумывай того, чего нет в тикете."), mcp_servers={"triage": server}, allowed_tools=["mcp__triage__read_ticket"], # чтение без вопросов tools=[], # встроенные Bash, Edit и др. выключены can_use_tool=can_use_tool, # запись — через проверку max_turns=8, # лимит шагов цикла max_budget_usd=0.50, # лимит денег на запуск )Пояснение: класс
Agent(..., max_iterations=8)из книги — набросок. В настоящем пакете инструменты оформляют через@toolиcreate_sdk_mcp_server, лимит шагов — этоmax_turns, проверку перед вызовом задаётcan_use_tool.
Вопросы для самопроверки
Заголовок раздела «Вопросы для самопроверки»- Почему починку тестов нельзя сделать одним вызовом API, а выжимку файла можно?
- Какой слой
guardrailsавтор считает самым сильным и почему? - Как при работе с памятью агента теряют информацию и как тащат лишнее?
- Когда
orchestrationокупается, а когда это лишняя сложность? - Что делать первым, если агент ведёт себя странно?
Предыдущая: Anthropic API. Следующая: Tool use, computer use и зрение.