- Настроить проект с 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 напрямую. npm выводит added N packages при успешной установке.Оба SDK TypeScript и Python включают нативный бинарный файл Claude Code, поэтому большинству установок не требуется отдельная установка Claude Code. Некоторые установки не имеют встроенного бинарного файла:
- Если pip устанавливает исходное распределение Python SDK вместо платформенного wheel, например на ARM64 Windows, бинарный файл не включается. Установите Claude Code нативно. Python SDK найдёт его в вашем
PATH. - TypeScript SDK устанавливает свой бинарный файл через опциональные зависимости npm, поэтому установка, которая их пропускает, например
npm ci --omit=optional, не получает бинарный файл даже на поддерживаемой платформе. Переустановите без пропуска опциональных зависимостей или установите Claude Code нативно и установитеpathToClaudeCodeExecutableна его путь.
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 Foundry: установите переменную окружения
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для понимания кода - Проанализировал логику и определил граничные случаи, которые вызовут сбой
- Отредактировал файл для добавления надлежащей обработки ошибок
Если вы видите ошибку аутентификации, такую как
Not logged in или Invalid API key, убедитесь, что вы установили переменную окружения 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"
Каждый из этих фрагментов устанавливает поля на одном и том же объекте опций. Для получения дополнительной информации см. Настройте вашего агента.
Ключевые концепции
Инструменты контролируют, что может делать ваш агент:
Режимы разрешений контролируют, сколько человеческого надзора вы хотите. SDK оценивает активный режим вместе с вашими правилами разрешения и запрета в фиксированном порядке, описанном в Как оцениваются разрешения. Для полного списка режимов, их поведения и когда использовать каждый, см. Режим разрешений в Как работает цикл агента.
Следующие шаги
Теперь, когда вы создали своего первого агента, узнайте, как расширить его возможности и адаптировать его к вашему варианту использования:- Настройка вашего агента: составьте объект параметров и найдите страницу, которая охватывает каждый параметр
- Разрешения: контролируйте, что может делать ваш агент и когда ему нужно одобрение
- Hooks: запускайте пользовательский код до или после вызовов инструментов
- Сессии: создавайте многооборотных агентов, которые сохраняют контекст
- MCP servers: подключайтесь к базам данных, браузерам, API и другим внешним системам
- Хостинг: развёртывайте агентов в Docker, облако и CI/CD
- Примеры агентов: см. полные примеры: помощник по электронной почте, исследовательский агент и многое другое
- Troubleshooting: исправляйте ошибки, когда CLI не запускается или выходит, или результат приходит без структурированного вывода