REST Resource: tasks

משאב: משימה

‫Task היא יחידת הפעולה העיקרית ב-A2A. יש לו סטטוס נוכחי, וכשהתוצאות נוצרות עבור המשימה הן נשמרות בארטיפקט. אם יש כמה תורות למשימה, הן נשמרות בהיסטוריה.

ייצוג ב-JSON 
{
  "id": string,
  "contextId": string,
  "status": {
    object (TaskStatus)
  },
  "artifacts": [
    {
      object (Artifact)
    }
  ],
  "history": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object
  }
}
שדות
id

string

חובה. מזהה ייחודי (למשל, UUID) של המשימה, שנוצר על ידי השרת למשימה חדשה.
contextId

string

מזהה ייחודי (למשל UUID) של אוסף ההקשרים של האינטראקציות (משימות והודעות).
status

object (TaskStatus)

חובה. הסטטוס הנוכחי של Task, כולל state וmessage.
artifacts[]

object (Artifact)

קבוצה של פריטי פלט בשביל Task.
history[]

object (Message)

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED The history of interactions from a Task.
metadata

object (Struct format)

protolint:enable REPEATED_FIELD_NAMES_PLURALIZED אובייקט של מפתח/ערך לאחסון מטא-נתונים מותאמים אישית לגבי משימה.

TaskStatus

מאגר לסטטוס של משימה

ייצוג ב-JSON 
{
  "state": enum (TaskState),
  "message": {
    object (Message)
  },
  "timestamp": string
}
שדות
state

enum (TaskState)

חובה. המצב הנוכחי של המשימה.
message

object (Message)

הודעה שמשויכת לסטטוס.
timestamp

string (Timestamp format)

חותמת זמן בפורמט ISO 8601 של מועד התיעוד של הסטטוס. דוגמה: ‎"2023-10-27T10:00:00Z"‎

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".

TaskState

ההגדרה הזו מגדירה את מצבי מחזור החיים האפשריים של Task.

טיפוסים בני מנייה (enum)
TASK_STATE_UNSPECIFIED סטטוס המשימה לא ידוע או לא ברור.
TASK_STATE_SUBMITTED מציין שהמשימה נשלחה ואושרה בהצלחה.
TASK_STATE_WORKING מציין שהסוכן מעבד באופן פעיל משימה.
TASK_STATE_COMPLETED מציין שמשימה הסתיימה בהצלחה. זהו מצב סופי.
TASK_STATE_FAILED מציין שמשימה הסתיימה עם שגיאה. זהו מצב סופי.
TASK_STATE_CANCELED מציין שמשימה בוטלה לפני שהושלמה. זהו מצב סופי.
TASK_STATE_INPUT_REQUIRED מציין שהסוכן צריך קלט של משתמשים נוסף כדי להמשיך. זהו מצב של הפרעה.
TASK_STATE_REJECTED מציין שהסוכן החליט לא לבצע את המשימה. הפעולה הזו יכולה להתבצע במהלך יצירת המשימה הראשונית או בשלב מאוחר יותר, אחרי שהסוכן קובע שהוא לא יכול להמשיך או שהוא לא ימשיך. זהו מצב סופי.
TASK_STATE_AUTH_REQUIRED מציין שנדרש אימות כדי להמשיך. זהו מצב של הפרעה.

הודעה

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

ייצוג ב-JSON 
{
  "messageId": string,
  "contextId": string,
  "taskId": string,
  "role": enum (Role),
  "parts": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ],
  "referenceTaskIds": [
    string
  ]
}
שדות
messageId

string

חובה. המזהה הייחודי (למשל, UUID) של ההודעה. ההודעה הזו נוצרת על ידי יוצר ההודעה.
contextId

string

זה שינוי אופציונלי. מזהה ההקשר של ההודעה. אם המאפיין מוגדר, ההודעה תשויך להקשר שצוין.
taskId

string

זה שינוי אופציונלי. מזהה המשימה של ההודעה. אם תוגדר משימה, ההודעה תשויך למשימה שצוינה.
role

enum (Role)

חובה. מזהה את השולח של ההודעה.
parts[]

object (Part)

חובה. החלק Parts הוא המאגר של תוכן ההודעה.
metadata

object (Struct format)

זה שינוי אופציונלי. כל מטא-נתונים שרוצים לספק יחד עם ההודעה.
extensions[]

string

כתובות ה-URI של התוספים שקיימים בהודעה הזו או שתורמים לה.
referenceTaskIds[]

string

רשימה של מזהי משימות שההודעה הזו מתייחסת אליהם כדי לספק הקשר נוסף.

תפקיד

ההגדרה מגדירה את השולח של הודעה בתקשורת של פרוטוקול A2A.

טיפוסים בני מנייה (enum)
ROLE_UNSPECIFIED התפקיד לא צוין.
ROLE_USER ההודעה נשלחת מהלקוח לשרת.
ROLE_AGENT ההודעה נשלחת מהשרת ללקוח.

חלק

‫Part מייצג מאגר של קטע מתוכן התקשורת. החלקים יכולים להיות טקסט בלבד, קובץ כלשהו (תמונה, סרטון וכו') או בלוב של נתונים מובְנים (למשל, JSON).

ייצוג ב-JSON 
{
  "metadata": {
    object
  },
  "filename": string,
  "mediaType": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "text": string,
  "raw": string,
  "url": string,
  "data": value
  // End of mutually exclusive fields.
}
שדות
metadata

object (Struct format)

אופציונלי. מטא-נתונים שמשויכים לחלק הזה.
filename

string

שם קובץ אופציונלי filename (לדוגמה, document.pdf).
mediaType

string

‫mediaType (סוג MIME) של תוכן החלק (לדוגמה, text/plain,‏ application/json,‏ image/png). השדה הזה זמין לכל סוגי החלקים.
הרשימה הבאה כוללת שדות שאי אפשר להשתמש בהם בו-זמנית. בכל תשובה יוגדר לכל היותר אחד מהשדות:
text

string

תוכן המחרוזת של החלק text.
raw

string (bytes format)

תוכן הקובץ בבייט raw. בסריאליזציה של JSON, הנתונים האלה מקודדים כמחרוזת base64.

מחרוזת בקידוד Base64.
url

string

‫url שמפנה לתוכן הקובץ.
data

value (Value format)

נתונים מובְנים שרירותיים data כערך JSON (אובייקט, מערך, מחרוזת, מספר, ערך בוליאני או null).
סוף השדות הבלעדיים.

ארטיפקט

ארטיפקטים מייצגים את הפלט של המשימה.

ייצוג ב-JSON 
{
  "artifactId": string,
  "name": string,
  "description": string,
  "parts": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ]
}
שדות
artifactId

string

חובה. מזהה ייחודי (למשל UUID) של הארטיפקט. הוא חייב להיות ייחודי בתוך משימה.
name

string

שם קריא לארטיפקט.
description

string

זה שינוי אופציונלי. תיאור קריא (לבני אדם) של הארטיפקט.
parts[]

object (Part)

חובה. התוכן של הארטיפקט. צריך להכיל לפחות חלק אחד.
metadata

object (Struct format)

זה שינוי אופציונלי. מטא-נתונים שנכללים עם הארטיפקט.
extensions[]

string

כתובות ה-URI של התוספים שקיימים בארטיפקט הזה או שתורמים לו.

Methods

cancel

 ביטול משימה בתהליך.

get

 מקבל את המצב האחרון של משימה.

list

 מציגה רשימה של משימות שתואמות למסנן שצוין.

subscribe

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