אתר שסוכנים יודעים לקרוא: llms.txt, גרסאות Markdown, OpenAPI וכרטיס שרת MCP

אתר מוכן לסוכנים הוא אתר שבו סוכן AI יכול למצוא, בלי לגרד HTML ובלי לנחש, שלושה דברים: מה השירות עושה, איך מתחברים אליו, ואיך מבצעים בו פעולה. בפועל זה חמישה קבצים או נקודות קצה: llms.txt עם תקציר ומפת קישורים, גרסת Markdown לכל עמוד, מפרט OpenAPI שמתאר את ממשק התכנות, קטלוג ב/.well-known/api-catalog, וכרטיס שרת MCP. shager.ai מפרסם את כולם, ולכן אשתמש בו כדוגמה.

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

מה זה llms.txt ומה צריך להיות בו?

llms.txt הוא הצעה שפרסם Jeremy Howard בספטמבר 2024, ומתוחזקת בllmstxt.org. זו לא תקינה של IETF או של W3C, אלא מוסכמה פתוחה. הקובץ יושב בשורש האתר, /llms.txt, ונכתב בפורמט Markdown במבנה קבוע:

1. כותרת H1 עם שם הפרויקט או האתר. זה החלק היחיד שהוא חובה.
2. ציטוט (blockquote) עם תקציר קצר.
3. פסקאות חופשיות עם מידע נוסף, בלי כותרות.
4. אפס או יותר רשימות קבצים, כל אחת תחת H2, שבהן כל פריט הוא קישור Markdown ואחריו, אם רוצים, נקודתיים והערה.

לפי ההצעה, לרשימה שנקראת Optional יש משמעות מיוחדת: אלה קישורים שסוכן יכול לדלג עליהם כשהוא צריך הקשר קצר יותר.

ככה זה נראה בllms.txt של שַׁגֵּר, בקיצור:

# Shager

> Shager (שגר) is agent-first distribution infrastructure for agencies and marketers: ...

## For AI agents
- MCP server: https://app.shager.ai/api/mcp (Authorization: Bearer <api key>; OAuth sign-in is coming)
- REST API: https://app.shager.ai/api/v1 ...

## Product
- [Shager for AI agents](https://shager.ai/md/en/agents): Connect Claude, ChatGPT or Cursor to Shager ...

## Optional
- [Sitemap](https://shager.ai/sitemap.xml)

שלוש החלטות שקיבלנו ואני ממליץ עליהן. התקציר אומר במפורש מה לא קיים עדיין (טיקטוק ולינקדאין בפיתוח), כי סוכן שמסיק יכולת שלא קיימת יטעה את המשתמש שלו. הקטע "For AI agents" מופיע לפני רשימת העמודים, כי סוכן שמגיע לקובץ צריך קודם כל לדעת איך מתחברים. והקישורים ברשימות מובילים לגרסאות Markdown ולא לעמודי HTML.

ומה עם llms-full.txt?

llms-full.txt הוא קובץ אחד עם כל התוכן של האתר בפורמט Markdown. הוא לא חלק מההצעה שבאתר llmstxt.org, אבל הוא מוסכמה נפוצה, וְשַׁגֵּר מפרסם אותו בכתובת קבועה. הוא שימושי לסוכן שרוצה לטעון את כל ההקשר בקריאה אחת, ופחות שימושי כשהאתר גדול.

גרסת Markdown לכל עמוד

ההצעה שבאתר llmstxt.org ממליצה שלכל עמוד עם מידע שימושי תהיה גרסת Markdown נקייה, ומתארת גילוי שלה דרך rel="alternate" עם type="text/markdown", כאלמנט <link> בקוד העמוד או ככותרת Link בתשובת השרת.

באתר shager.ai יש שלוש דרכים להגיע לגרסת Markdown של כל עמוד, ושלושתן עובדות:

# 1. נתיב ייעודי תחת /md
curl https://shager.ai/md/pricing

# 2. משא ומתן על תוכן: אותה כתובת, כותרת Accept אחרת
curl -H "Accept: text/markdown" https://shager.ai/pricing

# 3. גילוי דרך כותרת Link בתשובת ה HTML
curl -sI https://shager.ai/agents | grep -i '^link'
# link: </.well-known/api-catalog>; rel="api-catalog", </llms.txt>; rel="describedby"; type="text/plain", </md/agents>; rel="alternate"; type="text/markdown"

הדרך השנייה נשענת על משא ומתן על תוכן, מנגנון שמוגדר בRFC 9110 של HTTP. היתרון שלה הוא שסוכן לא צריך לדעת על מוסכמת /md מראש. הוא מבקש Markdown ומקבל Markdown.

בעמודי Markdown כדאי להוריד ניווט, כפתורים וטקסט שיווקי שתלוי בעיצוב, ולהשאיר טבלאות, קוד ועובדות. באתר shager.ai הגרסה העברית יושבת תחת /md/... והאנגלית תחת /md/en/....

OpenAPI: החוזה של ממשק התכנות

llms.txt מספר לסוכן מה קיים. מפרט OpenAPI 3.1 מספר לו בדיוק איך לקרוא לכל פעולה: נתיב, שדות, סוגים, ערכים מותרים ושגיאות. מפרט OpenAPI של שַׁגֵּר מתאר את כל הפעולות שזמינות גם ככלי MCP, עם operationId זהה לשם הכלי, כך שסוכן שקרא את המפרט יודע שהכלי create_post והקריאה POST /workspaces/{workspace_id}/posts הם אותה פעולה.

כמה דברים שהופכים מפרט OpenAPI לשימושי לסוכן, ולא רק לגנרטור קוד:

1. תיאור לכל שדה, שמסביר למה הוא משמש. אצלנו stagger_seconds מתואר כהפסקה אקראית בשניות בין חשבונות באותה רשת, עם ברירת המחדל.
2. דוגמאות בתוך התיאור במקומות שבהם הפורמט מכשיל, כמו schedule_at שמקבל ISO 8601 עם היסט.
3. ערכים מותרים כרשימה סגורה (enum), כמו FEED, REEL, STORY, SHORT, VIDEO.
4. סימון ההרשאה הנדרשת לכל פעולה. אצלנו זה שדה הרחבה x-scope.

קטלוג API: איפה ממשק התכנות נמצא

RFC 9727 מגדיר כתובת קבועה, /.well-known/api-catalog, שבה מפרסם מתאר את ממשקי התכנות שלו ומקשר אליהם. לפי התקן, הקטלוג מתפרסם בפורמט Linkset עם סוג התוכן application/linkset+json, ובקשת HEAD לכתובת צריכה להחזיר כותרת Link עם היחס api-catalog.

הקטלוג של שַׁגֵּר מקשר את כתובת הבסיס של ממשק התכנות לשני דברים: service-desc שמצביע על מפרט OpenAPI (למכונה), וservice-doc שמצביע על עמוד הסוכנים בגרסת HTML ובגרסת Markdown (לאדם או למודל). היחסים האלה מוגדרים בתקן RFC 8631, ותקן הקטלוג משתמש בהם בדוגמאות שלו.

{"linkset":[{"anchor":"https://app.shager.ai/api/v1",
  "service-desc":[{"href":"https://app.shager.ai/api/v1/openapi.json","type":"application/openapi+json"}],
  "service-doc":[{"href":"https://shager.ai/en/agents","type":"text/html"},
                 {"href":"https://shager.ai/md/en/agents","type":"text/markdown"}]}]}

כרטיס שרת MCP

כרטיס שרת MCP הוא מסמך JSON סטטי שמתאר שרת MCP מרוחק לפני שמתחברים אליו: שם, גרסה, תיאור, נקודות קצה וכותרות נדרשות. ההגדרה היא הרחבה של פרוטוקול MCP, SEP-2127, והסכמה המחייבת מתוחזקת במאגר נפרד של ההרחבה. לפי ההצעה, הכרטיס יכול לשבת בכל כתובת, והמיקום המומלץ הוא כתובת השרת עם /server-card בסוף. לגילוי לפי דומיין ההצעה מפנה לקטלוג AI בכתובת /.well-known/ai-catalog.json, ויש מימושים שמפרסמים את הכרטיס עצמו גם תחת /.well-known/mcp/.

שַׁגֵּר מפרסם את הכרטיס בשני המקומות: app.shager.ai/api/mcp/server-card וגם shager.ai/.well-known/mcp/server-card.json. החלק החשוב בו הוא remotes:

"remotes": [{
  "type": "streamable-http",
  "url": "https://app.shager.ai/api/mcp",
  "headers": [{
    "name": "Authorization",
    "description": "Bearer shgr_… API key (self-signup: POST /api/v1/agent/signup)",
    "isRequired": true,
    "isSecret": true
  }]
}]

מכאן לקוח MCP יודע בלי תיעוד נוסף שזה שרת Streamable HTTP, שצריך כותרת Authorization, ואיפה משיגים מפתח. ההצעה מסבירה שהכרטיס במתכונתו הראשונה לא אמור לפרסם את רשימת הכלים, כי כלים יכולים להשתנות לפי משתמש, ושהמקור המחייב לכלים הוא tools/list בזמן החיבור. שַׁגֵּר מוסיף רשימת כלים לכרטיס כמידע עזר, אבל סוכן צריך לסמוך על מה שהשרת מחזיר בחיבור.

שני קבצים נוספים שאינם תקן

auth.md הוא מוסכמה שלנו, לא תקן: מתכון קצר בשפה פשוטה שמסביר לסוכן איך נרשמים, מה מותר בסנדבוקס ואיך אדם תובע אותו. הקובץ נמצא כאן. והסקיל בhttps://shager.ai/skills/shager/SKILL.md כתוב בפורמט Agent Skills, כך שאפשר להוריד אותו כמו שהוא לתיקיית הסקילים של Claude Code. איך בונים סקיל כזה בעצמכם מוסבר במדריך לבניית סקיל לְשַׁגֵּר.

רשימת בדיקה לאתר שלכם

רכיב	איפה	בדיקה מהירה
llms.txt	/llms.txt	H1, תקציר, קישורים לגרסאות Markdown
Markdown לכל עמוד	/md/... או Accept: text/markdown	curl -H "Accept: text/markdown" מחזיר Markdown
כותרת Link	כל עמוד HTML	rel="alternate" עם type="text/markdown"
OpenAPI	כתובת קבועה	תיאור לכל שדה, enum, שגיאות
קטלוג API	/.well-known/api-catalog	application/linkset+json, כותרת Link בבקשת HEAD
כרטיס שרת MCP	<mcp-url>/server-card	remotes עם כותרות נדרשות

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

שאלות נפוצות

האם llms.txt משפר דירוג בגוגל?

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

צריך גם llms.txt וגם sitemap.xml?

כן, כי הם משרתים קוראים שונים. sitemap מפרט כתובות לסורק של מנוע חיפוש, והקובץ llms.txt נותן לסוכן תקציר ומפה מוערת של מה שחשוב. באתר shager.ai מפת האתר מופיעה בתוך llms.txt תחת Optional.

מה עדיף לסוכן, OpenAPI או שרת MCP?

תלוי איפה הסוכן רץ. סוכן בתוך Claude Code, Cursor או Codex עובד הכי טבעי עם שרת MCP. סקריפט או שירות בקוד ישתמשו בממשק REST לפי מפרט OpenAPI. בְּשַׁגֵּר שניהם חושפים את אותן פעולות, כך שאין צורך לבחור פעם אחת ולתמיד.