Руководство по использованию Claude Agent SDK

Claude Agent SDK позволяет создавать ИИ-агентов, которые могут автономно читать файлы, выполнять команды, искать в интернете, редактировать код и многое другое.

Claude Agent SDK предоставляет инструменты, цикл агента и возможности управления контекстом, которые лежат в основе Claude Code, в виде программируемых библиотек Python и TypeScript.

Проще говоря, это SDK, которое использует Claude Code как библиотеку. Вы можете встроить его в свои приложения, CI-конвейеры или сценарии автоматизации, чтобы создавать ИИ-агентов, способных автономно выполнять сложные задачи.

Основные возможности

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

Способность Описание
Встроенные инструменты Чтение/запись файлов, команды терминала, редактирование кода, веб-поиск и т. д.
Хуки Выполнение пользовательской логики до и после вызовов инструментов
Субагенты Разбивайте большие задачи на меньшие и делегируйте их независимым субагентам для параллельного выполнения
MCP-сервер Подключение к базам данных, браузерам, внешним API и т. д.
Управление разрешениями Точно контролируйте, что может делать агент и когда требуется одобрение пользователя
Управление сессиями Создавайте многоходовых диалоговых агентов, которые сохраняют контекст

Предварительные требования

Шаг 1: Установите SDK

TypeScript

npm install @anthropic-ai/claude-agent-sdk

TypeScript SDK включает бинарный файл Claude Code для вашей текущей платформы в качестве необязательной зависимости, поэтому нет необходимости устанавливать Claude Code отдельно.

Python

# 使用 pip
pip install claude-agent-sdk

# 或使用 uv（推荐）
uv add claude-agent-sdk

Примечание: Claude Code CLI автоматически устанавливается вместе с пакетом — отдельная установка не требуется! SDK по умолчанию использует встроенный CLI.

Если вы предпочитаете использовать установку на уровне системы или конкретную версию, вы можете использоватьClaudeAgentOptions(cli_path="/path/to/claude")Укажите путь.

Шаг 2: Настройте API-ключ

изClaude ConsoleПолучите API-ключ, затем создайте файл в каталоге проекта:.envфайл:

ANTHROPIC_API_KEY=your-api-key-here

Или задайте его напрямую как переменную окружения:

export ANTHROPIC_API_KEY=your-api-key-here

Поддержка сторонних облачных платформ

SDK также поддерживает аутентификацию через сторонних API-провайдеров: Amazon Bedrock (задайтеCLAUDE_CODE_USE_BEDROCK=1переменную окружения и настройте учетные данные AWS), Google Vertex AI (задайтеCLAUDE_CODE_USE_VERTEX=1) и Microsoft Azure (задайтеCLAUDE_CODE_USE_FOUNDRY=1）。

⚠️ Важно: Если не получено предварительное одобрение от Anthropic, сторонним разработчикам не разрешается предоставлять вход через claude.ai или ограничение скорости в продуктах, созданных на Claude Agent SDK. Пожалуйста, используйте метод аутентификации с помощью API-ключа, описанный в документации.

Шаг 3: Запустите первого агента

В следующем примере создается агент, который перечисляет файлы в текущем каталоге:

Python

Пример

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Какие файлы находятся в этом каталоге?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

TypeScript

Пример

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

async function main() {
  for await (const message of query({
    prompt: "Какие файлы находятся в этом каталоге?",
    options: { allowedTools: ["Bash", "Glob"] },
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

Практика: создайте агента, который автоматически исправляет ошибки

Ниже приведён полный пример, демонстрирующий основное использование Agent SDK.

Подготовьте файл с ошибкой

Создайтеutils.py, содержащий две намеренные ошибки:

Пример

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)   # Ошибка: деление на 0, когда список пуст

def get_user_name(user):
    return user["name"].upper()   # Ошибка: вызывает TypeError, когда user равен None

Напишите агента

Создайтеagent.py：

Пример

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="Проверьте utils.py на ошибки, которые могут привести к сбоям. Исправьте все найденные проблемы.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Разрешённые инструменты
            permission_mode="acceptEdits",            # Автоматически одобрять правки файлов
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)          # Процесс рассуждений Claude
                elif hasattr(block, "name"):
                    print(f"Инструмент: {block.name}") # Вызывается инструмент
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Итоговый результат

asyncio.run(main())

Запустите

python agent.py

После запуска проверьтеutils.py, вы увидите, что Агент автономно выполнил следующие действия:

  1. Прочиталужеutils.pyфайл
  2. Проанализироваллогику кода, выявил граничные случаи, которые могут привести к сбоям
  3. Отредактировалфайл, добавил комплексную обработку ошибок

Объяснение основных концепций

Функции — точка входа в цикл агента

query— основная точка входа для создания цикла агента, возвращает асинхронный итератор, поэтому вы используетеasync forдля потоковой передачи сообщений, генерируемых Claude, в реальном времени. Цикл завершается, когда Claude выполняет задачу или сталкивается с ошибкой. SDK обрабатывает оркестрацию (выполнение инструментов, управление контекстом, повторные попытки), а вам нужно только потреблять этот поток сообщений.

Каждая итерация создаёт сообщение, которое может быть:

  • Процесс рассуждений Claude
  • Вызов инструмента
  • Результат вызова инструмента
  • Итоговый результат

Инструменты — управление тем, что может делать агент

Комбинации инструментов Возможности агента
Read, Glob, Grep Анализ только для чтения
Read, Edit, Glob Анализ и изменение кода
Read, Edit, Bash, Glob, Grep Полная автоматизация
ПлюсWebSearch Добавить возможность веб-поиска

Режимы разрешений – контроль уровня человеческого надзора

Mode Поведение Сценарий использования
acceptEdits Автоматически одобрять правки файлов, остальные операции по-прежнему требуют подтверждения Доверенный рабочий процесс разработки
dontAsk ЗапретитьallowedToolsвсе операции за пределами Жёстко ограниченный агент без присмотра
auto(только TypeScript) Классификатор модели автоматически одобряет/отклоняет каждый вызов инструмента Автономный агент с защитными ограничениями
bypassPermissions Запускать все инструменты напрямую без запросов подтверждения Среда CI в песочнице
default Обязательно предоставитьcanUseToolколбэк для обработки подтверждения Настраиваемый процесс подтверждения

Настроить поведение агента

Добавить веб-поиск

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

Добавить пользовательские системные промпты

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

Разрешить выполнение команд терминала

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)
# 可以尝试：
# prompt="Write unit tests for utils.py, run them, and fix any failures"

Загрузить конфигурацию проекта (CLAUDE.md и т. д.)

SDK построен на той же основе, что и Claude Code, и агенты SDK могут использовать те же функции на основе файловой системы: инструкции проекта (CLAUDE.md и правила), навыки, Hooks и т. д. По умолчанию SDK не загружает никакие настройки файловой системы.

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit"],
    # "user" 从 ~/.claude/ 加载，"project" 从 ./.claude/ 加载
    setting_sources=["user", "project"],
)

Обработка ошибок

from claude_agent_sdk import (
    ClaudeSDKError,      # 基础错误
    CLINotFoundError,    # Claude Code 未安装
    CLIConnectionError,  # 连接问题
    ProcessError,        # 进程失败
    CLIJSONDecodeError,  # JSON 解析失败
)

try:
    async for message in query(prompt="Hello"):
        pass
except CLINotFoundError:
    print("请先安装 Claude Code")
except ProcessError as e:
    print(f"进程失败，退出码：{e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"响应解析失败：{e}")

SDK агента в сравнении с другими инструментами Claude

SDK агента Клиентский SDK（Messages API） Claude Code CLI
Использование Библиотека Python/TypeScript Вызовы HTTP API Инструмент командной строки терминала
Выполнение инструментов Встроенное, автоматическое выполнение Требуется ручная реализация Встроенный, интерактивный
Сценарий использования Создание автономных агентов, интеграция приложений Общие вызовы LLM Прямая помощь в написании кода
Управление состоянием С сохранением состояния, поддерживает сессии Без сохранения состояния С сохранением состояния, интерактивный

Таблица сравнения возможностей SDK

SDK также поддерживает конфигурацию Claude Code на основе файловой системы. Чтобы использовать эти возможности, задайте их в параметрахsetting_sources=["project"](Python) илиsettingSources: ['project'](TypeScript).

Характеристика Описание Расположение
Навыки Специализированные возможности, определённые в Markdown .claude/skills/*/SKILL.md
Слэш-команды Пользовательские команды для типовых задач .claude/commands/*.md
Память Контекст проекта и инструкции CLAUDE.md
Плагины Черезpluginsрасширения параметров Настраивается через код
Другие расширения