איך לבנות את סוכן ה-AI הראשון שלכם: מודל, כמה כלים, ולולאה

"סוכן AI" נשמע כאילו הוא אמור לדרוש framework, מסד נתונים וקטורי, וסוף שבוע של התקנות. הוא לא. ההגדרה של Anthropic עצמה קטנה באופן מרענן: סוכן הוא LLM שמשתמש בכלים באופן אוטונומי בתוך לולאה. ברגע שאתם רואים את התבנית, אתם יכולים לבנות סוכן ראשון שימושי בהרבה פחות ממאה שורות קוד — ובאותה מידת חשיבות, לדעת מתי לא כדאי לכם.

הלולאה המרכזית

כל סוכן, ולא משנה כמה מתוחכם, הוא אותו מחזור בן ארבעה שלבים:

1. אתם נותנים למודל מטרה ורשימה של כלים שמותר לו לקרוא להם.
2. המודל מחליט אם לענות ישירות או לקרוא לכלי.
3. הקוד שלכם מריץ את הכלי ומזין את התוצאה בחזרה למודל.
4. חוזרים על כך עד שהמודל אומר שסיים.

המודל אף פעם לא נוגע במערכת הקבצים או ברשת שלכם בעצמו. הוא רק מבקש להריץ כלי; הקוד שלכם מחליט אם וכיצד לעשות זאת בפועל. הפער הזה הוא המקום שבו נמצאת כל הבטיחות שלכם.

דוגמה קונקרטית

הנה סוכן מינימלי שיכול לענות על שאלות באמצעות כלי מחשבון. המבנה הוא מה שחשוב — אותה צורה מתרחבת לעריכת קבצים, חיפוש ברשת, או שאילתות למסד נתונים.

import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "calculator",
    "description": "Evaluate a basic arithmetic expression and return the result.",
    "input_schema": {
        "type": "object",
        "properties": {"expression": {"type": "string"}},
        "required": ["expression"],
    },
}]

def run_tool(name, args):
    if name == "calculator":
        # In real code, use a safe parser, not eval()
        return str(eval(args["expression"], {"__builtins__": {}}))
    return "unknown tool"

messages = [{"role": "user", "content": "What is 1894 * 37 plus 12?"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason != "tool_use":
        print(resp.content[0].text)
        break

    tool_results = []
    for block in resp.content:
        if block.type == "tool_use":
            result = run_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
    messages.append({"role": "user", "content": tool_results})

לולאת ה-while הזו היא הסוכן. המודל רואה את השאלה, מבקש לקרוא ל-calculator עם "1894 * 37 + 12", הקוד שלכם מריץ אותו, מחזיר 70090, והמודל כותב את התשובה הסופית. החליפו את המחשבון בזוג read_file/write_file וקיבלתם סוכן קוד פרימיטיבי.

הכלים הם החלק שבאמת חשוב

המודל מסוגל בדיוק כמו הכלים שאתם נותנים לו, ועיצוב הכלים הוא המקום שבו רוב הסוכנים הראשונים נכשלים. ההנחיות של Anthropic לגבי כתיבת כלים עבור סוכנים מסתכמות בכמה כללים:

• תנו שם ותארו כלים כאילו אתם כותבים עבור חבר צוות חדש. search_invoices(customer_id, date_range) עדיף על query(sql) עמום — ככל שהחוזה ברור יותר, כך פחות קריאות שגויות.
• החזירו תוצאות עתירות-אות (signal), לא היזרקויות גולמיות. אם כלי מחזיר 5,000 שורות של JSON, בזבזתם זה עתה את תקציב ההקשר (context) של המודל על רעש. גזמו למה שמועיל.
• הפכו את השגיאות למלמדות. "File not found: did you mean config.yaml?" מאפשר למודל להתאושש; stack trace ערום בדרך כלל לא.

מעקות בטיחות לפני שאתם נותנים לו לרוץ

מכיוון שהקוד שלכם מריץ כל קריאה לכלי, הבטיחות באחריותכם. שלושה מעקות בטיחות שכדאי להוסיף לפני שסוכן כלשהו נוגע במשהו אמיתי:

• הגבילו את הלולאה. הוסיפו ספירת איטרציות מקסימלית כך שסוכן מבולבל לא יוכל להסתובב לנצח (ולצבור חשבון גבוה).
• שמרו על פעולות הרסניות בשער. כל דבר שמוחק, שולח או משלם צריך לדרוש אישור או לרוץ קודם מול ארגז חול (sandbox).
• אמתו את הקלטים לכלים. אף פעם אל תריצו eval() על מחרוזות לא-מהימנות ואל תעבירו פלט מודל ישירות אל shell. התייחסו לכל ארגומנט של כלי כאל קלט משתמש לא-מהימן — כי למעשה זה מה שהוא.

מתי לא לבנות סוכן

הדבר השימושי ביותר ללמוד מוקדם: בעיות רבות לא צריכות סוכן בכלל. אם השלבים ידועים מראש — להביא נתונים, לסכם אותם, לשלוח את הסיכום במייל — סקריפט פשוט עם קריאה אחת או שתיים למודל הוא זול יותר, מהיר יותר, וקל יותר לדיבוג. Anthropic מכנה את אלה workflows, וממליצה עליהם בכל פעם שהמסלול צפוי. הושיטו יד לסוכן אמיתי רק כשהמודל באמת צריך להחליט מה לעשות בשלב הבא בהתבסס על מה שהוא מגלה.

התחילו עם הלולאה בת ארבעת השלבים שלמעלה, תנו לה כלי אחד או שניים מתוארים היטב, הגבילו את האיטרציות, והוסיפו משימה אמיתית. תלמדו יותר מסוכן עובד אחד מאשר מכל כמות של תיעוד framework.