Интеграция Anthropic Claude Agent SDK для построения AI-агентов
Отметим: когда клиент приходит с задачей построить агента, который не просто отвечает на вопросы, а выполняет действия — поиск в базах, создание тикетов, работа с файлами — мы знаем, что Anthropic Claude Agent SDK снимает 80% рутины. Но неправильная интеграция приводит к потерям контекста и галлюцинациям. Расскажу, как мы настраиваем SDK, чтобы агент работал надёжно в production. Наша команда имеет 5+ лет опыта в NLP и LLM, реализовала более 20 проектов с Claude Agent SDK. Мы гарантируем стабильную работу агента в вашей инфраструктуре.
Преимущества Claude Agent SDK
Claude Agent SDK — официальный Python SDK Anthropic для построения агентов на основе Claude. Он предоставляет высокоуровневые абстракции над Anthropic API: управление жизненным циклом агента, интеграция с инструментами, поддержка MCP (Model Context Protocol), стриминг событий и встроенный human-in-the-loop. Без SDK пришлось бы писать цикл вызовов, управлять историей и обрабатывать ошибки вручную — наша практика показывает, что это занимает в 3 раза больше времени, что при средней ставке разработчика даёт экономию в около $90–130 на проекте.
Базовая настройка агента
Установка через pip: pip install anthropic claude-agent-sdk. Мы используем последнюю стабильную версию. Дальше — определение инструментов через декоратор @tool и создание конфигурации. Код ниже — типовой шаблон, который мы применяем в проектах.
# pip install anthropic claude-agent-sdk import anthropic from claude_agent_sdk import Agent, AgentConfig, tool client = anthropic.Anthropic() # Определение инструментов через декоратор @tool def search_database(query: str, table: str = "products") -> str: """Поиск по базе данных компании. Args: query: Поисковый запрос table: Таблица для поиска (products, orders, customers) """ results = db.search(query=query, table=table, limit=10) return results.to_json() @tool def create_support_ticket( customer_id: str, subject: str, description: str, priority: str = "normal", ) -> str: """Создать тикет в системе поддержки. Args: customer_id: ID клиента subject: Тема обращения description: Подробное описание priority: Приоритет (low, normal, high, critical) """ ticket = helpdesk.create_ticket( customer_id=customer_id, subject=subject, description=description, priority=priority, ) return f"Тикет #{ticket['id']} создан. URL: {ticket['url']}" # Конфигурация и создание агента config = AgentConfig( model="claude-opus-4-5", system_prompt="""Ты — агент клиентской поддержки компании TechCorp. Помогай клиентам решать проблемы, используя доступные инструменты. Всегда проверяй данные через инструменты — не полагайся на память.""", max_turns=10, ) agent = Agent( client=client, config=config, tools=[search_database, create_support_ticket], ) # Запуск агента result = agent.run( messages=[{"role": "user", "content": "У клиента ID 12345 проблема с заказом №99876"}] ) print(result.final_message) Стриминг событий агента
Для real-time взаимодействия используем astream. Это позволяет отображать промежуточные шаги: вызов инструментов, получение результатов, завершение ходов.
import asyncio async def run_agent_with_streaming(): async for event in agent.astream( messages=[{"role": "user", "content": "Проанализируй последние 10 заказов клиента ID 12345"}] ): match event.type: case "text_delta": print(event.text, end="", flush=True) case "tool_use_start": print(f"\n[Инструмент: {event.tool_name}]") case "tool_result": print(f"[Результат получен, {len(event.content)} символов]") case "agent_turn_complete": print(f"\n[Завершено за {event.turn_count} ходов]") asyncio.run(run_agent_with_streaming()) Интеграция с MCP (Model Context Protocol)
MCP позволяет подключать внешние серверы с инструментами без явного кодирования. Мы используем эту возможность для интеграции с файловой системой, базами данных и GitHub. Ниже — пример подключения трёх серверов.
from claude_agent_sdk import Agent, MCPServerConfig # MCP-серверы расширяют агента инструментами без явного определения agent_with_mcp = Agent( client=client, config=config, mcp_servers=[ MCPServerConfig( name="filesystem", command="npx", args=["-y", "@modelcontextprotocol/server-filesystem", "/workspace"], ), MCPServerConfig( name="postgres", command="npx", args=["-y", "@modelcontextprotocol/server-postgres"], env={"POSTGRES_URL": "postgresql://user:pass@localhost/db"}, ), MCPServerConfig( name="github", command="npx", args=["-y", "@modelcontextprotocol/server-github"], env={"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."}, ), ], ) # Агент теперь может работать с файлами, PostgreSQL и GitHub result = agent_with_mcp.run( messages=[{"role": "user", "content": "Прочитай файл config.yaml и создай задачи в GitHub Issues на основе TODO-комментариев"}] ) Multi-turn диалог с историей
Для поддержания контекста между ходами используем ConversationSession. Это избавляет от ручного управления историей сообщений.
from claude_agent_sdk import ConversationSession # Сессия сохраняет историю диалога session = ConversationSession( agent=agent, session_id="customer_session_12345", ) # Первый ход response1 = session.send("Что такое статус моего заказа #99876?") # Второй ход — агент помнит контекст response2 = session.send("А можно перенести доставку на завтра?") # Третий ход response3 = session.send("Подтверди, пожалуйста") print(session.get_history()) Human-in-the-loop через Approval
Безопасность критичных операций обеспечивается политикой одобрения. Мы настраиваем запрос подтверждения для деструктивных действий.
from claude_agent_sdk import Agent, ToolApprovalPolicy class CustomApprovalPolicy(ToolApprovalPolicy): """Запрашивает подтверждение для деструктивных операций""" REQUIRES_APPROVAL = {"delete_order", "process_refund", "ban_customer"} async def should_approve(self, tool_name: str, tool_input: dict) -> bool: if tool_name not in self.REQUIRES_APPROVAL: return True # Автоматически разрешаем безопасные инструменты # Уведомляем оператора await notify_operator( message=f"Требуется подтверждение: {tool_name}\nПараметры: {tool_input}", callback_url="/api/approve/{approval_id}", ) # Ждём решения (таймаут 5 минут) approval = await wait_for_approval(timeout=300) return approval.approved agent_with_approval = Agent( client=client, config=config, tools=[search_database, process_refund, ban_customer], approval_policy=CustomApprovalPolicy(), ) Практический кейс: агент финансового мониторинга
Кейс финансового мониторинга
**Задача.** У нашего клиента, финансовой компании, rule-based система ежедневно генерировала 50–200 флагов подозрительных транзакций. Финансовый офицер тратил 3 часа на ручную проверку. **Инструменты агента:** get_flagged_transactions, get_transaction_history, get_customer_profile, check_external_sanctions, create_sar_draft, escalate_to_officer. **Поток работы:** агент получает флаги, анализирует контекст, профиль клиента и историю, решает — ложное срабатывание или подозрительно. Критичные кейсы эскалируют с черновиком SAR. **Результаты:** 78% флагов обработаны автоматически, время офицера сократилось до 45 минут, качество черновиков SAR оценено в 4.3/5.0, время реакции на критические случаи уменьшилось с 4–8 часов до 15 минут. Это позволило сэкономить до 3 часов рабочего времени в день, что в денежном эквиваленте составляет более $450–650 в месяц на одного сотрудника.Сравнение подходов: ручная реализация против Claude Agent SDK
| Аспект | Ручная реализация | Claude Agent SDK |
|---|---|---|
| Время создания базового агента | 2–3 недели | 3–5 дней |
| Управление историей | Требует кода | Встроено |
| Интеграция инструментов | Ручная обёртка API | Декоратор @tool |
| Поддержка MCP | Отсутствует | Готовая конфигурация |
| Human-in-the-loop | Реализация с нуля | Политика одобрения |
Использование SDK сокращает время разработки агента в 3 раза по сравнению с ручным кодированием цикла вызовов. По нашим данным, клиенты экономят от $5.4k–7.8k в год на ручной обработке.
Типичные ошибки при интеграции и их решения
| Ошибка | Решение |
|---|---|
| Потеря контекста в длинных диалогах | Использовать ConversationSession с automatic summarization |
| Галлюцинации при работе с инструментами | Всегда проверять результаты инструментов через system_prompt |
| Задержки из-за блокирующего вызова API | Перейти на стриминг (astream) и настройку timeouts |
| Безопасность деструктивных операций | Настроить human-in-the-loop через CustomApprovalPolicy |
Процесс и сроки
- Архитектурное проектирование агента под ваш сценарий — 1–2 дня.
- Интеграция SDK с вашей инфраструктурой и настройка инструментов — 3–5 дней.
- Подключение MCP-серверов (файлы, БД, внешние API) — 1–3 дня на каждый.
- Настройка human-in-the-loop и approval flow — 1 неделя.
- Документация и обучение команды — 2–3 дня.
- Production-деплой с мониторингом — 1 неделя.
- Поддержка в течение 1 месяца после деплоя включена.
Общий срок — от 2 до 4 недель в зависимости от сложности. Точная стоимость рассчитывается индивидуально после анализа вашего сценария.
Что вы получите в результате
- Рабочий агент с настроенными инструментами и MCP-серверами.
- Полная документация по архитектуре и API.
- Доступ к исходному коду и CI/CD пайплайну.
- Обучение команды (2-3 сессии).
- Техническая поддержка на месяц после деплоя.
Почему стоит интегрировать Claude Agent SDK?
SDK даёт готовые механизмы для управления контекстом, инструментами и безопасностью, что ускоряет выход в production в 3 раза. По данным внутреннего опроса клиентов, время обработки тикетов снижается на 60%. Свяжитесь с нами для оценки вашего сценария и закажите консультацию по интеграции.