איך בונים Agent Card המאפשר לסוכנים אחרים לגלות את היכולות שלכם

מאת צוות מדיה דיל · 12.08.2026 · Agent Protocols · 5 דק׳

מדריך מעשי לבניית Agent Card תקני: אילו שדות חובה, איך מתארים skills בצורה שסוכנים אחרים יכולים לפרש אוטומטית, ואיך מנהלים גרסאות וגישה מדורגת.

צוות שפיתח סוכן פנימי לניתוח חוזים רצה לחשוף אותו לשימוש של סוכנים אחרים בארגון — סוכן משפטי, סוכן רכש, סוכן תמחור — כל אחד מהם צריך לגשת ליכולת אחרת ובאופן שונה מעט. הפתרון הראשוני היה תיעוד Word עם רשימת endpoints, שדרש משיחת אינטגרציה בת שעה עם כל צוות שרצה להתחבר, ונשבר בכל פעם שהצוות המפתח שינה שדה בתשובה. הפתרון הנכון היה AgentCard — מסמך JSON מובנה שמתאר את היכולות בצורה שסוכן אחר יכול לקרוא ולפרש אוטומטית, בלי שיחה אנושית בכלל. הכתיבה הנכונה של Agent Card היא ההבדל בין סוכן שנשאר "אי מבודד" לבין סוכן שבאמת משתתף באקוסיסטם רחב יותר.

השדות שחובה שיהיו נכונים

AgentCard תקני, לפי מפרט A2A, כולל שדות ליבה שכל client צריך למצוא בו: name ו-description קריאים לאדם אך גם מספיק ספציפיים לניתוח על ידי מודל שפה, url של ה-endpoint לתקשורת, capabilities שמצהיר על תמיכה ב-streaming או ב-push notifications, ו-authentication שמפרט את מנגנון ההזדהות הנדרש. הרשימה הקריטית ביותר היא skills — מערך שבו כל skill מתואר עם id ייחודי, description, ורשימת examples קונקרטיים שממחישים איך נראית קריאה טיפוסית. ה-examples חשובים במיוחד כי הם מה שסוכן קורא בפועל משתמש בהם כדי להחליט אם ה-skill מתאים למשימה שהוא צריך לבצע כרגע.

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

גרסאות ותאימות לאחור

AgentCard כולל שדה version שמתאר את גרסת הסוכן עצמו, אבל בפועל צריך גם מנגנון גרסאות לכל skill בנפרד, כי skills מתפתחים בקצב שונה מהסוכן כולו. הפרקטיקה המומלצת היא לצרף מספר גרסה לכל id של skill (contract-analysis-v2), ולהשאיר את הגרסה הישנה זמינה במקביל לתקופת מעבר, כדי שסוכנים קוראים שכבר משולבים מול הגרסה הישנה לא יישברו ברגע. רק אחרי שכל הצדדים הידועים עברו לגרסה החדשה, מסירים את הישנה מה-AgentCard.

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

גישה מדורגת: מה מפרסמים לציבור מול לשותפים מאומתים

לא כל skill צריך להיות גלוי לכל מי שמוצא את כתובת ה-AgentCard. הפרקטיקה הנכונה היא לפרסם AgentCard ציבורי מצומצם שמכיל רק skills כלליים ובטוחים, ולחשוף AgentCard מורחב — עם skills רגישים יותר, כמו גישה לנתונים פנימיים — רק אחרי אימות מוצלח מול הקורא. זה נעשה בדרך כלל דרך header ייעודי בבקשה הראשונית, שמפעיל לוגיקת שרת להחזיר גרסת AgentCard מתאימה לרמת ההרשאה של הקורא הספציפי.

• AgentCard ציבורי — skills כלליים, ללא פרטי אימות רגישים
• AgentCard מורחב לשותפים מאומתים — לאחר OAuth2 או trust handshake
• AgentCard פנימי לארגון — כל היכולות, כולל skills ניסיוניים

שכבת הגישה המדורגת הזו קשורה ישירות לתהליך אימות ההדדי בין סוכנים, שמפורט במדריך Trust Handshake בין סוכנים. בלי מנגנון כזה, כל AgentCard הופך לרשימת יכולות פומבית שכל גורם — כולל תוקפים — יכול לראות ולנסות לנצל.

איך סוכנים אחרים בפועל מגלים ומשתמשים ב-Card

תהליך הגילוי המלא נראה כך: סוכן קורא מקבל כתובת בסיס (למשל דרך registry ארגוני או המלצה מסוכן שלישי), פונה ל-/.well-known/agent.json, מקבל את ה-AgentCard, סורק את רשימת ה-skills מול המשימה שהוא צריך לבצע, ובוחר את ה-skill המתאים ביותר לפי ה-description וה-examples. אם נמצאה התאמה, הוא פותח Task חדש עם המבנה שה-skill דורש. כל השלב הזה קורה ללא מעורבות אנושית, ולכן איכות הכתיבה של ה-AgentCard משפיעה ישירות על שיעור ההצלחה של הגילוי האוטומטי הזה.

ניהול AgentCards בסקייל ארגוני, כשיש עשרות או מאות סוכנים פנימיים שכל אחד צריך AgentCard משלו, דורש registry מרכזי שמאפשר חיפוש וסינון לפי skill, בדומה לאיך שמנוהל registry לשרתי MCP. הרחבה על תבנית כזו נמצאת במדריך גילוי סוכנים ובמדריך A2A 1.0, שם מפורט גם איך ה-Task נפתח בפועל לאחר שלב הגילוי.

בדיקה עצמית לפני פרסום

לפני שמפרסמים AgentCard לסביבת ייצור, כדאי להריץ בדיקת שפיות פשוטה: לתת למודל שפה, בלי הקשר נוסף, רק את מסמך ה-AgentCard ומשימה טיפוסית שהיה צריך לבצע, ולבדוק אם הוא בוחר את ה-skill הנכון בלי טעות. אם המודל מתלבט בין שני skills או בוחר את הלא נכון, זה סימן שהתיאורים חופפים או מעורפלים מדי, ושווה לחדד אותם לפני שהבעיה מתגלה בפרודקשן מול סוכנים אמיתיים שאין להם סבלנות לבקש הבהרה.

שגיאות עיצוב שחוזרות שוב ושוב

השגיאה הראשונה והנפוצה ביותר היא AgentCard שמתאר את הסוכן במונחים שיווקיים במקום פונקציונליים — "הסוכן החכם ביותר לניתוח מסמכים" במקום תיאור מדויק של קלט, פלט ומגבלות. סוכן קורא לא מתרשם משפה שיווקית, הוא זקוק לעובדות שהוא יכול להשוות מולן. השגיאה השנייה היא רשימת skills ארוכה מדי שכוללת יכולות שוליות לצד היכולת המרכזית, מה שמקשה על הקורא לזהות מה באמת חשוב. הפרקטיקה הטובה היא לפרסם מעט skills, כל אחד מתואר בדיוק רב, ולא הרבה skills מתוארים באופן שטחי. AgentCard ממוקד וברור עולה על AgentCard מקיף אך מעורפל בכל תרחיש שימוש אמיתי שנבדק בשטח. השגיאה השלישית היא שכחת שדה ה-authentication, או השארתו ריק כי "עוד לא הוחלט" — סוכן קורא שנתקל ב-AgentCard בלי מדיניות אימות ברורה פשוט לא ידע איך לפנות בבטחה, ובמימושים רבים יתייחס לכך כאילו הסוכן לא זמין כלל, גם אם הוא בפועל פעיל ומחכה לבקשות.

תגיות: Agent Card · A2A · agent discovery · skills schema · capability description · trust handshake

← חזרה לבלוג · צור קשר