Інтеграція Claude Agent SDK для побудови AI-агентів

Інтеграція 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 рази більше часу, що при середній ставці розробника дає економію в десятки тисяч гривень на проєкті.

Встановлення через 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, багатокрокових діалогів та безпеки?

Підключення через MCP (Model Context Protocol)

MCP дозволяє приєднувати зовнішні сервери з інструментами без явного кодування. Ми часто використовуємо цю можливість для доступу до файлової системи, баз даних та GitHub. Нижче — приклад підключення трьох серверів.

from claude_agent_sdk import Agent, MCPServerConfig

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(),
)

Практичний кейс: агент фінансового моніторингу

Порівняння підходів та типові помилки

Ручна реалізація проти Claude Agent SDK

На основі внутрішніх бенчмарків, використання SDK скорочує час розробки помічника в 3 рази порівняно з ручним кодуванням циклу викликів. Наші клієнти економлять від 600 000 грн на рік на ручній обробці.

Типові помилки при налаштуванні та їх вирішення

Як ми впроваджуємо: процес, що входить та вартість

Ми пропонуємо інтеграцію «під ключ» від 2 до 4 тижнів залежно від складності. Ось що входить у роботу:

• 📄 Архітектурне проєктування помічника під ваш сценарій — 1–2 дні.
• 🔌 Підключення SDK до вашої інфраструктури та налаштування інструментів — 3–5 днів.
• 🌐 Приєднання MCP-серверів (файли, БД, зовнішні API) — 1–3 дні на кожен.
• 🛡️ Налаштування схвалення оператором (human-in-the-loop) — 1 тиждень.
• 📝 Документація та навчання команди — 2–3 дні.
• 🚀 Production-деплой з моніторингом — 1 тиждень.
• 🤝 Підтримка протягом 1 місяця після деплою включена.

Що ви отримаєте:

• Робочий помічник з налаштованими інструментами та MCP-серверами.
• Повна документація з архітектури та API.
• Доступ до вихідного коду та CI/CD пайплайну.
• Навчання команди (2-3 сесії).
• Технічна підтримка на місяць після деплою.

Вартість: Базова інтеграція — від 50 000 грн. Точна вартість розраховується індивідуально після безкоштовної оцінки вашого сценарію. Середня економія клієнтів — 600 000 грн на рік.

Чому Claude Agent SDK краще за ручне кодування?

SDK дає готові механізми для управління контекстом, інструментами та безпекою, що прискорює вихід у production в 3 рази. SDK у 5 разів швидше впроваджує human-in-the-loop порівняно з саморобним рішенням. Зв'яжіться з нами для оцінки вашого сценарію: пишіть на пошту або замовте консультацію з інтеграції.

Практичний розбір LLM: fine-tuning, RAG, агенти, деплой

Модель GPT‑4 або Claude 3.5 Sonnet через публічне API — не рішення, а просто інструмент. Коли приходить вимога «зробити як ChatGPT, але на наших даних», за нею стоїть реальна інженерна задача: від налаштування промптів до навчання 70B‑моделі на власній інфраструктурі. LLM розробка під ключ — це складний стек, і ми займаємося цим понад 5 років. За цей час реалізовано понад 20 проєктів у галузі генеративного AI: від RAG‑систем для юридичних департаментів до кастомних агентів для техпідтримки. Де саме знаходиться ваша задача — залежить від даних, latency‑вимог, бюджету та того, наскільки критична конфіденційність.

Типова ситуація: клієнт уже спробував ChatGPT, але результати нестабільні — то відповідає точно, то галюцинує. Або потрібна інтеграція в корпоративний портал з дотриманням політик безпеки. Розберемо кожен шар стеку в деталях — від RAG до production‑деплою.

Чому RAG‑системи ламаються і як це виправити?

RAG (Retrieval‑Augmented Generation) виглядає просто: знайшли релевантні документи, поклали в контекст, модель відповіла. На практиці збоїть у кількох місцях.

Chunking без перекриття. Класична помилка: chunk_size=512, overlap=0. Якщо відповідь лежить на межі двох чанків, retrieval не знайде жодного з достатньою впевненістю. Рішення: overlap 15–25% від chunk_size, а краще sentence‑aware splitting через spaCy або NLTK, а не наївне розбиття за символами.

Поганий embedder. Текст‑embedding‑ada‑002 — хороший для загального випадку, але на юридичних або медичних текстах програє спеціалізованим моделям: E5‑large‑v2, BGE‑M3 або fine‑tuned sentence‑transformers на доменних даних. Різниця в Recall@5 може становити 15–25%.

Відсутність re‑ranking. Векторний пошук оптимізований за швидкістю, не за релевантністю. Cross‑encoder re‑ranker (ms‑marco‑MiniLM‑L‑6‑v2, bge‑reranker‑large) після первинного retrieval піднімає точність топ‑3 при прийнятній затримці (+50–150 ms). Це часто важливіше за покращення embedding‑моделі.

Гібридний пошук. Тільки dense вектори погано працюють на точних запитах: імена, артикули, коди. BM25 (sparse) добре знаходить точні збіги, але не розуміє семантику. Гібрид через RRF (Reciprocal Rank Fusion) — оптимальний компроміс. Qdrant, Weaviate та pgvector 0.7+ підтримують гібридний пошук нативно.

Коли варто fine‑tune, а не промпт‑інжиніринг?

Промпт‑інжиніринг вирішує ~70% завдань адаптації LLM під домен. Решта 30% вимагають донавчання. Три ознаки: модель ігнорує специфічний формат виведення навіть при детальному описі в промпті; задача вимагає глибокого знання спеціалізованої лексики (медицина, право); потрібно значно знизити витрати на токени, замінивши велику модель меншою спеціалізованою.

LoRA та QLoRA — стандарт для SFT. LoRA додає trainable low‑rank матриці до attention‑шарів. Типова конфігурація для Llama‑3 8B: r=64, lora_alpha=128, target_modules=["q_proj","v_proj","k_proj","o_proj"] — параметрів, що навчаються, ~0.8%, навчання на одній A100 40GB. QLoRA додає 4‑бітну квантизацію (NF4) і дозволяє fine‑tune 70B модель на двох A100 40GB, хоча швидкість падає вдвічі порівняно з bf16.

DPO замість RLHF. Direct Preference Optimization вимагає лише пари (chosen, rejected), а не скалярні reward‑сигнали. DPOTrainer з бібліотеки trl (Hugging Face) реалізує це кількома десятками рядків.

Типова помилка. Датасет з 500 прикладів, 5 епох, validation loss 0.8 — здається норм. Але на тесті модель деградувала на загальних інструкціях. Причина: catastrophic forgetting. Рішення — додати 10–20% загальних instruction‑following прикладів (Alpaca, FLAN) у навчальну вибірку, щоб не зруйнувати вихідні здібності.

Як обрати базову модель: 8B чи 70B?

Для більшості задач fine‑tuning 8B моделі достатньо. 70B потрібен, коли потрібне глибоке міркування або baseline 8B не досягає потрібної якості навіть після донавчання. Вартість інференсу Llama‑3 8B через vLLM на A100 значно нижча, ніж у GPT‑4, що робить його економічно вигідним.

Що дає PagedAttention в production?

vLLM — перший вибір для serving open‑source моделей. PagedAttention — ключове технічне рішення: KV‑cache керується як virtual memory в ОС, без фрагментації. Це дає throughput у 2–4 рази вище порівняно з наївним HuggingFace Transformers inference. Документація vLLM підтверджує: continuous batching та PagedAttention — стандарт для високонавантажених LLM‑сервісів.

Типові числа на A100 80GB для Llama‑3 8B (bf16): 400–600 req/s, P50 latency 200–400ms, P99 latency 600–900ms при concurrency 64. Для 70B на двох A100 з tensor parallelism: 80–120 req/s, P99 latency 1.5–2.5s. Квантизація AWQ або GPTQ знижує споживання пам'яті в 2 рази при втраті якості в межах 1–3%.

Мультиагентні системи

Агенти — LLM з доступом до інструментів: пошук, виконання коду, запити до API, робота з БД. Основні патерни:

• ReAct (Reason + Act): модель розмірковує → обирає інструмент → спостерігає результат → знову розмірковує. LangChain та LlamaIndex реалізують з коробки.
• Multi‑agent orchestration: кілька спеціалізованих агентів з координатором зверху. Приклад: coordinator → researcher (пошук + summarization) → coder (генерація та виконання коду) → critic (перевірка). Інструменти: AutoGen (Microsoft), CrewAI, кастомна реалізація на LangGraph.

В продакшені агентні системи недетерміновані. Обов'язкові guardrails, ліміти кроків, логування кожного кроку, human‑in‑the‑loop для критичних дій.

Як ми гарантуємо якість LLM рішення?

Ми використовуємо RAGAS для автоматичної оцінки відповідей: faithfulness, answer relevancy, context precision. Система трекінгу експериментів на базі MLflow фіксує всі метрики, датасети та конфіги. Це дозволяє порівнювати різні гіпотези та доводити покращення з цифрами. Гарантію стабільної роботи забезпечує continuous integration з тестами на специфічних сценаріях (prompt injection, edge‑cases).

Як почати LLM розробку: наступні кроки

Ми передаємо:

• Технічну документацію (model card, конфіги, інструкції з розгортання)
• Доступ до інфраструктури (репозиторій з кодом, навчені ваги)
• 1 місяць підтримки після деплою (консультації, виправлення багів)
• Навчання команди замовника (2–3 заняття з експлуатації системи)

Терміни: базовий RAG‑прототип — 1–2 тижні. Fine‑tuning з даними замовника — 3–6 тижнів (з урахуванням підготовки даних). Production‑система з моніторингом та перенавчанням — 2–4 місяці.

Вартість розраховується індивідуально і залежить від обсягу даних, складності моделі та вимог до інфраструктури. Хочете оцінити свій проєкт? Зв'яжіться з нами — ми підготуємо попереднє резюме за 1–2 робочі дні. Або замовте консультацію фахівця з вибору підходу: RAG, fine‑tuning або гібрид — розповімо, що підійде саме вам.