Перейти к содержимому
TelegramGitHub

Claude AI Bible, глава 18: Claude Agent SDK

Главная мысль: Agent SDK — библиотека Anthropic, которая ведёт цикл агента за вас: модель решает, инструмент работает, модель видит результат, и так до конца задачи. На этом же движке работает Claude Code. Но агент нужен редко: сначала убедитесь, что задаче мало одного вызова API, а потом дайте агенту узкий набор инструментов и жёсткие границы.

В главе 17 мы отправляли один запрос и получали один ответ. Агент же действует: читает файлы, запускает команды, проверяет итог и решает, что делать дальше. Цикл, инструменты, контекст и защиту можно написать поверх API самому, а можно взять Agent SDK. Автор подчёркивает, что это не игрушка: Anthropic обобщила каркас агента из Claude Code, который прошёл миллионы реальных задач.

Фреймворк для агентов решает одну скучную задачу — цикл. С голым Messages API вы сами проверяете, попросил ли Claude инструмент, запускаете его, отправляете результат обратно и повторяете. Ещё на вас ложатся растущая история разговора, права агента и десяток типичных сбоев, когда программа действует сама. Agent SDK берёт эту механику на себя: вы задаёте цель и инструменты, а он ведёт цикл, следит за контекстом и правами. Ещё он даёт точки, где можно наблюдать за агентом и управлять им.

ЗадачаЧто брать
Одно преобразование: текст на входе, текст на выходеMessages API
Шаги известны заранееПростая цепочка вызовов в скрипте
Каждый шаг зависит от прошлого, число шагов неизвестноAgent SDK

Задача «почини упавший тест и повторяй, пока не пройдёт» подходит агенту: сколько будет кругов, заранее не знает никто. А выжимку файла делают одним вызовом.

Ловушка. Самая дорогая ошибка — агент там, где хватило бы одного вызова. Агент медленнее, дороже и менее предсказуем, ведь каждый результат снова идёт через модель. Пусть задача сначала докажет, что ей нужен агент.

Всё в SDK крутится вокруг цикла из четырёх тактов:

  1. Модель решает: отвечает или просит инструмент.
  2. SDK запускает инструмент: читает файл, выполняет команду, делает запрос к базе.
  3. Модель видит результат: данные или ошибку.
  4. Цикл повторяется до финального ответа или до вашего лимита.

Цикл агента: вы задаёте цель, инструменты и лимиты; модель решает; если нужен инструмент, SDK его запускает, модель видит результат и решает снова; иначе финальный ответ; лимит шагов или бюджета останавливает цикл

Схему читают по кругу: от решения к инструменту, к результату и снова к решению. Выход из круга один — финальный ответ, а красный блок справа показывает аварийный стоп.

Claude Code — тот же цикл с инструментами для файлов и shell. Главный сдвиг в том, что вы больше не пишете шаги: вы задаёте цель и инструменты, а путь выбирает Claude. Поэтому агент силён и поэтому же непредсказуем.

Агент умеет столько, сколько дают его инструменты, и безопасен настолько, насколько они ограничены. Для модели инструмент — это имя, описание простыми словами и схема параметров. Сама модель код не запускает: она просит инструмент по имени, а SDK вызывает функцию. Подробно о схемах — в главе 19.

Кроме встроенных инструментов, как в Claude Code, можно добавить свои. Пример из книги — lookup_inventory: по артикулу он возвращает остаток и склад, а docstring функции служит описанием. Модель выбирает инструмент в основном по имени и описанию, поэтому пишите их для толкового новичка, который не видел вашу систему.

Совет автора. На каждый инструмент записи дайте инструмент чтения. Агент, который перечитывает исправленный файл, ловит свои ошибки внутри цикла, а не оставляет их вам.

Ещё Agent SDK работает с MCP server (глава 16), и трекер, база или хранилище подключаются без кода интеграции. Свои инструменты пишите для того, что уникально в задаче, а общее берите у готовых серверов.

С каждым шагом разговор растёт, и на длинной задаче вы упрётесь в context window. Сессия — это один запуск агента к одной цели со всеми ходами. SDK умеет сжимать старые части разговора в выжимки, чтобы агент помнил суть.

Внутри сессии агент помнит всё. Между сессиями он не помнит ничего, пока вы сами не сохраните нужное: например, в файл заметок, который агент читает в начале. На этой границе информацию либо теряют, либо тащат лишнее. Теряют, когда верят, что агент «помнит» вчерашний разговор. Лишнее тащат, когда каждый раз грузят один растущий файл со всем подряд, а это дорого и приносит устаревшие факты. Правило автора: сохраняйте осознанно, загружайте выборочно и держите сессии узкими.

Агент, который может действовать, может действовать плохо: удалить не тот файл, зайти в боевую базу, сжечь бюджет в цикле. SDK делали те же люди, что пустили Claude Code в реальные кодовые базы, поэтому guardrails здесь — основа, а не добавка. Вы явно решаете, что агент делает сам, на что просит разрешения и чего не делает никогда:

СлойКак работает
Набор инструментовНет инструмента — нет действия. Самый сильный слой, потому что абсолютный
ОдобрениеЧеловек или код подтверждает опасное действие, как Claude Code перед рискованной командой
ПесочницаКонтейнер без сети и только со своей папкой. С вашими полными правами агент опасен
Жёсткие лимитыМаксимум шагов и потолок бюджета. Нужны редко, но ставят их всегда

Путь действия агента через четыре слоя: если инструмента нет, действие невозможно; если нужно одобрение, человек или код говорит да или нет; разрешённое действие идёт в песочнице; лимиты шагов и бюджета останавливают цикл

Каждое действие агента проходит проверки слева направо, а лимиты стоят последним стопом.

Случай из практики. Стартап в Роттердаме разрешил агенту для сверки счетов править записи в боевой базе без одобрения: на тестах тот не ошибался. На третьем запуске агент неверно прочитал необычный счёт и переписал сорок с лишним записей. Данные вернули из бэкапа, но уборка заняла два дня. Решением стала не более умная модель, а проверка, которую сначала пропустили: теперь каждая запись ждёт подтверждения в один клик.

Большую или разнородную задачу главный агент-оркестратор делит на части, отдаёт каждую своему 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.

  1. Почему починку тестов нельзя сделать одним вызовом API, а выжимку файла можно?
  2. Какой слой guardrails автор считает самым сильным и почему?
  3. Как при работе с памятью агента теряют информацию и как тащат лишнее?
  4. Когда orchestration окупается, а когда это лишняя сложность?
  5. Что делать первым, если агент ведёт себя странно?

Предыдущая: Anthropic API. Следующая: Tool use, computer use и зрение.