איך לבנות סוכן Claude AI (הדרך שאני באמת עשיתי את זה)
מדריך צעד-אחר-צעד לבניית סוכן Claude AI אמיתי - מהלולאה הסוכנית ועד דיפלוימנט ב-Cloud Run, נכתב על ידי מישהו שעשה את זה בפרודקשן.
שלושה שבועות פנימה. היה לי בוט WhatsApp עובד פרוס על Cloud Run - עונה על שאלות, שולף נתונים חיים, קורא ל-APIs חיצוניים. מונע על ידי לולאת Python של 200 שורות שכתבתי מאפס. בלי פריימוורק. בלי עטיפת קסם. רק המכניקה הגולמית של tool_use.
הנה איך לעשות את זה.
המודל המנטלי של 5 הדקות
סוכן Claude הוא לא צ'אטבוט. נקודה.
צ'אטבוט לוקח קלט ומחזיר פלט. סוכן לוקח קלט, מחליט מה לעשות הלאה, עושה את זה, בודק את התוצאה, וחוזר בלולאה. ההבחנה הזו היא כל המשחק.
הלולאה, מפושטת:
1. אתה שולח ל-Claude הודעה + רשימה של כלים זמינים
2. Claude או עונה ישירות - או מבקש כלי
3. אם הוא מבקש כלי, הקוד שלך מריץ אותו ושולח בחזרה את התוצאה
4. Claude מקבל את התוצאה ומחליט שוב: לענות, או לקרוא לכלי נוסף?
5. חוזרים עד ש-Claude מפסיק לבקש כלים
זהו. הלולאה הסוכנית. היא דטרמיניסטית. אין שום דבר חכם מסתתר מאחוריה.
הבלבול? פריימוורקים שמסתירים את הלולאה הזו לפני שראית אותה פעם אחת. אני בניתי בלי אחד קודם - זו הדרך היחידה שבאמת הבנתי מה קורה.
צעד 1: הקמת הסביבה
שלושה דברים. זה כל מה שצריך לפני כתיבת קוד סוכן:
pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
ופרומפט system. פרומפט ה-system הוא החלק הכי לא-מוערך בכל הבנייה. ביליתי בערך 30% מהזמן הכולל שלי עליו - וזה הורגש. הנה השלד מהבוט שלי ב-WhatsApp:
SYSTEM = """You are a helpful assistant with access to specific tools.
When you need information you don't have, use a tool.
When you have enough information, answer directly — do not call tools unnecessarily.
Always be concise. Messages are read on mobile."""
קצר. דעתן. בלי מלל.
המסגור הטוב יותר: פרומפט ה-system שלך הוא חוזה בינך לבין המודל. היה מפורש על מתי כלים צריכים ולא צריכים לירות, או ש-Claude יאלתר בדרכים שאתה לא רוצה.
צעד 2: הגדרת הכלים
Claude צריך לדעת אילו כלים קיימים ובדיוק מה הם מצפים. זו סכמת JSON - לא קסם:
tools = [
{
"name": "search_database",
"description": "Look up a user record in the database by email address. Cannot search by name — email only.",
"input_schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "The exact email address to look up"
}
},
"required": ["email"]
}
}
]
שני כללים שלמדתי בכאב:
- תיאורים חייבים להיות ספציפיים. Claude קורא אותם כדי להחליט אם לקרוא לכלי. מעורפל = קריאות שגויות.
- סכמת הקלט חייבת להתאים בדיוק לחתימות הפונקציות שלך. אי-התאמות נשברות בשקט. עד 2 בלילה.
צעד 3: הלולאה הסוכנית ב-Python
זה הקוד בפועל. כל הדבר:
import anthropic
import json
client = anthropic.Anthropic()
def run_agent(user_message: str) -> str:
messages = [{"role": "user", "content": user_message}]
while True:
response = client.messages.create(
model="claude-opus-4-5",
max_tokens=4096,
system=SYSTEM,
tools=tools,
messages=messages
)
# Add Claude's response to the message history
messages.append({"role": "assistant", "content": response.content})
# If Claude is done — return the answer
if response.stop_reason == "end_turn":
for block in response.content:
if hasattr(block, "text"):
return block.text
# If Claude wants a tool — run it
if response.stop_reason == "tool_use":
tool_results = []
for block in response.content:
if block.type == "tool_use":
result = execute_tool(block.name, block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": str(result)
})
# Feed results back to Claude
messages.append({"role": "user", "content": tool_results})
שלושה דברים ששווים ציון:
1. messages היא היסטוריית השיחה המלאה. אתה מצרף כל תור - גם התגובות של Claude וגם תוצאות הכלי שלך. ככה Claude יודע מה כבר קרה.
2. הלולאה רצה עד stop_reason == "end_turn". Claude מחליט מתי הוא סיים. לא אתה.
3. execute_tool() הוא הדיספצ'ר שלך. הוא ממפה שמות כלים לפונקציות Python בפועל. שמור אותו פשוט - dict או משפט match.
צעד 4: דיפלוימנט ל-Cloud Run
כאן רוב המדריכים עוצרים. אל תעצרו כאן.
לרוץ מקומית זה אב-טיפוס. לרוץ על Cloud Run זה מוצר. ההבדל:
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "server.py"]
# cloudbuild.yaml
steps:
- name: 'gcr.io/cloud-builders/docker'
args: ['build', '-t', 'gcr.io/$PROJECT_ID/claude-agent', '.']
- name: 'gcr.io/cloud-builders/docker'
args: ['push', 'gcr.io/$PROJECT_ID/claude-agent']
- name: 'gcr.io/cloud-builders/gcloud'
args:
- 'run'
- 'deploy'
- 'claude-agent'
- '--image=gcr.io/$PROJECT_ID/claude-agent'
- '--region=us-central1'
- '--platform=managed'
- '--allow-unauthenticated'
- '--min-instances=1'
ה---min-instances=1 משנה אם אתם מטפלים ב-webhooks. התנעות קרות על Cloud Run יכולות לקחת 2-4 שניות - בסדר לאסינכרוני, אכזרי לצ'אט בזמן אמת.
אחסנו את ה-ANTHROPIC_API_KEY ב-Secret Manager, לא באימג' הקונטיינר. לא-סחיר.
מה הייתי עושה אחרת אחרי שישה חודשים
1. לבנות את הדיספצ'ר לפני הכלים.
בניתי כלים קודם, דיספצ'ר שני. נהיה מבולגן מהר. עכשיו אני כותב את שלד הדיספצ'ר - אפילו עם פונקציות placeholder - לפני נגיעה בהגדרות כלים.
2. לתעד כל קריאת כלי.
לא את התוצאות. את הקריאות. tool_name + input + timestamp בלוג מובנה. כשמשהו נשבר ב-23:00, תודו לעצמכם.
3. לשים מעקות בטיחות בתיאור הכלי, לא בפרומפט ה-system.
"אל תקרא לכלי הזה אם X" שייך בשדה התיאור של הכלי, איפה ש-Claude קורא אותו בזמן-החלטה - לא קבור בפרומפט system של 500 מילים.
4. לבדוק עם קלטים עוינים מוקדם.
מה קורה אם המשתמש מבקש משהו שהכלים שלך לא יכולים לטפל בו? מה אם הם שואלים בשפה אחרת? מה אם הכלי מחזיר שגיאה? בנו לזה לפני שאתם חיים.
החלק שאף אחד לא מדבר עליו
לבנות את הסוכן זה החלק הקל.
החלק הקשה הוא המערכת סביב הסוכן: איך הוא נכשל, איך אתה יודע שהוא נכשל, איך אתה מחזיר אחורה כשהוא עושה משהו לא צפוי.
אני מריץ בדיקת תקינות יומית על הבוט שלי. יש לי לוגים מובנים לכל קריאת כלי. יש לי שרשרת גיבוי - אם המודל הראשי למטה, זה מנתב לגיבוי. אלה לא פיצ'רים מפוארים. הם דרישות בסיס לכל דבר שרץ בפרודקשן.
אם אתם בונים דמו: התעלמו מהפסקה הזו.
אם אתם בונים משהו שאנשים באמת ישתמשו בו: בנו את הניטור לפני שאתם משתפים את הקישור.
מקורות
ההתייחסויות האלה תומכות במושגים הטכניים שנדונים כאן. הן לא מאמתות באופן עצמאי את הניסויים האישיים, העלויות או נתוני הביצועים המדווחים במאמר הזה. התנהגות מוצר יכולה להשתנות אחרי פרסום.
- Building effective agents: טריידאופים בעיצוב זרימות עבודה וסוכנים.
- Writing tools for agents: ממשקי כלים והערכה.
שאלות נפוצות
איך סוכן Claude שונה משימוש ב-Claude API ישירות?
ה-API הגולמי הוא בקשה-תגובה - הודעה אחת נכנסת, הודעה אחת יוצאת. סוכן עוטף את ה-API בלולאה שנותנת ל-Claude לבקש פעולות (כלים), לעבד תוצאות, ולבצע איטרציה עד שהעבודה נעשית.
האם אני צריך פריימוורק כמו LangChain או LlamaIndex?
לא. פריימוורקים מוסיפים הפשטה ונוחות; הם גם מוסיפים מורכבות והתנהגות נסתרת. לבנייה ראשונה, השתמשו ב-SDK של Anthropic ישירות. הוסיפו פריימוורק רק כשיש לכם סיבה ספציפית.
מהו tool_use ב-Anthropic API?
זה המנגנון ש-Claude משתמש בו כדי לבקש קריאת כלי. כש-Claude רוצה להריץ פונקציה, הוא מחזיר תגובה עם stop_reason: "tool_use" ובלוק מובנה שמכיל את שם הכלי והקלט. הקוד שלכם מריץ את הפונקציה ומחזיר את התוצאה.
איך מטפלים בשגיאות מכלים?
מחזירים את השגיאה כמחרוזת בתוכן ה-tool_result. Claude יקרא אותה ואו ינסה שוב, ינסה כלי אחר, או יסביר למשתמש שהוא לא יכול להשלים את הבקשה. אל תזרקו חריגות - טפלו בהן והחזירו הודעה.
איזה מודל כדאי להשתמש?
לסוכני פרודקשן: claude-opus-4-5 להנמקה מורכבת, claude-haiku-3-5 למהירות ועלות. אני משתמש ב-Haiku לכל דבר שלא דורש תכנון מרובה-צעדים.
איך מטפלים בשיחות ארוכות?
מערך ה-messages גדל עם כל תור. לסוכנים ארוכי-ריצה, תצטרכו אסטרטגיה: לסכם תורים ישנים, לקצץ עם חלון מתגלגל, או לאחסן היסטוריה במסד נתונים ולהזריק רק את הקונטקסט הרלוונטי.
האם Cloud Run הוא יעד הדיפלוימנט הנכון?
לרוב מקרי השימוש, כן. הוא סרברלס, מתכווץ לאפס, ומטפל ב-webhooks טוב. אם אתם צריכים חיבורים מתמידים (WebSockets) או התנעות קרות תת-100ms, הסתכלו על GCE או אופציית Kubernetes מנוהלת.
מה הטעות הגדולה ביותר שאנשים עושים בבניית סוכני Claude?
לדלג על פרומפט ה-system. ההתנהגות הדיפולטית טובה באופן מפתיע - טובה מספיק שאתה חושב שאתה לא צריך אחד. אתה כן. זה ההבדל בין סוכן שעושה מה שהתכוונת לאחד שעושה מה שאמרת.
אפשר להריץ את זה מקומית?
כן. קוד הלולאה רץ בכל מקום ש-Python רץ. Cloud Run הוא רק איפה שאני פורס אותו. לפיתוח מקומי, python server.py עם כלי מנהרה כמו ngrok לבדיקת webhooks.
מה הלאה אחרי שזה עובד?
זיכרון. סוכן חסר-מצב שוכח הכל בין סשנים. הוסיפו מאגר מפתח-ערך פשוט (Redis, Firestore, אפילו קובץ JSON) כדי להשאיר קונטקסט על פני שיחות. זה הקפיצה מ"דמו" ל"מוצר."
קריאה נוספת
- Claude Code Skills: מה הם ואיך אני משתמש בהם כדי לבנות סוכני AI
הסבר מעשי על סקילים של Claude Code - מה הם, איך הם עובדים, ודוגמאות אמיתיות מהסביבה שלי כולל article-humanizer, geo-faq-architect ו-llm-citation-tracker.
- GitHub Agentic Workflows GA ו-Copilot Automations: טריגרים, כלים, מגבלות קרדיט ושיפור-עצמי, לפי ה-changelogs של 28 באוקטובר
GitHub פרסמה שלושה ערכי changelog ב-28 באוקטובר: Agentic Workflows זמין באופן כללי, Copilot Automations קיבל טריגרי API, כלי MCP ומגבלות קרדיט AI, ואוטומציות יכולות להציע עריכות לעצמן. מה כל אחד אומר, ומה לבדוק.
- תפקיד ה-AI Builder: כישורים, כלים, ואיך להתחיל
תפקיד ה-AI builder, מוסבר על ידי מישהו שעושה את העבודה יומיומית: הכישורים שמשנים, הכלים ששווים לימוד, ודרך קונקרטית של 30 יום להתחיל.
יומן הבנייה
לעקוב אחרי העבודה.
מאמרים ואבטיפוסים חדשים, ישר לקורא ה-RSS שלכם. מנויי המייל בהשהיה זמנית, עד שאחבר שירות משלוח עובד. לא נאסף כאן אימייל.
עקבו ב-RSS