Package lf.a2a.v1

אינדקס

A2AService

מספק פעולות לאינטראקציה עם סוכנים באמצעות פרוטוקול A2A.

CancelTask

rpc CancelTask(CancelTaskRequest) returns (Task)

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

ניתן למצוא מידע נוסף כאן: Authentication Overview.

CreateTaskPushNotificationConfig

rpc CreateTaskPushNotificationConfig(TaskPushNotificationConfig) returns (TaskPushNotificationConfig)

יצירת הגדרת התראות למשימה.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

ניתן למצוא מידע נוסף כאן: Authentication Overview.

DeleteTaskPushNotificationConfig

rpc DeleteTaskPushNotificationConfig(DeleteTaskPushNotificationConfigRequest) returns (Empty)

מחיקת הגדרת התראה על משימה.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

ניתן למצוא מידע נוסף כאן: Authentication Overview.

GetExtendedAgentCard

rpc GetExtendedAgentCard(GetExtendedAgentCardRequest) returns (AgentCard)

מקבל את כרטיס הסוכן המורחב של הסוכן המאומת.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

ניתן למצוא מידע נוסף כאן: Authentication Overview.

GetTask

rpc GetTask(GetTaskRequest) returns (Task)

מקבל את הסטטוס העדכני של משימה.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

ניתן למצוא מידע נוסף כאן: Authentication Overview.

GetTaskPushNotificationConfig

rpc GetTaskPushNotificationConfig(GetTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig)

מקבלים הגדרת התראה בדחיפה למשימה.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

ניתן למצוא מידע נוסף כאן: Authentication Overview.

ListTaskPushNotificationConfigs

rpc ListTaskPushNotificationConfigs(ListTaskPushNotificationConfigsRequest) returns (ListTaskPushNotificationConfigsResponse)

אחזור רשימה של התראות פוש שהוגדרו למשימה.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

ניתן למצוא מידע נוסף כאן: Authentication Overview.

ListTasks

rpc ListTasks(ListTasksRequest) returns (ListTasksResponse)

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

ניתן למצוא מידע נוסף כאן: Authentication Overview.

SendMessage

rpc SendMessage(SendMessageRequest) returns (SendMessageResponse)

שליחת הודעה לנציג.

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

ניתן למצוא מידע נוסף כאן: Authentication Overview.

SendStreamingMessage

rpc SendStreamingMessage(SendMessageRequest) returns (StreamResponse)

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

ניתן למצוא מידע נוסף כאן: Authentication Overview.

SubscribeToTask

rpc SubscribeToTask(SubscribeToTaskRequest) returns (StreamResponse)

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

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

ניתן למצוא מידע נוסף כאן: Authentication Overview.

APIKeySecurityScheme

הגדרת תוכנית אבטחה באמצעות מפתח API.

שדות
description

string

תיאור אופציונלי של תוכנית האבטחה.

location

string

חובה. המיקום של מפתח ה-API. הערכים התקינים הם query,‏ header או cookie.

name

string

חובה. השם של הפרמטר של הכותרת, השאילתה או קובץ ה-Cookie שבו רוצים להשתמש.

AgentCapabilities

מגדיר יכולות אופציונליות שסוכן תומך בהן.

שדות
extensions[]

AgentExtension

רשימה של הרחבות פרוטוקול שהסוכן תומך בהן.

streaming

bool

מציין אם הסוכן תומך בתגובות סטרימינג.

push_notifications

bool

ההגדרה מציינת אם הסוכן תומך בשליחת התראות על עדכונים של משימות אסינכרוניות.

extended_agent_card

bool

מציין אם הסוכן תומך באספקת כרטיס סוכן מורחב לאחר אימות.

AgentCard

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

שדות
name

string

חובה. שם הסוכן שקריא לאנשים. דוגמה: "סוכן מתכונים"

description

string

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

supported_interfaces[]

AgentInterface

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

provider

AgentProvider

ספק השירות של הסוכן.

version

string

חובה. גרסת הסוכן. דוגמה: "1.0.0"

capabilities

AgentCapabilities

חובה. קבוצת היכולות A2A שנתמכת על ידי הסוכן.

security_schemes

map<string, SecurityScheme>

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

security_requirements[]

SecurityRequirement

דרישות אבטחה ליצירת קשר עם הסוכן.

default_input_modes[]

string

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

default_output_modes[]

string

חובה. סוגי המדיה הנתמכים כפלט מהסוכן הזה.

skills[]

AgentSkill

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

signatures[]

AgentCardSignature

חתימות אינטרנט מבוססות JSON שחושבו עבור AgentCard.

documentation_url

string

כתובת URL שכוללת מסמכים נוספים על הסוכן.

icon_url

string

זה שינוי אופציונלי. כתובת URL לסמל של הסוכן.

AgentCardSignature

‫AgentCardSignature מייצג חתימת JWS של AgentCard. הפורמט הזה תואם לפורמט JSON של חתימת רשת מבוססת JSON‏ (JWS) של RFC 7515.

שדות
protected

string

חובה. חובה. כותרת ה-JWS המוגנת של החתימה. זה תמיד אובייקט JSON בקידוד base64url.

signature

string

חובה. החתימה המחושבת, בקידוד base64url.

header

Struct

ערכי הכותרת של JWS לא מוגן.

AgentExtension

הצהרה על הרחבת פרוטוקול שנתמכת על ידי סוכן.

שדות
uri

string

מזהה משאבים אחיד (URI) ייחודי שמזהה את התוסף.

description

string

תיאור קריא לאנשים של אופן השימוש של הסוכן בתוסף.

required

bool

אם הערך הוא True, הלקוח חייב להבין את הדרישות של התוסף ולפעול בהתאם להן.

params

Struct

זה שינוי אופציונלי. פרמטרים להגדרה ספציפית של תוסף.

AgentInterface

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

שדות
url

string

חובה. כתובת ה-URL שבה הממשק הזה זמין. זו צריכה להיות כתובת URL מוחלטת ותקינה מסוג HTTPS בסביבת הייצור. דוגמה: "https://api.example.com/a2a/v1",‏ "https://grpc.example.com/a2a"

protocol_binding

string

חובה. הקישור לפרוטוקול שנתמך בכתובת ה-URL הזו. זהו מחרוזת טופס פתוחה, שאפשר להרחיב אותה בקלות לקישורי פרוטוקולים אחרים. הפורמטים העיקריים שנתמכים באופן רשמי הם JSONRPC, ‏ GRPC ו-HTTP+JSON.

tenant

string

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

protocol_version

string

חובה. הגרסה של פרוטוקול A2A שהממשק הזה חושף. מומלץ להשתמש בגרסה המשנית הנתמכת האחרונה לכל גרסה ראשית. דוגמאות: ‎0.3,‏ ‎1.0

AgentProvider

מייצג את ספק השירות של סוכן.

שדות
url

string

חובה. כתובת URL של אתר האינטרנט של ספק הסוכן או של מסמכים רלוונטיים. דוגמה: "https://ai.google.dev"

organization

string

חובה. השם של הארגון של ספק הסוכן. דוגמה: Google

AgentSkill

מייצג יכולת או פונקציה ייחודית שהנציג יכול לבצע.

שדות
id

string

חובה. מזהה ייחודי של מיומנות הסוכן.

name

string

חובה. שם של המיומנות שקריא לאנשים.

description

string

חובה. תיאור מפורט של המיומנות.

tags[]

string

חובה. קבוצה של מילות מפתח שמתארות את היכולות של המיומנות.

examples[]

string

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

input_modes[]

string

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

output_modes[]

string

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

security_requirements[]

SecurityRequirement

תוכניות אבטחה שנדרשות לשימוש במיומנות הזו.

ארטיפקט

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

שדות
artifact_id

string

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

name

string

שם של הארטיפקט שקריא לאנשים.

description

string

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

parts[]

Part

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

metadata

Struct

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

extensions[]

string

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

AuthenticationInfo

הגדרת פרטי אימות שמשמשים להתראות פוש.

שדות
scheme

string

חובה. סכמת אימות HTTP ממאגר IANA. דוגמאות: Bearer, Basic, Digest. שמות הסכימות לא תלויי-רישיות לפי RFC 9110 סעיף 11.1.

credentials

string

פרטי הכניסה של ההתראות. הפורמט תלוי בסכימה (למשל, טוקן ל-Bearer).

AuthorizationCodeOAuthFlow

הגדרת פרטים של תהליך הרשאה באמצעות קוד של OAuth 2.0.

שדות
authorization_url

string

חובה. כתובת ה-URL לאישור שתשמש בתהליך הזה.

token_url

string

חובה. כתובת ה-URL של האסימון שתשמש בתהליך הזה.

refresh_url

string

כתובת ה-URL שתשמש להשגת טוקנים לרענון.

scopes

map<string, string>

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

pkce_required

bool

מציין אם נדרש PKCE ‏ (RFC 7636) בתהליך הזה. תמיד צריך להשתמש ב-PKCE עבור לקוחות ציבוריים, ומומלץ להשתמש בו עבור כל הלקוחות.

CancelTaskRequest

מייצג בקשה לשיטת CancelTask.

שדות
tenant

string

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

id

string

חובה. מזהה המשאב של המשימה שרוצים לבטל.

metadata

Struct

מפת מפתח/ערך גמישה להעברת הקשר או פרמטרים נוספים.

ClientCredentialsOAuthFlow

הגדרת פרטי ההגדרה של תהליך פרטי הכניסה של לקוח OAuth 2.0.

שדות
token_url

string

חובה. כתובת ה-URL של האסימון שתשמש בתהליך הזה.

refresh_url

string

כתובת ה-URL שתשמש להשגת טוקנים לרענון.

scopes

map<string, string>

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

DeleteTaskPushNotificationConfigRequest

מייצג בקשה לשיטת DeleteTaskPushNotificationConfig.

שדות
tenant

string

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

task_id

string

חובה. מזהה מקור המידע של משימת ההורה.

id

string

חובה. מזהה המשאב של ההגדרה למחיקה.

DeviceCodeOAuthFlow

הגדרת פרטי התצורה של תהליך קוד המכשיר של OAuth 2.0 (RFC 8628). התהליך הזה מיועד למכשירים עם מגבלות על הקלט, כמו מכשירי IoT וכלי CLI שבהם המשתמש מאמת את עצמו במכשיר נפרד.

שדות
device_authorization_url

string

חובה. כתובת ה-URL של נקודת הקצה להרשאה של המכשיר.

token_url

string

חובה. כתובת ה-URL של האסימון שתשמש בתהליך הזה.

refresh_url

string

כתובת ה-URL שתשמש להשגת טוקנים לרענון.

scopes

map<string, string>

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

GetExtendedAgentCardRequest

מייצג בקשה לשיטת GetExtendedAgentCard.

שדות
tenant

string

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

GetTaskPushNotificationConfigRequest

מייצג בקשה לשיטת GetTaskPushNotificationConfig.

שדות
tenant

string

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

task_id

string

חובה. מזהה מקור המידע של משימת ההורה.

id

string

חובה. מזהה מקור המידע של ההגדרה שרוצים לאחזר.

GetTaskRequest

מייצג בקשה לשיטת GetTask.

שדות
tenant

string

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

id

string

חובה. מזהה המשאב של המשימה שאותה רוצים לאחזר.

history_length

int32

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

HTTPAuthSecurityScheme

הגדרה של סכמת אבטחה באמצעות אימות HTTP.

שדות
description

string

תיאור אופציונלי של תוכנית האבטחה.

scheme

string

חובה. השם של סכמת האימות של HTTP שבה יש להשתמש בכותרת Authorization, כפי שמוגדר ב-RFC7235 (למשל, Bearer). הערך הזה צריך להיות רשום במאגר של IANA Authentication Scheme.

bearer_format

string

רמז ללקוח לזיהוי הפורמט של אסימון ה-Bearer (למשל, JWT). בעיקר למטרות תיעוד.

ImplicitOAuthFlow

הוצא משימוש: במקומו יש להשתמש בקוד הרשאה + PKCE.

שדות
authorization_url

string

כתובת ה-URL לאישור שתשמש בתהליך הזה. הערך חייב להיות בפורמט של כתובת URL. תקן OAuth2 מחייב שימוש ב-TLS

refresh_url

string

כתובת ה-URL שתשמש להשגת טוקנים לרענון. הערך חייב להיות בפורמט של כתובת URL. התקן OAuth2 מחייב שימוש ב-TLS.

scopes

map<string, string>

היקפי ההרשאות שזמינים לתוכנית האבטחה OAuth2. מיפוי בין שם ההיקף לבין תיאור קצר שלו. יכול להיות שהמפה תהיה ריקה.

ListTaskPushNotificationConfigsRequest

מייצג בקשה לשיטת ListTaskPushNotificationConfigs.

שדות
tenant

string

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

task_id

string

חובה. מזהה משאב המשימה ברמת ההורה.

page_size

int32

מספר ההגדרות המקסימלי שיוחזרו.

page_token

string

טוקן של דף שהתקבל מקריאה קודמת של ListTaskPushNotificationConfigsRequest.

ListTaskPushNotificationConfigsResponse

מייצג תגובה תקינה לשיטת ListTaskPushNotificationConfigs.

שדות
configs[]

TaskPushNotificationConfig

רשימת ההגדרות של ההתראות.

next_page_token

string

אסימון לאחזור של דף התוצאות הבא, או ערך ריק אם אין יותר תוצאות ברשימה.

ListTasksRequest

פרמטרים להצגת רשימת משימות עם קריטריוני סינון אופציונליים.

שדות
tenant

string

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

context_id

string

אפשר לסנן את המשימות לפי מזהה ההקשר כדי לקבל משימות משיחה או מפגישה ספציפית.

status

TaskState

סינון משימות לפי הסטטוס הנוכחי שלהן.

page_token

string

טוקן של דף שהתקבל מקריאה קודמת של ListTasks. ListTasksResponse.next_page_token. צריך להזין את הטוקן כדי לאחזר את הדף הבא.

status_timestamp_after

Timestamp

סינון משימות שהסטטוס שלהן עודכן אחרי חותמת הזמן שצוינה בפורמט ISO 8601 (למשל, ‎2023-10-27T10:00:00Z). יוחזרו רק משימות שחותמת הזמן של הסטטוס שלהן גדולה מהערך הזה או שווה לו.

page_size

int32

מספר המשימות המקסימלי שיוחזרו. יכול להיות שהשירות יחזיר פחות מהערך הזה. אם לא מציינים ערך, יוחזרו לכל היותר 50 משימות. הערך המינימלי הוא 1. הערך המקסימלי הוא 100.

history_length

int32

מספר ההודעות המקסימלי שייכללו בהיסטוריה של כל משימה.

include_artifacts

bool

האם לכלול ארטיפקטים במשימות שמוחזרות. ברירת המחדל היא false כדי להקטין את גודל המטען הייעודי (payload).

ListTasksResponse

אובייקט התוצאה של שיטת ListTasks שמכיל מערך של משימות ומידע על חלוקה לדפים.

שדות
tasks[]

Task

חובה. מערך של משימות שתואמות לקריטריונים שצוינו.

next_page_token

string

חובה. אסימון לאחזור של דף התוצאות הבא, או ערך ריק אם אין יותר תוצאות ברשימה.

page_size

int32

חובה. גודל הדף ששימש ליצירת התשובה הזו.

total_size

int32

חובה. המספר הכולל של המשימות שזמינות (לפני חלוקה לדפים).

הודעה

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

שדות
message_id

string

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

context_id

string

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

task_id

string

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

role

Role

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

parts[]

Part

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

metadata

Struct

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

extensions[]

string

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

reference_task_ids[]

string

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

MutualTlsSecurityScheme

הגדרה של תוכנית אבטחה באמצעות אימות mTLS.

שדות
description

string

תיאור אופציונלי של תוכנית האבטחה.

OAuth2SecurityScheme

הגדרת תוכנית אבטחה באמצעות OAuth 2.0.

שדות
description

string

תיאור אופציונלי של תוכנית האבטחה.

flows

OAuthFlows

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

oauth2_metadata_url

string

כתובת ה-URL של המטא-נתונים של שרת ההרשאות ב-OAuth2‏ RFC 8414. נדרש פרוטוקול TLS.

OAuthFlows

ההגדרה הזו מגדירה את התצורה של תהליכי OAuth 2.0 הנתמכים.

שדות

שדה איחוד flow.

הערך flow יכול להיות רק אחד מהבאים:

authorization_code

AuthorizationCodeOAuthFlow

הגדרות לתהליך הרשאה באמצעות קוד של OAuth.

client_credentials

ClientCredentialsOAuthFlow

הגדרות לתהליך OAuth Client Credentials.

implicit
(deprecated)

ImplicitOAuthFlow

הוצא משימוש: במקומו יש להשתמש בקוד הרשאה + PKCE.

password
(deprecated)

PasswordOAuthFlow

הוצא משימוש: צריך להשתמש בקוד הרשאה + PKCE או בקוד מכשיר.

device_code

DeviceCodeOAuthFlow

הגדרה של תהליך קוד המכשיר ב-OAuth.

OpenIdConnectSecurityScheme

הגדרת תוכנית אבטחה באמצעות OpenID Connect.

שדות
description

string

תיאור אופציונלי של תוכנית האבטחה.

open_id_connect_url

string

חובה. כתובת URL של מסמך Discovery של OpenID Connect למטא-נתונים של ספק OIDC.

חלק

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

שדות
metadata

Struct

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

filename

string

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

media_type

string

‫media_type (סוג MIME) של תוכן החלק (לדוגמה, text/plain,‏ application/json,‏ image/png). השדה הזה זמין לכל סוגי החלקים.

שדה איחוד content.

הערך content יכול להיות רק אחד מהבאים:

text

string

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

raw

bytes

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

url

string

url שמצביע על תוכן הקובץ.

data

Value

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

PasswordOAuthFlow

הוצא משימוש: צריך להשתמש בקוד הרשאה + PKCE או בקוד מכשיר.

שדות
token_url

string

כתובת ה-URL של האסימון שתשמש בתהליך הזה. הערך חייב להיות בפורמט של כתובת URL. התקן OAuth2 מחייב שימוש ב-TLS.

refresh_url

string

כתובת ה-URL שתשמש להשגת טוקנים לרענון. הערך חייב להיות בפורמט של כתובת URL. התקן OAuth2 מחייב שימוש ב-TLS.

scopes

map<string, string>

היקפי ההרשאות שזמינים לתוכנית האבטחה OAuth2. מיפוי בין שם ההיקף לבין תיאור קצר שלו. יכול להיות שהמפה תהיה ריקה.

תפקיד

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

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

SecurityRequirement

הגדרת דרישות האבטחה של סוכן.

שדות
schemes

map<string, StringList>

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

SecurityScheme

הגדרת תוכנית אבטחה שאפשר להשתמש בה כדי לאבטח את נקודות הקצה של סוכן. זהו סוג של איחוד מובחן שמבוסס על אובייקט של תוכנית אבטחה ב-OpenAPI 3.2. למידע נוסף: https://spec.openapis.org/oas/v3.2.0.html#security-scheme-object

שדות

שדה איחוד scheme.

הערך scheme יכול להיות רק אחד מהבאים:

api_key_security_scheme

APIKeySecurityScheme

אימות מבוסס-מפתח API.

http_auth_security_scheme

HTTPAuthSecurityScheme

אימות HTTP (בסיסי, Bearer וכו').

oauth2_security_scheme

OAuth2SecurityScheme

אימות OAuth 2.0.

open_id_connect_security_scheme

OpenIdConnectSecurityScheme

אימות OpenID Connect.

mtls_security_scheme

MutualTlsSecurityScheme

אימות TLS בו-זמני (mTLS).

SendMessageConfiguration

הגדרת בקשה לשליחת הודעה.

שדות
accepted_output_modes[]

string

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

task_push_notification_config

TaskPushNotificationConfig

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

return_immediately

bool

אם true, הפעולה חוזרת מיד אחרי יצירת המשימה, גם אם העיבוד עדיין מתבצע. אם הערך הוא false (ברירת מחדל), הפעולה חייבת להמתין עד שהמשימה תגיע למצב סופי (COMPLETED, FAILED, CANCELED, REJECTED) או למצב של הפרעה (INPUT_REQUIRED, AUTH_REQUIRED) לפני שהיא חוזרת.

history_length

int32

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

SendMessageRequest

מייצג בקשה לשיטת SendMessage.

שדות
tenant

string

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

message

Message

חובה. ההודעה שרוצים לשלוח לנציג.

configuration

SendMessageConfiguration

הגדרות לבקשת השליחה.

metadata

Struct

מפת מפתח/ערך גמישה להעברת הקשר או פרמטרים נוספים.

SendMessageResponse

מייצג את התשובה ל-method‏ SendMessage.

שדות
שדה איחוד payload. המטען הייעודי (payload) של התשובה. הערך payload יכול להיות רק אחד מהבאים:
task

Task

המשימה שנוצרה או עודכנה על ידי ההודעה.

message

Message

הודעה מהסוכן.

StreamResponse

אובייקט wrapper שמשמש בפעולות סטרימינג כדי להכיל סוגים שונים של נתוני תגובה.

שדות
שדה איחוד payload. המטען הייעודי (payload) של תשובת הסטרימינג. הערך payload יכול להיות רק אחד מהבאים:
task

Task

אובייקט Task שמכיל את המצב הנוכחי של המשימה.

message

Message

אובייקט Message שמכיל הודעה מהסוכן.

status_update

TaskStatusUpdateEvent

אירוע שמציין עדכון של סטטוס המשימה.

artifact_update

TaskArtifactUpdateEvent

אירוע שמציין עדכון של פריט מידע שנוצר בתהליך פיתוח (Artifact) של משימה.

StringList

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED A list of strings.

שדות
list[]

string

ערכי המחרוזות הנפרדים.

SubscribeToTaskRequest

מייצג בקשה לשיטת SubscribeToTask.

שדות
tenant

string

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

id

string

חובה. מזהה מקור המידע של המשימה שאליה רוצים להירשם.

משימה

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

שדות
id

string

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

context_id

string

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

status

TaskStatus

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

artifacts[]

Artifact

קבוצה של פריטי מידע שנוצר בתהליך הפיתוח (Artifact) של הפלט בשביל Task.

history[]

Message

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED היסטוריית האינטראקציות מTask.

metadata

Struct

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

TaskArtifactUpdateEvent

דלתא של משימה שבה נוצר ארטיפקט.

שדות
task_id

string

חובה. המזהה של המשימה של הארטיפקט הזה.

context_id

string

חובה. המזהה של ההקשר שאליו המשימה הזו שייכת.

artifact

Artifact

חובה. הארטיפקט שנוצר או עודכן.

append

bool

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

last_chunk

bool

אם הערך הוא true, זהו החלק האחרון של הארטיפקט.

metadata

Struct

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

TaskPushNotificationConfig

מאגר שמשייך הגדרה של התראה בדחיפה למשימה ספציפית.

שדות
tenant

string

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

id

string

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

task_id

string

המזהה של המשימה שההגדרה הזו משויכת אליה.

url

string

חובה. כתובת ה-URL שאליה צריך לשלוח את ההתראה.

token

string

טוקן ייחודי למשימה או לסשן הזה.

authentication

AuthenticationInfo

נדרשים פרטי אימות כדי לשלוח את ההתראה.

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 הסמל הזה מציין שנדרש אימות כדי להמשיך. זהו מצב של הפרעה.

TaskStatus

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

שדות
state

TaskState

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

message

Message

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

timestamp

Timestamp

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

TaskStatusUpdateEvent

אירוע שנשלח על ידי הסוכן כדי להודיע ללקוח על שינוי בסטטוס של משימה.

שדות
task_id

string

חובה. המזהה של המשימה שהשתנה.

context_id

string

חובה. המזהה של ההקשר שאליו המשימה שייכת.

status

TaskStatus

חובה. הסטטוס החדש של המשימה.

metadata

Struct

זה שינוי אופציונלי. מטא-נתונים שמשויכים לעדכון המשימה.