Copilot ב-SDK

client.copilot מאפשר לשלוט מקוד ב-Copilot, עוזר התהליכים של Nodaro. שיחה נפתחת על תהליך מסוים, ופנייה היא הודעה אחת, יחד עם כל מה שהעוזר עושה כדי לענות עליה. המתודות קוראות ל-/v1/copilot/*. כדי לקרוא על היכולת עצמה, ראו את הדף בניית תהליך עם ה-Copilot.

ה-Copilot עובד רק בתוך אפליקציה של Nodaro. כל נתיב דוחה עם 403 in_app_only כל קריאה שלא נשלחת עם הסשן של המשתמש המחובר עצמו. ה-SDK זורק את השגיאה הזו כ-ForbiddenError. השדה code שלה הוא forbidden, ולכן כדי לזהות אותה בדקו את השדה message. אסימוני API ואסימוני OAuth לא יכולים לשלוט ב-Copilot של אף משתמש. השתמשו בו מאפליקציית דפדפן עם supabaseAuth. ה-Copilot רץ ב-Nodaro Cloud. בפריסה שבה היכולת כבויה, פתיחת שיחה או שליחת פנייה נדחות עם 503 feature_disabled.

מתודות

המתודות האלה מחזירות את מעטפת ה-{ data } של ה-API כמו שהיא מגיעה, חוץ מ-stream(), שמחזירה אירועים בזה אחר זה.

client.copilot

create(input)‎

פותחת שיחה. אפשר לשלוח workflowId של תהליך קיים, או prompt, ואז השרת יוצר תהליך שמתחיל מהפרומפט הזה. פתיחת שיחה על תהליך שכבר יש לו שיחה פעילה מחזירה את השיחה הזו, ולא פותחת שיחה שנייה.

create(input: { workflowId?: string; prompt?: string; name?: string }): Promise<{
  data: { thread: CopilotThread; workflow: CopilotThreadWorkflow }
}>

const { data } = await client.copilot.create({ workflowId })
const threadId = data.thread.id

לשיחה יש id, workflowId, runMode (ask, שמציע הרצות ומחכה, או auto, שמריץ בגבולות autoRunLimitCredits), modelTier, allowPublishing, userTurnCount, lastMessageAt ו-createdAt. השדה surface מציין לאיזה עוזר השיחה שייכת; כשהשדה חסר, הפריסה לא ציינה זאת.

list(params)‎

מחזירה את השיחה הפעילה של תהליך, או null כשאין שיחה כזו.

list(params: { workflowId: string }): Promise<{ data: { thread: CopilotThread | null } }>

const { data: { thread } } = await client.copilot.list({ workflowId })

get(id, opts?)‎

מחזירה שיחה עם ההודעות שלה. השיחה כוללת גם status מחושב (running או idle) ואת activeTurnId.

get(id: string, opts?: { after?: number; limit?: number }): Promise<{
  data: { thread: CopilotThread; messages: CopilotMessage[] }
}>

const { data: { messages } } = await client.copilot.get(threadId, { after: lastSeq })

לכל הודעה יש id, seq, turnId, role, createdAt ו-parts: חלקי טקסט וחלקים של קריאות לכלים.

archive(id)‎

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

archive(id: string): Promise<{ data: { archived: true } }>

await client.copilot.archive(threadId)

cancel(id)‎

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

cancel(id: string): Promise<{ data: { cancelling: true; turnId: string } }>

await client.copilot.cancel(threadId)

stream(threadId, opts)‎

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

stream(threadId: string, opts: {
  message: string
  baseVersion?: number
  tier?: "economy" | "standard" | "premium"
  signal?: AbortSignal
}): AsyncGenerator<CopilotStreamFrame>

try {
  for await (const frame of client.copilot.stream(threadId, { message: "Tidy the graph" })) {
    if (frame.type === "token") appendText(frame.data.text)
    if (frame.type === "run_proposed") await askTheUser(frame.data)
    if (frame.type === "done") break
  }
} catch (err) {
  if ((err as Error).name !== "AbortError") throw err // a stopped turn is a normal ending
}

הטיפוס CopilotStreamFrame הוא union שמובחן לפי type:

השדה data של אירוע מועבר כמו שהוא, ולכן גם שדות שה-SDK לא מגדיר מגיעים אליכם. ה-SDK מדלג על סוג אירוע שהוא לא מגדיר, במקום לזרוק שגיאה, כך ששרת חדש יותר לא יכול לשבור לקוח ישן יותר. הגרסה הזו לא מגדירה את action_proposed, כרטיס ההצעה של שיחות שה-surface שלהן הוא studio, ולכן ההצעות האלה לא מגיעות לקוד שקורא למתודה.

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