- Настроить проект с Agent SDK
- Создать файл с некорректным кодом
- Запустить агента, который автоматически находит и исправляет ошибки
Предварительные требования
- Node.js 18+ или Python 3.10+
- Учётная запись Anthropic (зарегистрируйтесь здесь)
Настройка
1
Создайте папку проекта
Создайте новый каталог для этого быстрого старта:Для собственных проектов вы можете запустить SDK из любой папки; по умолчанию он будет иметь доступ к файлам в этом каталоге и его подкаталогах.
2
Установите SDK
Установите пакет Agent SDK для вашего языка:Установка
- TypeScript (новый проект)
- TypeScript (существующий проект)
- Python (uv)
- Python (pip)
"type": "module" в package.json позволяет вашему скрипту агента использовать верхнеуровневый await, а tsx запускает файлы TypeScript напрямую.TypeScript SDK включает нативный бинарный файл Claude Code для вашей платформы в качестве опциональной зависимости, поэтому вам не нужно устанавливать Claude Code отдельно.
3
Установите ваш API ключ
Получите API ключ из Claude Console, затем установите его как переменную окружения в оболочке, где вы будете запускать вашего агента:SDK читает ключ из окружения процесса, который запускает вашего агента; он не загружает файлы
- macOS / Linux
- Windows (PowerShell)
.env автоматически. Если вы храните ключ в файле .env, загрузите его самостоятельно, например с помощью пакета dotenv, перед вызовом SDK.SDK также поддерживает аутентификацию через сторонних поставщиков API:- Amazon Bedrock: установите переменную окружения
CLAUDE_CODE_USE_BEDROCK=1и настройте учётные данные AWS - Claude Platform on AWS: установите
CLAUDE_CODE_USE_ANTHROPIC_AWS=1иANTHROPIC_AWS_WORKSPACE_ID, затем настройте учётные данные AWS - Google Cloud’s Agent Platform: установите переменную окружения
CLAUDE_CODE_USE_VERTEX=1и настройте учётные данные Google Cloud - Microsoft Azure: установите переменную окружения
CLAUDE_CODE_USE_FOUNDRY=1и настройте учётные данные Azure
Если не было предварительного одобрения, Anthropic не разрешает сторонним разработчикам предлагать вход через claude.ai или ограничения скорости для своих продуктов, включая агентов, созданных на основе Claude Agent SDK. Вместо этого используйте методы аутентификации через API ключ, описанные в этом документе.
Создайте файл с ошибками
Этот быстрый старт проведёт вас через создание агента, который может находить и исправлять ошибки в коде. Сначала вам нужен файл с некоторыми намеренными ошибками для исправления агентом. Создайтеutils.py в каталоге my-agent и вставьте следующий код:
calculate_average([])падает с ошибкой деления на нольget_user_name(None)падает с TypeError
Создайте агента, который находит и исправляет ошибки
Создайтеagent.py, если вы используете Python SDK, или agent.ts для TypeScript. Используйте agent.mts вместо этого, если ваш существующий проект использует CommonJS:
-
query: основная точка входа, которая создаёт цикл агента. Она возвращает асинхронный итератор, поэтому вы используетеasync forдля потоковой передачи сообщений по мере работы Claude. Полный API см. в справочнике Python или TypeScript SDK. -
prompt: то, что вы хотите, чтобы сделал Claude. Claude определяет, какие инструменты использовать, на основе задачи. -
options: конфигурация для агента. В этом примере используетсяallowedToolsдля предварительного одобренияRead,EditиGlob, а такжеpermissionMode: "acceptEdits"для автоматического одобрения изменений файлов. Другие опции включаютsystemPrompt,mcpServersи многое другое. Все опции для Python или TypeScript.
async for продолжает работать, пока Claude думает, вызывает инструменты, наблюдает результаты и решает, что делать дальше. Каждая итерация выдаёт сообщение: рассуждение Claude, вызов инструмента, результат инструмента или окончательный результат. SDK обрабатывает оркестровку (выполнение инструментов, управление контекстом, повторные попытки), поэтому вы просто потребляете поток. Цикл заканчивается, когда Claude завершает задачу или возникает ошибка.
Обработка сообщений внутри цикла фильтрует удобочитаемый вывод. Без фильтрации вы увидите необработанные объекты сообщений, включая инициализацию системы и внутреннее состояние, что полезно для отладки, но в остальном шумно.
В этом примере используется потоковая передача для отображения прогресса в реальном времени. Если вам не нужен живой вывод (например, для фоновых заданий или конвейеров CI), вы можете собрать все сообщения сразу. Подробности см. в разделе Потоковая передача и однооборотный режим.
Запустите вашего агента
Ваш агент готов. Запустите его с помощью следующей команды:- TypeScript
- Python (uv)
- Python (pip)
agent.mts, запустите npx tsx agent.mts вместо этого.Done: success. После запуска проверьте utils.py. Вы увидите защитный код, обрабатывающий пустые списки и нулевых пользователей. Ваш агент автономно:
- Прочитал
utils.pyдля понимания кода - Проанализировал логику и определил граничные случаи, которые вызовут сбой
- Отредактировал файл для добавления надлежащей обработки ошибок
Если вы видите “API key not found”, убедитесь, что вы установили переменную окружения
ANTHROPIC_API_KEY в оболочке, где вы запускаете вашего агента. SDK не загружает файлы .env автоматически. Подробнее см. в полном руководстве по устранению неполадок.Попробуйте другие подсказки
Теперь, когда ваш агент настроен, попробуйте некоторые другие подсказки:"Add docstrings to all functions in utils.py""Add type hints to all functions in utils.py""Create a README.md documenting the functions in utils.py"
Настройте вашего агента
Вы можете изменить поведение вашего агента, изменив опции. Вот несколько примеров: Добавьте возможность веб-поиска:Bash попробуйте: "Write unit tests for utils.py, run them, and fix any failures"
Ключевые концепции
Инструменты контролируют, что может делать ваш агент:
Режимы разрешений контролируют, сколько человеческого надзора вы хотите:
Приведённый выше пример использует режим
acceptEdits, который автоматически одобряет файловые операции, чтобы агент мог работать без интерактивных подсказок. Если вы хотите запрашивать у пользователей одобрение, используйте режим default и предоставьте обратный вызов canUseTool, который собирает пользовательский ввод. Для большего контроля см. Разрешения.
Следующие шаги
Теперь, когда вы создали своего первого агента, узнайте, как расширить его возможности и адаптировать его к вашему варианту использования:- Разрешения: контролируйте, что может делать ваш агент и когда ему нужно одобрение
- Hooks: запускайте пользовательский код до или после вызовов инструментов
- Сессии: создавайте многооборотных агентов, которые сохраняют контекст
- MCP servers: подключайтесь к базам данных, браузерам, API и другим внешним системам
- Хостинг: развёртывайте агентов в Docker, облако и CI/CD
- Примеры агентов: см. полные примеры: помощник по электронной почте, исследовательский агент и многое другое