שילוב Anthropic Claude Agent SDK עבור סוכני AI

שילוב Anthropic Claude Agent SDK לבניית סוכני AI

בואו נהיה ישירים: כשלקוח מגיע עם משימה לבנות סוכן שלא רק עונה על שאלות אלא מבצע פעולות—חיפוש במאגרי נתונים, יצירת כרטיסים, עבודה עם קבצים—אנחנו יודעים שה-Anthropic Claude Agent SDK מסיר 80% מהעבודה השחורה. אבל אינטגרציה לא נכונה מובילה לאובדן הקשר והזיות. הנה איך אנחנו מגדירים את ה-SDK כדי להפוך את הסוכן לאמין בסביבת ייצור. לצוות שלנו יש ניסיון של 5+ שנים ב-NLP ו-LLMs, עם למעלה מ-20 פרויקטים שמשתמשים ב-Claude Agent SDK. אנחנו מבטיחים פעילות יציבה של הסוכן בתשתית שלכם.

בעיות שאנחנו פותרים

• סחיפת הקשר בשיחות מרובות-שלבים: ללא ניהול סשן נכון, הסוכן שוכח אינטראקציות קודמות, מה שגורם לשאלות חוזרות או לפעולות שגויות. ה-pip install anthropic claude-agent-sdk המובנה של ה-SDK מטפל בזה אוטומטית.
• מורכבות אינטגרציית כלים: עטיפה ידנית של כל קריאת API עם טיפול בשגיאות, ניסיונות חוזרים וניתוח היא שגויה וגוזלת זמן. ה-decorator @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) של ה-SDK מספק ממשק נקי ל-human-in-the-loop.

איך אנחנו עושים את זה: פרטים טכניים

אנחנו מתחילים בהתקנת ה-SDK והגדרת כלים באמצעות decorators. להלן תבנית טיפוסית שאנחנו משתמשים בה.

# 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)

לאינטראקציות בזמן אמת, אנחנו משתמשים בסטרימינג דרך 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-комментариев"}]
)

שיחות מרובות-שלבים עם היסטוריה

אנחנו משתמשים ב-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()) כדי לשמור על הקשר בין שלבים ללא ניהול היסטוריה ידני.

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 באמצעות אישורים

לפעולות הרסניות, אנחנו דורשים אישור. ה-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-комментариев"}] ) מאפשר לנו להגדיר אילו כלים דורשים אישור.

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 מקצר את זמן פיתוח הסוכן פי שלושה בהשוואה ליישום ידני. בהתבסס על הנתונים שלנו, לקוחות משיגים חיסכון שנתי משמעותי בעיבוד ידני.

טעויות נפוצות ופתרונות

תהליך ולוח זמנים

• עיצוב ארכיטקטוני של הסוכן לתרחיש שלכם — 1–2 ימים.
• אינטגרציית SDK עם התשתית שלכם והגדרת כלים — 3–5 ימים.
• חיבור שרתי MCP (קבצים, מסדי נתונים, APIs חיצוניים) — 1–3 ימים כל אחד.
• הגדרת human-in-the-loop וזרימת אישורים — שבוע אחד.
• תיעוד והדרכת צוות — 2–3 ימים.
• פריסה לייצור עם ניטור — שבוע אחד.
• תמיכה לחודש אחד לאחר הפריסה כלולה.

לוח זמנים כולל: 2 עד 4 שבועות תלוי במורכבות. עלות מדויקת מחושבת באופן אישי לאחר ניתוח התרחיש שלכם.

מה אתם מקבלים

• סוכן עובד עם כלים ושרתי MCP מוגדרים.
• תיעוד מלא על הארכיטקטורה וה-API.
• גישה לקוד מקור ו-CI/CD pipeline.
• הדרכת צוות (2–3 מפגשים).
• חודש אחד של תמיכה טכנית לאחר הפריסה.

למה לשלב את Claude Agent SDK?

ה-SDK מספק מנגנונים מובנים לניהול הקשר, כלים ואבטחה, ומאיץ את השחרור לייצור פי שלושה. לפי סקר פנימי של לקוחות, זמן עיבוד הכרטיסים יורד ב-60%. צרו קשר כדי להעריך את התרחיש שלכם ולתאם ייעוץ לאינטגרציה.