Copilot SDK — בנה כלים משלך

מה זה Copilot SDK — ולמה זה משנה את הכל

עד עכשיו ב-Copilot עבדתם בתוך סביבות מוכנות — VS Code, טרמינל, GitHub.com. הייתם משתמשים של הלולאה האגנטית. ה-Copilot SDK (ראשי תיבות: Software Development Kit — ערכת פיתוח תוכנה) הופך אתכם לבונים.

הרעיון פשוט ומשנה כללי משחק: אותו מנוע שמריץ את Copilot CLI — אותה לולאה אגנטית (Agentic Execution Loop) של קלט, תכנון, בחירת כלי, הפעלה, בדיקת תוצאה וחזרה — עכשיו זמין כספריה שאפשר לייבא לכל אפליקציה. לא clone, לא חיקוי — ממש אותו קוד battle-tested שמפעיל את Copilot.

בשורה תחתונה: Copilot ב-VS Code הוא אפליקציה אחת שבנויה מעל הלולאה הזו. עם ה-SDK, אתם בונים את האפליקציה. רוצים בוט שסורק PRs כל לילה? אייג'נט שעונה ללקוחות? כלי שמנתח קוד לפי סטנדרט של הצוות? ה-SDK מאפשר את כל זה.

למה לא פשוט לקרוא ל-API של OpenAI ישירות?

שאלה לגיטימית. הרי אפשר לקרוא ישירות ל-API של OpenAI, Anthropic או Google — אז למה לעבור דרך ה-SDK? התשובה: הלולאה האגנטית. כש-API רגיל מקבל פרומפט ומחזיר תשובה (one-shot), ה-SDK מריץ לולאה שלמה: הוא שולח את הפרומפט, המודל מחליט אם צריך כלי, ה-SDK מפעיל את הכלי, מחזיר את התוצאה למודל, והמודל ממשיך — שוב ושוב עד שהמשימה מושלמת. זה בדיוק מה שקורה ב-Agent Mode ב-VS Code.

אם הייתם רוצים לבנות את הלולאה הזו בעצמכם, הייתם צריכים:

• ניהול שיחה מרובת סיבובים (multi-turn)
• ניתוח תשובות המודל לזיהוי קריאות כלים (tool calls parsing)
• הפעלת כלים, טיפול בשגיאות, והחזרת תוצאות
• לוגיקת retry כשכלי נכשל
• ניהול context window ודחיסה כשהשיחה ארוכה
• streaming token-by-token

ה-SDK נותן את כל זה מוכן. כמות הקוד שחוסכים: מאות שורות של boilerplate שמישהו כבר כתב, בדק ותיקן.

5 תרחישי שימוש שווים

כדי שהרעיון יהפוך לקונקרטי — הנה תרחישים שאנשים כבר בונים עם ה-SDK:

1. בוט Code Review אוטומטי: רץ ב-GitHub Actions על כל PR, סורק שינויים, מוצא בעיות, ומשאיר הערות — בלי שמפתח אנושי ייגע
2. Slack Bot לשאלות קוד: חבר צוות שואל "@copilot מה עושה הפונקציה X?", הבוט קורא את הקוד מ-GitHub ומסביר — בתוך Slack
3. סורק תיעוד: אייג'נט שרץ כל לילה, קורא את הקוד, ומעדכן אוטומטית את ה-README ואת ה-API docs
4. מנתח dependencies: בודק חבילות ישנות, CVEs, ופותח PRs אוטומטיים לעדכון — מותאם לסטנדרט הצוות
5. עוזר onboarding: מפתח חדש מקבל בוט אישי שמכיר את כל ה-codebase ועונה על שאלות בזמן אמת

שפות נתמכות

ה-SDK זמין רשמית ב-4 שפות:

בנוסף, הקהילה פיתחה SDK-ים לא-רשמיים ל-Java, Rust ו-C++ — אבל שימו לב: אלה community-maintained ועשויים להישבר כש-API משתנה.

למה בפרק הזה נעבוד עם Node.js?

שתי סיבות מעשיות. ראשית, ה-SDK ל-Node.js הוא הכי בוגר — הוא יצא ראשון ויש לו הכי הרבה דוגמאות ותיעוד. שנית, הקונספטים זהים בכל השפות. אם תבינו את ה-API ב-TypeScript, המעבר ל-Python או Go הוא בעיקר תרגום syntax — לא שינוי חשיבה.

הנה השוואה מהירה של אותו "Hello World" בשתי שפות:

כמו שאתם רואים — ההבדל הוא camelCase מול snake_case. הלוגיקה זהה. אם אתם מפתחי Python, תרגישו בבית. הדוגמאות בפרק הזה ב-TypeScript, אבל כל קונספט מתורגם 1:1.

ה-SDK בהקשר של המערכת האקולוגית

איפה ה-SDK יושב ביחס לכלים שכבר הכרתם? בואו נסדר:

ככל שעולים בטבלה, השליטה שלכם גדלה — אבל גם כמות הקוד שצריך לכתוב. ה-SDK נותן שליטה מלאה במחיר של יותר אחריות. זו הסיבה שרוב המפתחים ישתמשו ב-Agent Mode ל-90% מהמשימות, וב-SDK ל-10% — אבל אותם 10% הם בדיוק המקרים שה-SDK בלתי ניתן להחלפה: אוטומציות, בוטים, ושירותים.

מה ה-SDK מספק — ומה לא

חשוב להבין את הגבולות:

ה-SDK הוא המנוע. את המכונית — ה-UI, ה-hosting, האינטגרציות — אתם בונים.

התקנה ו-Hello World — האייג'נט הראשון שלך

הגיע הזמן לכתוב קוד. תוך 5 דקות יהיה לכם אייג'נט חי שרץ מתוך קובץ TypeScript שלכם. בואו נבנה אותו שלב אחרי שלב.

שלב 1: יצירת פרויקט

פתחו תיקייה חדשה וצרו פרויקט Node.js:

mkdir my-copilot-agent
cd my-copilot-agent
npm init -y
npm install @github/copilot-sdk tsx

tsx מאפשר להריץ TypeScript ישירות בלי שלב build — מושלם לפיתוח מהיר.

שלב 2: קובץ האייג'נט הראשון

צרו קובץ agent.ts:

import { CopilotClient } from "@github/copilot-sdk";

async function main() {
  // יצירת הלקוח — מתחבר ל-Copilot CLI מאחורי הקלעים
  const client = new CopilotClient();

  // יצירת סשן עם מודל ספציפי
  const session = await client.createSession({
    model: "gpt-4.1"
  });

  // שליחת פרומפט והמתנה לתשובה מלאה
  const response = await session.sendAndWait({
    prompt: "Analyze this project structure and suggest improvements"
  });

  console.log(response?.data.content);

  // ניקוי
  await client.stop();
  process.exit(0);
}

main();

שלב 3: הרצה

npx tsx agent.ts

מה שקורה מאחורי הקלעים: CopilotClient מפעיל מופע של Copilot CLI, שולח את הפרומפט דרכו, ומחזיר את התשובה. ה-CLI משתמש באימות שלכם (שהגדרתם בפרק 6) ובקרדיטים של המנוי שלכם.

הבנת הזרימה — מה קורה בין השורות

בואו נפרק את מה שקורה כשמריצים את הקוד הזה:

1. new CopilotClient() — יוצר מופע שמתחבר ל-Copilot CLI ברקע. אם ה-CLI לא מותקן או לא מאומת, כאן תקבלו שגיאה
2. client.createSession({ model: "gpt-4.1" }) — פותח סשן חדש. הסשן שומר את ההיסטוריה של השיחה, הכלים הזמינים, ומצב הביצוע. אפשר לפתוח כמה סשנים במקביל
3. session.sendAndWait({ prompt: "..." }) — שולח את הפרומפט, ממתין שהלולאה האגנטית תסתיים (כולל קריאות כלים אם צריך), ומחזיר את התשובה הסופית
4. response?.data.content — הטקסט של התשובה. ה-?. כי response יכול להיות null (למשל אם הייתה שגיאה)
5. client.stop() — מנקה את כל המשאבים וסוגר את תהליך ה-CLI

נקודה חשובה: הסשן הוא stateful — הוא זוכר את כל מה שנאמר. אם תשלחו פרומפט שני, המודל יכיר את ההקשר מהפרומפט הראשון. זה מה שמאפשר שיחות multi-turn:

const r1 = await session.sendAndWait({ prompt: "List all .ts files in this project" });
console.log(r1?.data.content);

// הסשן זוכר! לא צריך לחזור על ההקשר
const r2 = await session.sendAndWait({ prompt: "Now count the lines in each of those files" });
console.log(r2?.data.content);

מה קורה כשמשנים את המודל?

החליפו "gpt-4.1" ב-"claude-sonnet" או "gemini-2.5-pro" — והריצו שוב. תשובה שונה, סגנון שונה, אותו API. זו אחת הנקודות החזקות של ה-SDK: בחירת מודל היא פרמטר, לא ארכיטקטורה. אתם לא נעולים על ספק אחד.

פתרון בעיות נפוצות בהתקנה

כמה דברים שיכולים להשתבש בשלב ההתקנה — והפתרונות:

כלים מותאמים — defineTool

האייג'נט הבסיסי שכבר יש לכם חכם — אבל מוגבל לכלים המובנים של Copilot CLI (קריאת קבצים, עריכה, חיפוש וכו'). עם defineTool אתם מרחיבים את יכולותיו: מגדירים כלי חדש, ואומרים לאייג'נט "אתה יכול להשתמש בזה".

אנטומיה של כלי מותאם

כל כלי מוגדר עם 4 חלקים:

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

import { CopilotClient, defineTool } from "@github/copilot-sdk";
import { readdirSync, statSync } from "fs";
import { join, extname } from "path";

// הגדרת הכלי
const countFiles = defineTool("count_files", {
  description: "Count files in a directory, grouped by extension",
  parameters: {
    type: "object",
    properties: {
      directory: {
        type: "string",
        description: "Path to the directory to scan"
      }
    },
    required: ["directory"]
  },
  handler: async (args: { directory: string }) => {
    const counts: Record<string, number> = {};
    const files = readdirSync(args.directory);

    for (const file of files) {
      const fullPath = join(args.directory, file);
      if (statSync(fullPath).isFile()) {
        const ext = extname(file) || "(no extension)";
        counts[ext] = (counts[ext] || 0) + 1;
      }
    }

    return { directory: args.directory, total: files.length, by_extension: counts };
  }
});

// שימוש בכלי בסשן
async function main() {
  const client = new CopilotClient();
  const session = await client.createSession({
    model: "gpt-4.1",
    tools: [countFiles]   // <-- רישום הכלי
  });

  const response = await session.sendAndWait({
    prompt: "Count all files in the current directory and tell me the breakdown"
  });

  console.log(response?.data.content);
  await client.stop();
  process.exit(0);
}

main();

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

איך המודל "יודע" מתי להשתמש בכלי?

זה קורה בזכות ה-description שכתבתם. כשהמודל מקבל את הפרומפט "Count all files", הוא רואה גם את רשימת הכלים הזמינים עם התיאורים שלהם. תיאור טוב = המודל ידע מתי לקרוא לכלי. תיאור גרוע = המודל לא ישתמש בכלי גם כשצריך. כמה כללים:

• כתבו באנגלית ברורה — המודל מבין אנגלית הכי טוב
• תארו מה הכלי עושה, לא איך — "Count files in a directory by extension" ולא "Uses readdirSync to iterate"
• ציינו את סוג הקלט והפלט — "Takes a directory path, returns a count by file type"
• תנו דוגמה אם לא ברור — "e.g., returns { '.ts': 5, '.json': 2 }"

כלים מרובים — האייג'נט מתאם בעצמו

כשרושמים כמה כלים, האייג'נט מחליט לבד באיזה סדר להשתמש בהם. למשל, אם יש לכם count_files ו-get_file_size, והפרומפט הוא "Find the largest TypeScript file" — האייג'נט עשוי:

1. קודם לקרוא ל-count_files כדי לראות אילו קבצי .ts קיימים
2. אז לקרוא ל-get_file_size על כל אחד מהם
3. לנתח את התוצאות ולהגיד לכם מה הקובץ הגדול ביותר

כל זה בלי שכתבתם שורה אחת של לוגיקת תיאום. הלולאה האגנטית מטפלת בזה.

מה ה-handler יכול להחזיר?

ל-handler יש גמישות מלאה בסוג הערך המוחזר:

• אובייקט JSON — הכי נפוץ. האייג'נט מפרש את הנתונים ומשלב אותם בתשובה. דוגמה: return { count: 42, files: ["a.ts", "b.ts"] }
• מחרוזת פשוטה — מתורגמת אוטומטית לתוצאה. דוגמה: return "Found 42 files"
• ToolResultObject — שליטה מלאה על metadata של התוצאה, כולל שגיאות. שימושי כשרוצים לסמן שהכלי נכשל בלי לזרוק exception:

  return {
    content: "File not found: /path/to/file",
    isError: true
  };

כלל אצבע: החזירו JSON כשהתוצאה מובנית (מספרים, רשימות, אובייקטים). החזירו מחרוזת כשהתוצאה היא טקסט חופשי. השתמשו ב-ToolResultObject כשצריך לסמן שגיאה.

Best Practices לכתיבת כלים

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

1. שם ברור ב-snake_case: count_files, parse_config, write_report — לא doStuff
2. description באנגלית תיאורית: המודל צריך להבין בדיוק מה הכלי עושה. שורה אחת מספיקה, אבל ספציפית
3. פרמטרים מינימליים: כל פרמטר צריך description. שימו required על מה שחובה, optional על שאר
4. Handler שלא זורק: עטפו ב-try/catch ותחזירו { error: "..." } במקום לתת ל-exception לעוף. האייג'נט מטפל טוב יותר בהודעת שגיאה מפורשת מאשר ב-crash
5. תוצאה מידית: אם ה-handler לוקח יותר מ-30 שניות — שקלו לפרק אותו לשני כלים

חיבור MCP Servers לאייג'נט

בפרק 5 חיברתם MCP servers ל-Copilot ב-VS Code — קבצי mcp.json, שרתי GitHub, filesystem ועוד. עכשיו תעשו את אותו דבר — אבל מקוד. ה-SDK תומך באותם שני סוגי שרתים שלמדתם:

חיבור שרת STDIO (מקומי)

const session = await client.createSession({
  model: "gpt-4.1",
  mcpServers: {
    filesystem: {
      type: "local",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"],
      tools: ["*"]   // כל הכלים של השרת זמינים
    }
  }
});

מה קורה: ה-SDK מפעיל את תהליך ה-MCP server, מתחבר אליו דרך stdin/stdout, וחושף את כל הכלים שלו לאייג'נט. מרגע זה, האייג'נט יכול לקרוא קבצים, לכתוב קבצים, ולחפש — בדיוק כמו שהיה יכול דרך VS Code.

חיבור שרת HTTP (מרוחק)

שרתי HTTP מתאימים כשה-MCP server רץ על מכונה אחרת — ענן, שרת צוות, או שירות SaaS. ה-SDK מתחבר דרך SSE (Server-Sent Events) לקבלת עדכונים בזמן אמת:

const session = await client.createSession({
  model: "claude-sonnet",
  mcpServers: {
    "my-api": {
      type: "http",
      url: "https://my-mcp-server.example.com/sse",
      headers: {
        "Authorization": "Bearer my-token"
      },
      tools: ["*"]
    }
  }
});

ה-headers מאפשרים להעביר authentication — ככה ה-MCP server יודע מי אתם. שימו את הטוקן במשתנה סביבה, לא בקוד: headers: { "Authorization": `Bearer ${process.env.MCP_TOKEN}` }

חיבור מרובה — כמה שרתים בו-זמנית

אפשר לחבר כמה MCP servers לסשן אחד. האייג'נט יכול להשתמש בכלים מכולם:

mcpServers: {
  filesystem: { type: "local", command: "npx", args: [...], tools: ["*"] },
  github: { type: "local", command: "npx", args: ["-y", "@github/mcp-server"], tools: ["*"] },
  database: { type: "http", url: "https://db-mcp.example.com/sse", tools: ["query", "schema"] }
}

שימו לב לפרמטר tools: עם ["*"] כל הכלים של השרת זמינים. אפשר גם לפרט רשימה ספציפית — כדי להגביל את האייג'נט רק לכלים מסוימים. זה שימושי כשאתם רוצים שהאייג'נט יוכל רק לקרוא מ-database אבל לא לכתוב.

Custom Tools + MCP — חלוקת תפקידים

שאלה שעולה: אם MCP server נותן כלים, ו-defineTool גם נותן כלים — למה צריך את שניהם? התשובה: חלוקת תפקידים.

בפרויקט טיפוסי, תשתמשו ב-MCP servers לגישה לתשתיות (קבצים, Git, DB) ובכלים מותאמים ללוגיקה העסקית. הם משלימים זה את זה.

Troubleshooting — כשהחיבור נכשל

בעיות נפוצות עם MCP servers ב-SDK:

• "Command not found": ה-MCP server לא מותקן. ודאו ש-npx -y @modelcontextprotocol/server-filesystem עובד בטרמינל רגיל לפני שמכניסים ל-SDK
• "Connection refused" (HTTP): ה-URL לא נגיש. בדקו ש-URL נכון, שה-port פתוח, ושה-headers מוגדרים נכון
• הכלים לא נראים: ודאו ש-tools: ["*"] מוגדר, או שפירטתם את שמות הכלים הנכונים
• Timeout: אם שרת MCP לוקח יותר מדי זמן לענות, ה-SDK יתנתק. ודאו שהשרת מגיב מהר

בחירת מודל — כל מודלי Copilot בידיים שלך

כשאתם בונים אייג'נט עם ה-SDK, בחירת המודל היא שלכם. כל המודלים שזמינים ב-Copilot — אותם מודלים שלמדתם בפרק 3 — זמינים גם כאן:

המכפילים חשובים: כשאתם בונים אייג'נט שרץ 100 פעמים ביום, ההבדל בין מודל 1x למודל 0.25x הוא משמעותי. אייג'נט שמשתמש ב-Claude Haiku או GPT-4.1 mini צורך רבע מהקרדיטים — מה שאומר שתוכלו להריץ אותו פי 4 יותר עם אותו תקציב.

Multi-Model Strategy — מודל שונה לכל שלב

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

// שלב 1: סיווג — מודל זול
const classifySession = await client.createSession({ model: "gpt-4.1-mini" });
const classification = await classifySession.sendAndWait({
  prompt: "Classify this file: is it a configuration, source code, test, or documentation?"
});

// שלב 2: ניתוח מעמיק — מודל חזק (רק אם צריך)
if (classification?.data.content.includes("source code")) {
  const analyzeSession = await client.createSession({ model: "claude-sonnet" });
  const analysis = await analyzeSession.sendAndWait({
    prompt: "Analyze this source file for code quality issues and security vulnerabilities"
  });
}

בדוגמה הזו, 80% מהקבצים מסווגים במודל 0.25x (זול). רק קבצי קוד מקור עוברים ניתוח מעמיק ב-1x. החיסכון: ~60% בקרדיטים לעומת הפעלת מודל 1x על הכל.

אימות — Copilot Subscription מול BYOK

ל-SDK יש שני מסלולי אימות. ההבדל ביניהם משפיע על המחיר, המודלים הזמינים, ואופן החיוב:

מסלול 1: Copilot Subscription (ברירת מחדל)

כשיוצרים CopilotClient בלי הגדרות מיוחדות, ה-SDK משתמש באימות של Copilot CLI. זה אומר:

• גישה לכל מודלי Copilot (טבלה למעלה)
• חיוב מ-premium requests של המנוי שלכם
• לא צריך מפתח API נפרד
• מוגבל לתקרת הקרדיטים של התוכנית (Pro: 300, Pro+: 1,500)

מסלול 2: BYOK (Bring Your Own Key)

עם BYOK תעבדו ישירות עם ספק מודלים — בלי לעבור דרך GitHub:

const session = await client.createSession({
  provider: {
    type: "openai-compatible",
    baseURL: "https://api.openai.com/v1",
    bearerToken: process.env.OPENAI_API_KEY
  },
  model: "gpt-4.1"
});

ספקים נתמכים ב-BYOK: OpenAI, Anthropic, Google AI Studio, AWS Bedrock, Microsoft Foundry, xAI, וכל ספק תואם OpenAI API.

דוגמה: BYOK עם Anthropic (Claude)

const session = await client.createSession({
  provider: {
    type: "openai-compatible",
    baseURL: "https://api.anthropic.com/v1",
    bearerToken: process.env.ANTHROPIC_API_KEY
  },
  model: "claude-sonnet-4-20250514"
});

דוגמה: BYOK עם AWS Bedrock

const session = await client.createSession({
  provider: {
    type: "openai-compatible",
    baseURL: "https://bedrock-runtime.us-east-1.amazonaws.com",
    bearerToken: process.env.AWS_SESSION_TOKEN,
    headers: {
      "X-Amz-Security-Token": process.env.AWS_SESSION_TOKEN
    }
  },
  model: "anthropic.claude-sonnet"
});

מגבלה חשובה: BYOK עובד עם static tokens בלבד. ה-SDK לא מרענן טוקנים אוטומטית. אם הטוקן שלכם פג תוקף (כמו ב-AWS sessions), הבקשות יכשלו ותצטרכו ליצור סשן חדש עם טוקן חדש. לכן, ב-production, תכננו מנגנון רענון מחוץ ל-SDK.

מתי כל מסלול? — ההשוואה המלאה

מעבר בין מסלולים — אפשר גם את שניהם

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

// סשן 1: Copilot subscription למשימות רגילות
const regularSession = await client.createSession({
  model: "gpt-4.1-mini"  // שימוש בקרדיטים של Copilot
});

// סשן 2: BYOK למשימות שדורשות מודל ספציפי
const specialSession = await client.createSession({
  provider: {
    type: "openai-compatible",
    baseURL: "https://api.anthropic.com/v1",
    bearerToken: process.env.ANTHROPIC_API_KEY
  },
  model: "claude-opus-4-20250514"  // מודל שלא זמין דרך Copilot
});

הגישה הזו מאפשרת אופטימיזציית עלות: משימות רגילות עוברות דרך מנוי Copilot (חינם עד התקרה), ומשימות מיוחדות דרך BYOK (חיוב לפי שימוש).

Streaming — תוצאות בזמן אמת

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

עם Streaming, התשובה מגיעה חלק-אחרי-חלק (token by token), בדיוק כמו שאתם רגילים לראות ב-ChatGPT או ב-Copilot Chat.

הפעלת Streaming

const session = await client.createSession({
  model: "claude-sonnet",
  streaming: true    // <-- זה כל מה שצריך
});

// האזנה לחלקי תשובה בזמן אמת
session.on("assistant.message_delta", (event) => {
  process.stdout.write(event.data.content);  // הדפסה ללא ירידת שורה
});

// האזנה לסיום
session.on("session.idle", () => {
  console.log("\n--- Response complete ---");
});

// שליחת הפרומפט (לא sendAndWait!)
await session.send({
  prompt: "Write a detailed analysis of the package.json in this project"
});

ההבדל המרכזי: session.send() (לא sendAndWait) — שולח את הפרומפט ומיד חוזר. התשובה מגיעה דרך ה-event listeners.

אירועים זמינים

דוגמה מעשית: CLI app עם progress indicator

הנה דוגמה שלמה שמציגה progress בזמן שהאייג'נט עובד — מושלם ל-CLI tool:

let toolCallCount = 0;
let charCount = 0;

session.on("tool.call", (event) => {
  toolCallCount++;
  process.stdout.write(`\r🔧 Using tool: ${event.data.toolName} (#${toolCallCount})...`);
});

session.on("assistant.message_delta", (event) => {
  if (charCount === 0) process.stdout.write("\r" + " ".repeat(60) + "\r");  // נקה שורת progress
  process.stdout.write(event.data.content);
  charCount += event.data.content.length;
});

session.on("session.idle", () => {
  console.log(`\n\n--- Done! ${toolCallCount} tool calls, ${charCount} characters ---`);
});

המשתמש רואה: קודם "Using tool: read_file (#1)..." שמתעדכן, ואז כשהתשובה מתחילה — הטקסט זורם. זה חוויה טובה יותר מאשר מסך ריק שמחכה 30 שניות.

sendAndWait מול send — סיכום

זיכרון מתמשך ו-Infinite Sessions

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

Session Persistence — חידוש סשן

אם אתם רוצים לחדש סשן אחרי restart (למשל, אייג'נט שעובד על משימה ארוכה), ספקו sessionId ייחודי:

// סשן ראשון
const session = await client.createSession({
  model: "gpt-4.1",
  sessionId: "my-project-scan-001"
});
// ... עבודה ...
await session.disconnect();  // שומר מצב לדיסק, לא מוחק

// אחרי restart — חידוש
const resumed = await client.createSession({
  model: "gpt-4.1",
  sessionId: "my-project-scan-001"  // אותו ID!
});
// הסשן ממשיך מאיפה שעצר

חשוב: disconnect() שומר את המצב לדיסק ומשחרר זיכרון. deleteSession() מוחק הכל לצמיתות. אל תתבלבלו ביניהם.

Infinite Sessions — סשנים ללא הגבלת אורך

כל מודל מוגבל ב-context window — כמות הטוקנים שהוא יכול "לראות" בבת אחת. כשהשיחה ארוכה מדי — למשל, אייג'נט שסורק 50 קבצים ומנתח כל אחד — ה-context מתמלא ואי אפשר להמשיך. Infinite Sessions פותרות את הבעיה: ה-SDK דוחס אוטומטית את ההיסטוריה — מסכם את מה שהיה ומשחרר מקום:

const session = await client.createSession({
  model: "gpt-4.1",
  infiniteSessions: {
    enabled: true,
    backgroundCompactionThreshold: 0.80,  // התחל דחיסה ב-80%
    bufferExhaustionThreshold: 0.95       // חובה לדחוס ב-95%
  }
});

איך זה עובד:

• כשהקונטקסט מגיע ל-80% (backgroundCompactionThreshold), ה-SDK מתחיל דחיסה ברקע — בלי לחסום אינטראקציה
• כשמגיעים ל-95% (bufferExhaustionThreshold), הדחיסה כפויה ומיידית
• הדחיסה מסכמת את ההיסטוריה בצורה אינטליגנטית — החלטות ותוצאות נשמרות, דקויות ופרטים משניים נמחקים

מתי להשתמש בכל אפשרות?

disconnect() מול deleteSession() — אל תתבלבלו

ההבדל קריטי:

• await session.disconnect() — משחרר זיכרון, שומר מצב לדיסק. אפשר לחדש אחר כך עם אותו sessionId
• await session.deleteSession() — מוחק הכל לצמיתות. אין חזרה

אם אתם לא בטוחים — השתמשו ב-disconnect(). תמיד אפשר למחוק אחר כך.

פרויקט: אייג'נט שסורק ריפוזיטורי ומייצר דוח

הגיע הזמן לחבר את כל מה שלמדתם לפרויקט אחד שלם. נבנה אייג'נט שסורק ריפוזיטורי ומייצר דוח Markdown מסודר — עם כלים מותאמים, MCP server, streaming ו-error handling.

הקוד המלא

import { CopilotClient, defineTool } from "@github/copilot-sdk";
import { readFileSync, writeFileSync, readdirSync, statSync } from "fs";
import { join, extname } from "path";

// === כלי 1: ספירת שורות ===
const countLines = defineTool("count_lines", {
  description: "Count lines of code in a file",
  parameters: {
    type: "object",
    properties: {
      filePath: { type: "string", description: "Path to the file" }
    },
    required: ["filePath"]
  },
  handler: async (args: { filePath: string }) => {
    const content = readFileSync(args.filePath, "utf-8");
    const lines = content.split("\n");
    return {
      file: args.filePath,
      totalLines: lines.length,
      nonEmptyLines: lines.filter(l => l.trim()).length
    };
  }
});

// === כלי 2: ניתוח package.json ===
const parsePackageJson = defineTool("parse_package_json", {
  description: "Parse package.json and extract key info",
  parameters: {
    type: "object",
    properties: {
      directory: { type: "string", description: "Project root directory" }
    },
    required: ["directory"]
  },
  handler: async (args: { directory: string }) => {
    try {
      const pkg = JSON.parse(readFileSync(join(args.directory, "package.json"), "utf-8"));
      return {
        name: pkg.name,
        version: pkg.version,
        dependencies: Object.keys(pkg.dependencies || {}),
        devDependencies: Object.keys(pkg.devDependencies || {}),
        scripts: Object.keys(pkg.scripts || {})
      };
    } catch {
      return { error: "No package.json found" };
    }
  }
});

// === כלי 3: כתיבת דוח ===
const writeReport = defineTool("write_report", {
  description: "Write a markdown report to a file",
  parameters: {
    type: "object",
    properties: {
      filePath: { type: "string", description: "Output file path" },
      content: { type: "string", description: "Markdown content" }
    },
    required: ["filePath", "content"]
  },
  handler: async (args: { filePath: string; content: string }) => {
    writeFileSync(args.filePath, args.content, "utf-8");
    return { success: true, path: args.filePath, bytes: args.content.length };
  }
});

// === הרצת האייג'נט ===
async function main() {
  const client = new CopilotClient();

  const session = await client.createSession({
    model: "claude-sonnet",
    streaming: true,
    tools: [countLines, parsePackageJson, writeReport],
    mcpServers: {
      filesystem: {
        type: "local",
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", process.cwd()],
        tools: ["*"]
      }
    }
  });

  // ניטור כלים
  session.on("tool.call", (event) => {
    console.log(`\n[TOOL] ${event.data.toolName}(${JSON.stringify(event.data.args).slice(0, 80)}...)`);
  });

  // Streaming output
  session.on("assistant.message_delta", (event) => {
    process.stdout.write(event.data.content);
  });

  // מחכים לסיום
  const done = new Promise<void>((resolve) => {
    session.on("session.idle", resolve);
  });

  // הפרומפט — מנחה את האייג'נט לסרוק ולדווח
  await session.send({
    prompt: `Scan this repository thoroughly. Use the following steps:
1. List all files and directories
2. Parse package.json for dependencies and scripts
3. Count lines of code in the top 10 largest source files
4. Identify the tech stack and architecture patterns
5. Write a comprehensive report to REPORT.md

Include: project overview, tech stack, file structure summary,
dependency analysis, code metrics, and 3 improvement suggestions.
Format as clean Markdown.`
  });

  await done;
  console.log("\n\n=== Report generated! Check REPORT.md ===");
  await client.stop();
  process.exit(0);
}

main();

מה קורה כשמריצים:

1. האייג'נט קורא את הפרומפט ומתכנן את המשימה
2. משתמש בכלי ה-filesystem MCP כדי לסרוק את מבנה התיקיות
3. קורא ל-parse_package_json כדי להבין את ה-dependencies
4. קורא ל-count_lines על הקבצים הגדולים
5. מנתח את כל המידע ומייצר דוח
6. קורא ל-write_report כדי לשמור את הדוח לקובץ

וכל זה — אוטונומית. אתם כותבים פרומפט אחד והאייג'נט מחליט איך לבצע.

שדרוג: הוספת סשן מרובה סיבובים

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

// שלב 1: סריקה ואיסוף נתונים
await session.send({ prompt: "First, scan the project structure and list all source files" });
await waitForIdle(session);

// שלב 2: ניתוח מעמיק (הסשן זוכר את שלב 1!)
await session.send({ prompt: "Now analyze the top 5 largest files for code quality" });
await waitForIdle(session);

// שלב 3: כתיבת הדוח
await session.send({ prompt: "Write a comprehensive REPORT.md based on everything you found" });
await waitForIdle(session);

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

הרחבה: הוספת כלי analyze_deps

לסורק ריפוזיטורי מלא, שווה להוסיף כלי שמנתח dependencies. הנה דוגמה:

const analyzeDeps = defineTool("analyze_deps", {
  description: "Analyze node_modules to count installed packages and find outdated ones",
  parameters: {
    type: "object",
    properties: {
      directory: { type: "string", description: "Project root directory" }
    },
    required: ["directory"]
  },
  handler: async (args: { directory: string }) => {
    const nodeModules = join(args.directory, "node_modules");
    try {
      const packages = readdirSync(nodeModules)
        .filter(d => !d.startsWith("."));
      return {
        totalPackages: packages.length,
        scopedPackages: packages.filter(d => d.startsWith("@")).length,
        topLevel: packages.slice(0, 20)
      };
    } catch {
      return { error: "node_modules not found. Run npm install first." };
    }
  }
});

שימו לב ל-error handling — אם node_modules לא קיים (למשל, אחרי git clone בלי npm install), הכלי מחזיר הודעת שגיאה ידידותית במקום crash.

התמודדות עם שגיאות בפרויקט

בפרויקט אמיתי, דברים ישברו. הנה כמה תרחישים נפוצים:

• הכלי מחזיר שגיאה: האייג'נט ינסה גישה אחרת או ידווח על הבעיה. לא צריך לטפל ב-handler — המודל מתמודד
• הקובץ לא קיים: ודאו שה-handler שלכם מחזיר הודעת שגיאה ברורה (לא crash). return { error: "File not found" } עדיף על exception
• Timeout: הוסיפו timeout ל-handlers ארוכים. אייג'נט שתקוע על כלי אחד חוסם את כל השיחה

שיקולי Production — מ-prototype לפרודקשן

הקוד שכתבתם עובד מצוין ב-development. אבל לפני שמריצים אותו ב-production — ב-cron job, ב-CI/CD, או כשירות — צריך להתייחס לכמה נקודות קריטיות:

1. Rate Limits

Copilot מגביל שימוש כדי למנוע עומס. כשפוגעים ב-rate limit, אתם מקבלים שגיאה זמנית. הגישה חוזרת אחרי כמה דקות, אבל אייג'נט אוטומטי צריך לדעת לטפל בזה:

async function sendWithRetry(session: any, prompt: string, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await session.sendAndWait({ prompt });
    } catch (error: any) {
      if (error.status === 429 && attempt < maxRetries) {
        const waitTime = Math.pow(2, attempt) * 1000; // exponential backoff
        console.log(`Rate limited. Waiting ${waitTime/1000}s...`);
        await new Promise(r => setTimeout(r, waitTime));
      } else {
        throw error;
      }
    }
  }
}

2. Error Handling

לעטוף כל אינטראקציה ב-try/catch. סוגי שגיאות נפוצים:

3. שכבת הפשטה (Abstraction Layer)

ה-SDK ב-Technical Preview. ה-API עשוי להשתנות. אל תפזרו קריאות SDK בכל הקוד — צרו wrapper:

// agent-wrapper.ts — שכבת הפשטה
export class MyAgent {
  private client: CopilotClient;
  private session: any;

  async init(model: string, tools: any[]) {
    this.client = new CopilotClient();
    this.session = await this.client.createSession({ model, tools });
  }

  async ask(prompt: string): Promise<string> {
    const response = await sendWithRetry(this.session, prompt);
    return response?.data.content || "";
  }

  async cleanup() {
    await this.client.stop();
  }
}

כשה-SDK ישתנה, תתקנו רק ב-agent-wrapper.ts — לא בכל הקוד.

4. עלות — חישוב שכדאי לעשות מראש

כל פרומפט שהאייג'נט שולח צורך premium requests לפי מכפיל המודל. בואו נעשה חשיבון מהיר:

אסטרטגיית חיסכון:

• השתמשו במודלים 0x/0.25x למשימות פשוטות (סיווג, תיוג, formatting)
• שמרו מודלים 1x למשימות שדורשות חשיבה (ניתוח, כתיבת קוד)
• שמרו מודלים יקרים (GPT-5, Claude Opus) לתרחישים שבאמת דורשים חשיבה עמוקה
• שקלו BYOK אם הנפח גבוה — לפעמים חיוב ישיר לספק זול יותר מ-$0.04/request
• הוסיפו cache לתשובות חוזרות — אם אותה שאלה חוזרת, אל תקראו למודל שוב

5. לוגים וניטור

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

import { appendFileSync } from "fs";

function log(level: string, message: string, data?: any) {
  const entry = JSON.stringify({
    timestamp: new Date().toISOString(),
    level,
    message,
    data
  });
  appendFileSync("agent.log", entry + "\n");
  if (level === "error") console.error(message);
}

// שימוש
session.on("tool.call", (event) => {
  log("info", `Tool called: ${event.data.toolName}`, event.data.args);
});

session.on("tool.result", (event) => {
  log("info", `Tool result`, { tool: event.data.toolName, success: !event.data.error });
});

בדקו את agent.log כל בוקר. חפשו שגיאות, rate limits, וכלים שנקראו בצורה לא צפויה.

6. Technical Preview — מה צפוי להשתנות?

ה-SDK בסטטוס Technical Preview מינואר 2026. בהתבסס על דפוסים מוכרים של GitHub, הנה מה צפוי:

• שמות מתודות: עשויים להשתנות. sendAndWait יכול להפוך ל-send עם פרמטר. לכן — wrapper
• הגדרת כלים: ה-schema של defineTool עשוי להתרחב (למשל, הוספת metadata). לא סביר שיישבר לחלוטין
• אימות: BYOK צפוי לתמוך ב-OAuth ו-managed identities — היום רק static tokens
• מודלים: חדשים יתווספו, ישנים יוסרו. שם המודל ב-SDK ישתנה. אל תעשו hard-code

העיקרון: כל מה שיכול להשתנות — הפרידו לקובץ config או ל-wrapper. מה שלא סביר שישתנה (הקונספט של client, session, send) — כנראה יישאר.

7. סיכום: רשימת בדיקה ל-Production Launch

לפני שמעלים אייג'נט SDK ל-production, וודאו:

• ☐ Abstraction layer: יש wrapper שמפריד את קוד ה-SDK מהלוגיקה העסקית
• ☐ Error handling: כל קריאה עטופה ב-try/catch עם retry
• ☐ Rate limit handling: exponential backoff מוגדר
• ☐ לוגים: tool.call, tool.result, errors — הכל נשמר לקובץ
• ☐ עלות: חישוב חודשי עם מודל, תדירות, ומכפיל
• ☐ Secrets: מפתחות API במשתני סביבה, לא בקוד
• ☐ client.stop(): נקרא תמיד בסיום — גם במקרה שגיאה (finally block)
• ☐ מודל נכון: מודל זול למשימות פשוטות, יקר רק למורכבות

שגרת עבודה

אם אתם עושים רק דבר אחד

בדקו את עצמכם

סיכום הפרק