MCP Tools Reference: ces.googleapis.com

כלי: get_conversation

הצגת פרטים של השיחה שצוינה.

בדוגמת הקוד הבאה מוסבר איך להשתמש ב-curl כדי להפעיל את כלי ה-MCP‏ get_conversation.

בקשת Curl 
curl --location 'https://ces.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "get_conversation",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

סכימת הקלט

הודעת בקשה עבור AgentService.GetConversation.

GetConversationRequest

ייצוג ב-JSON 
{
  "name": string,
  "source": enum (Source)
}
שדות
name

string

חובה. שם המשאב של השיחה שרוצים לאחזר.
source
(deprecated)

enum (Source)

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

מקור

מקור השיחה.

טיפוסים בני מנייה (enum)
SOURCE_UNSPECIFIED מקור לא מוגדר.
LIVE השיחה היא ממשתמש קצה פעיל.
SIMULATOR השיחה היא מהסימולטור.
EVAL השיחה היא מההערכה.
AGENT_TOOL השיחה היא מכלי של סוכן. הכלי Agent מריץ את הנציג בסשן נפרד, שנשמר למטרות בדיקה וניפוי באגים.

סכימת הפלט

שיחה מייצגת אינטראקציה בין משתמש קצה לבין אפליקציית CES.

שיחה

ייצוג ב-JSON 
{
  "name": string,
  "startTime": string,
  "endTime": string,
  "turns": [
    {
      object (Turn)
    }
  ],
  "turnCount": integer,
  "channelType": enum (ChannelType),
  "source": enum (Source),
  "inputTypes": [
    enum (InputType)
  ],
  "entryAgent": string,
  "deployment": string,
  "appVersion": string,
  "languageCode": string,
  "messages": [
    {
      object (Message)
    }
  ]
}
שדות
name

string

מזהה. המזהה הייחודי של השיחה. פורמט: projects/{project}/locations/{location}/apps/{app}/conversations/{conversation}
startTime

string (Timestamp format)

פלט בלבד. חותמת הזמן של מועד יצירת השיחה.

הפורמט הוא 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".
endTime

string (Timestamp format)

פלט בלבד. חותמת זמן של מועד סיום השיחה.

הפורמט הוא 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".
turns[]

object (Turn)

חובה. התורות בשיחה.
turnCount

integer

פלט בלבד. מספר התורות בשיחה.
channelType
(deprecated)

enum (ChannelType)

הוצא משימוש. במקומה, השתמש במדיניות input_types.
source

enum (Source)

פלט בלבד. מציינים את מקור השיחה.
inputTypes[]

enum (InputType)

פלט בלבד. סוגי הקלט של השיחה.
entryAgent

string

פלט בלבד. הסוכן שמטפל בשיחה בהתחלה. אם לא מציינים נציג, השיחה מטופלת על ידי הנציג הראשי. פורמט: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
deployment

string

פלט בלבד. הפריסה של האפליקציה שמשמשת לעיבוד השיחה. פורמט: projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}
appVersion

string

פלט בלבד. גרסת האפליקציה שמשמשת לעיבוד השיחה. פורמט: projects/{project}/locations/{location}/apps/{app}/versions/{version}
languageCode

string

פלט בלבד. קוד השפה של השיחה.
messages[]
(deprecated)

object (Message)

הוצאה משימוש, במקום זאת, אפשר להשתמש בתורות.

חותמת הזמן

ייצוג ב-JSON 
{
  "seconds": string,
  "nanos": integer
}
שדות
seconds

string (int64 format)

מייצג שניות של זמן UTC מאז ראשית זמן יוניקס (Unix epoch) ‏1970-01-01T00:00:00Z. הערך חייב להיות בין ‎-62135596800 ל-253402300799, כולל (טווח שמתאים ל-‎0001-01-01T00:00:00Z עד ‎9999-12-31T23:59:59Z).
nanos

integer

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

פנייה

ייצוג ב-JSON 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "rootSpan": {
    object (Span)
  },
  "userIntendedText": string
}
שדות
messages[]

object (Message)

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

object (Span)

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

string

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

הודעה

ייצוג ב-JSON 
{
  "role": string,
  "chunks": [
    {
      object (Chunk)
    }
  ],
  "eventTime": string
}
שדות
role

string

זה שינוי אופציונלי. התפקיד בשיחה, למשל: משתמש, נציג.
chunks[]

object (Chunk)

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

string (Timestamp format)

זה שינוי אופציונלי. חותמת הזמן של שליחת או קבלת ההודעה. אין להשתמש אם ההודעה היא חלק מ-example.

הפורמט הוא 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".

מקטע

ייצוג ב-JSON 
{

  // Union field data can be only one of the following:
  "text": string,
  "transcript": string,
  "blob": {
    object (Blob)
  },
  "payload": {
    object
  },
  "image": {
    object (Image)
  },
  "toolCall": {
    object (ToolCall)
  },
  "toolResponse": {
    object (ToolResponse)
  },
  "agentTransfer": {
    object (AgentTransfer)
  },
  "updatedVariables": {
    object
  },
  "defaultVariables": {
    object
  }
  // End of list of possible types for union field data.
}
שדות
שדה של איחוד data. נתוני המקטע. הערך data יכול להיות רק אחד מהבאים:
text

string

זה שינוי אופציונלי. נתוני טקסט.
transcript

string

זה שינוי אופציונלי. תמליל שמשויך לאודיו.
blob

object (Blob)

זה שינוי אופציונלי. נתוני Blob.
payload

object (Struct format)

זה שינוי אופציונלי. נתוני מטען ייעודי (payload) בהתאמה אישית.
image

object (Image)

זה שינוי אופציונלי. נתוני התמונה.
toolCall

object (ToolCall)

זה שינוי אופציונלי. בקשה להפעלת כלי.
toolResponse

object (ToolResponse)

זה שינוי אופציונלי. תגובה להרצת הכלי.
agentTransfer

object (AgentTransfer)

זה שינוי אופציונלי. אירוע העברה של סוכן.
updatedVariables

object (Struct format)

מבנה שמייצג משתנים שעודכנו בשיחה, עם מפתחות לפי שמות המשתנים.
defaultVariables

object (Struct format)

מבנה שמייצג משתני ברירת מחדל בתחילת השיחה, עם מפתחות לפי שמות המשתנים.

כתם

ייצוג ב-JSON 
{
  "mimeType": string,
  "data": string
}
שדות
mimeType

string

חובה. סוג ה-MIME של נתוני המקור לפי תקן IANA.
data

string (bytes format)

חובה. בייטים גולמיים של ה-blob.

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

Struct

ייצוג ב-JSON 
{
  "fields": {
    string: value,
    ...
  }
}
שדות
fields

map (key: string, value: value (Value format))

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

אובייקט שמכיל רשימה של צמדי "key": value. לדוגמה: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

ייצוג ב-JSON 
{
  "key": string,
  "value": value
}
שדות
key

string
value

value (Value format)

ערך

ייצוג ב-JSON 
{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}
שדות
שדה של איחוד kind. סוג הערך. הערך kind יכול להיות רק אחד מהבאים:
nullValue

null

מייצג null ב-JSON.
numberValue

number

מייצג מספר ב-JSON. אסור להשתמש בערכים NaN,‏ Infinity או -Infinity, כי אין להם תמיכה ב-JSON. הוא גם לא יכול לייצג ערכי Int64 גדולים, כי בדרך כלל פורמט JSON לא תומך בהם בסוג המספר שלו.
stringValue

string

מייצג מחרוזת JSON.
boolValue

boolean

מייצג ערך בוליאני של JSON (ליטרל true או false ב-JSON).
structValue

object (Struct format)

מייצג אובייקט JSON.
listValue

array (ListValue format)

מייצג מערך JSON.

ListValue

ייצוג ב-JSON 
{
  "values": [
    value
  ]
}
שדות
values[]

value (Value format)

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

תמונה

ייצוג ב-JSON 
{
  "mimeType": string,
  "data": string,
  "altText": string
}
שדות
mimeType

string

חובה. סוג ה-MIME של נתוני המקור לפי תקן IANA. סוגי התמונות הנתמכים כוללים: * image/png * image/jpeg * image/webp
data

string (bytes format)

חובה. בייטים גולמיים של התמונה.

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

string

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

ToolCall

ייצוג ב-JSON 
{
  "id": string,
  "displayName": string,
  "args": {
    object
  },
  "parentToolCallId": string,
  "agentName": string,
  "targetApp": string,

  // Union field tool_identifier can be only one of the following:
  "tool": string,
  "toolsetTool": {
    object (ToolsetTool)
  }
  // End of list of possible types for union field tool_identifier.
}
שדות
id

string

זה שינוי אופציונלי. המזהה הייחודי של קריאת ה-API לכלי. אם השדה מאוכלס, הלקוח צריך להחזיר את תוצאת ההפעלה עם המזהה התואם ב-ToolResponse.
displayName

string

פלט בלבד. השם המוצג של הכלי.
args

object (Struct format)

זה שינוי אופציונלי. הפרמטרים והערכים של הקלט לכלי בפורמט של אובייקט JSON.
parentToolCallId

string

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

string

פלט בלבד. השם של הנציג שביצע את השיחה, בפורמט שקריא לבני אדם, למשל "אדריכל קבלן". השדה ריק כשהסוכן ברמה הבסיסית (root) הנפיק אותו.
targetApp

string

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

string

זה שינוי אופציונלי. שם הכלי שרוצים להפעיל. פורמט: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

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

ToolsetTool

ייצוג ב-JSON 
{
  "toolset": string,
  "toolId": string
}
שדות
toolset

string

חובה. שם המשאב של ערכת הכלים שממנה נגזר הכלי הזה. פורמט: projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolId

string

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

ToolResponse

ייצוג ב-JSON 
{
  "id": string,
  "displayName": string,
  "response": {
    object
  },
  "parentToolCallId": string,
  "agentName": string,
  "targetApp": string,

  // Union field tool_identifier can be only one of the following:
  "tool": string,
  "toolsetTool": {
    object (ToolsetTool)
  }
  // End of list of possible types for union field tool_identifier.
}
שדות
id

string

זה שינוי אופציונלי. המזהה התואם של tool call שהתשובה מתייחסת אליו.
displayName

string

פלט בלבד. השם המוצג של הכלי.
response

object (Struct format)

חובה. תוצאת ההפעלה של הכלי בפורמט של אובייקט JSON. צריך להשתמש במפתח output כדי לציין את התגובה של הכלי, ובמפתח error כדי לציין את פרטי השגיאה (אם יש). אם המפתחות "output" ו-"error" לא צוינו, כל ה-"response" נחשב לתוצאת ההפעלה של הכלי.
parentToolCallId

string

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

string

פלט בלבד. השם של הנציג שביצע את השיחה, בפורמט שקריא לבני אדם, למשל "אדריכל קבלן". השדה ריק כשהסוכן ברמה הבסיסית (root) הנפיק אותו.
targetApp

string

פלט בלבד. האפליקציה שהכלי שהופעל טירגט; משקפת את ToolCall.target_app.
שדה של איחוד tool_identifier. המזהה של הכלי שהופעל. הוא יכול להיות כלי קבוע או כלי מתוך ערכת כלים. הערך tool_identifier יכול להיות רק אחד מהבאים:
tool

string

זה שינוי אופציונלי. שם הכלי שרוצים להפעיל. פורמט: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
toolsetTool

object (ToolsetTool)

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

AgentTransfer

ייצוג ב-JSON 
{
  "targetAgent": string,
  "displayName": string
}
שדות
targetAgent

string

חובה. הנציג שאליו מועברת השיחה. הנציג יטפל בשיחה מכאן והלאה. פורמט: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

פלט בלבד. השם המוצג של הנציג.

Span

ייצוג ב-JSON 
{
  "name": string,
  "startTime": string,
  "endTime": string,
  "duration": string,
  "attributes": {
    object
  },
  "childSpans": [
    {
      object (Span)
    }
  ]
}
שדות
name

string

פלט בלבד. שם ה-span.
startTime

string (Timestamp format)

פלט בלבד. שעת ההתחלה של הטווח.

הפורמט הוא 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".
endTime

string (Timestamp format)

פלט בלבד. שעת הסיום של הטווח.

הפורמט הוא 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".
duration

string (Duration format)

פלט בלבד. משך הזמן של הטווח.

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה העשרונית, שמסתיים ב-s. לדוגמה: "3.5s".
attributes

object (Struct format)

פלט בלבד. מאפייני מפתח/ערך שמשויכים ל-span.
childSpans[]

object (Span)

פלט בלבד. ה-spans המשניים שמוטמעים ב-span הזה.

משך

ייצוג ב-JSON 
{
  "seconds": string,
  "nanos": integer
}
שדות
seconds

string (int64 format)

שניות חתומות של משך הזמן. הערך חייב להיות בין ‎-315,576,000,000 ל-‎+315,576,000,000, כולל. הערה: הגבולות האלה מחושבים לפי: 60 שניות/דקה * 60 דקות/שעה * 24 שעות/יום * 365.25 ימים/שנה * 10,000 שנים
nanos

integer

שברים חתומים של שנייה ברזולוציה של ננו-שנייה של משך הזמן. משכי זמן של פחות משנייה מיוצגים על ידי שדה seconds עם הערך 0 ושדה nanos עם ערך חיובי או שלילי. במשכי זמן של שנייה אחת או יותר, ערך שאינו אפס בשדה nanos חייב להיות עם אותו סימן כמו השדה seconds. הערך חייב להיות בין ‎-999,999,999 ל- ‎+999,999,999, כולל.

NullValue

מייצג null ב-JSON.

‫NullValue הוא sentinel, שמשתמש ב-enum עם ערך אחד בלבד כדי לייצג את הערך null לאיחוד מסוג Value.

שדה מסוג NullValue עם ערך שונה מ-0 נחשב לא תקין. רוב ה-serializers של ProtoJSON יפיקו Value עם null_value שמוגדר כ-null של JSON, בלי קשר לערך של המספר השלם, ולכן יבצעו סבב מלא לערך 0.

טיפוסים בני מנייה (enum)
NULL_VALUE ערך Null.

ChannelType

סוג הערוץ של השיחה.

טיפוסים בני מנייה (enum)
CHANNEL_TYPE_UNSPECIFIED סוג הערוץ לא צוין.
TEXT השיחה מכילה רק הודעות SMS בין משתמש הקצה לבין הנציג.
AUDIO השיחה מכילה הודעות קוליות בין משתמש הקצה לנציג.
MULTIMODAL ההודעות המולטי-מודאליות (למשל, תמונה) בשיחה בין משתמש הקצה לבין הנציג.

מקור

מקור השיחה.

טיפוסים בני מנייה (enum)
SOURCE_UNSPECIFIED מקור לא מוגדר.
LIVE השיחה היא ממשתמש קצה פעיל.
SIMULATOR השיחה היא מהסימולטור.
EVAL השיחה היא מההערכה.
AGENT_TOOL השיחה היא מכלי של סוכן. הכלי Agent מריץ את הנציג בסשן נפרד, שנשמר למטרות בדיקה וניפוי באגים.

InputType

סוג הודעת הקלט.

טיפוסים בני מנייה (enum)
INPUT_TYPE_UNSPECIFIED סוג הקלט לא צוין.
INPUT_TYPE_TEXT קלט טקסט.
INPUT_TYPE_EVENT קלט של אירוע.
INPUT_TYPE_AUDIO קלט אודיו.
INPUT_TYPE_IMAGE קלט תמונה.
INPUT_TYPE_BLOB קלט של Blob.
INPUT_TYPE_TOOL_RESPONSE קלט של תשובה מכלי פונקציה של הלקוח.
INPUT_TYPE_VARIABLES קלט של משתנים.

הערות לגבי הכלים

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

בנוסף למחרוזת הכותרת, הרמזים הבוליאניים הבאים מוגדרים כך:

  • ‫readOnlyHint: אם הערך הוא True, הכלי לא משנה את הסביבה שלו. ברירת המחדל: false.
  • ‫destructiveHint: אם הערך הוא True, הכלי יכול לבצע פעולות הרסניות. אם הערך הוא False, הכלי יכול לבצע רק פעולות הוספה. ברירת המחדל: true.
  • ‫idempotentHint: אם הערך הוא True, קריאה חוזרת לכלי עם אותם ארגומנטים לא תשפיע על הסביבה שלו. ברירת המחדל: false.
  • ‫openWorldHint: אם הערך הוא True, הכלי יכול לקיים אינטראקציה עם "עולם פתוח" של ישויות חיצוניות. אם הערך הוא false, הכלי יכול לקיים אינטראקציה רק עם ישויות פנימיות. לדוגמה, כלי חיפוש באינטרנט הוא כלי בעולם פתוח, אבל כלי זיכרון הוא לא כלי בעולם פתוח.

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌