Method: projects.locations.apps.executeTool

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

בקשת HTTP

POST https://ces.googleapis.com/v1/{parent=projects/*/locations/*/apps/*}:executeTool

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

פרמטרים של נתיב

פרמטרים
parent

string

חובה. שם המשאב של האפליקציה שאליה שייך הכלי או ערכת הכלים. פורמט: projects/{project}/locations/{location}/apps/{app}

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "args": {
    object
  },
  "mockConfig": {
    object (MockConfig)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "tool": string,
  "toolsetTool": {
    object (ToolsetTool)
  }
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "variables": {
    object
  },
  "context": {
    object
  }
  // End of mutually exclusive fields.
}
שדות
args

object (Struct format)

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

object (MockConfig)

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

string

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

object (ToolsetTool)

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

object (Struct format)

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

object (Struct format)

זה שינוי אופציונלי. [ToolCallContext](https://docs.cloud.google.com/customer-engagement-ai/conversational-agents/ps/tool/python#environment לפרטים) שיועבר לכלי Python.
סוף השדות הבלעדיים.

גוף התשובה

הודעת תגובה ל-ToolService.ExecuteTool.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "response": {
    object
  },
  "variables": {
    object
  },
  "citations": {
    object (Citations)
  },
  "googleSearchSuggestions": {
    object (GoogleSearchSuggestions)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "tool": string,
  "toolsetTool": {
    object (ToolsetTool)
  }
  // End of mutually exclusive fields.
}
שדות
response

object (Struct format)

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

object (Struct format)

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

object (Citations)

ציטוטים שמספקים את פרטי המקור של הפעלת הכלי.
googleSearchSuggestions

object (GoogleSearchSuggestions)

ההצעות שמוחזרות מחיפוש Google כתוצאה מהפעלת הכלי 'חיפוש Google' במהלך ההרצה של הכלי.
המזהה של הכלי שהופעל. הרשימה הבאה כוללת שדות שאי אפשר להשתמש בהם בו-זמנית. בכל תשובה יוגדר לכל היותר אחד מהשדות:
tool

string

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

object (ToolsetTool)

הכלי בערכת הכלים שהופעל.
סוף השדות הבלעדיים.

היקפי הרשאות

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

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

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

הרשאות IAM

נדרשת הרשאת IAM הבאה במשאב parent:

  • ces.tools.execute

מידע נוסף מופיע במאמרי העזרה בנושא IAM.

MockConfig

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

ייצוג ב-JSON 
{
  "mockedToolCalls": [
    {
      object (MockedToolCall)
    }
  ],
  "unmatchedToolCallBehavior": enum (MockConfig.UnmatchedToolCallBehavior)
}
שדות
mockedToolCalls[]

object (MockedToolCall)

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

enum (MockConfig.UnmatchedToolCallBehavior)

חובה. התנהגות של קריאות לכלים שלא תואמות לאף תבנית של ארגומנטים ב-mockedToolCalls.

MockedToolCall

קריאה לכלי בהדמיה.

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

ייצוג ב-JSON 
{
  "tool": string,
  "expectedArgsPattern": {
    object
  },
  "mockResponse": {
    object
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "toolId": string,
  "toolset": {
    object (ToolsetTool)
  }
  // End of mutually exclusive fields.
}
שדות
tool
(deprecated)

string

זה שינוי אופציונלי. הוצאה משימוש, במקום זאת, צריך להשתמש ב-tool_identifier.
expectedArgsPattern

object (Struct format)

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

object (Struct format)

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

string

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

object (ToolsetTool)

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

MockConfig.UnmatchedToolCallBehavior

מה עושים כשקריאה לכלי לא תואמת לקריאות לכלי שנוצרו כדוגמה.

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