MCP Tools Reference: ces.googleapis.com

כלי: update_guardrail

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

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

בקשת 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": "update_guardrail",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

סכימת הקלט

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

UpdateGuardrailRequest

ייצוג ב-JSON 
{
  "guardrail": {
    object (Guardrail)
  },
  "updateMask": string
}
שדות
guardrail

object (Guardrail)

חובה. ההנחיה שרוצים לעדכן.
updateMask

string (FieldMask format)

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

זוהי רשימה מופרדת בפסיקים של שמות שדות שמוגדרים במלואם. דוגמה: "user.displayName,photo"

שכבת הגנה

ייצוג ב-JSON 
{
  "name": string,
  "displayName": string,
  "description": string,
  "enabled": boolean,
  "action": {
    object (TriggerAction)
  },
  "createTime": string,
  "updateTime": string,
  "etag": string,

  // Union field guardrail_type can be only one of the following:
  "contentFilter": {
    object (ContentFilter)
  },
  "llmPromptSecurity": {
    object (LlmPromptSecurity)
  },
  "llmPolicy": {
    object (LlmPolicy)
  },
  "modelSafety": {
    object (ModelSafety)
  },
  "codeCallback": {
    object (CodeCallback)
  },
  "supervisor": {
    object (Supervisor)
  }
  // End of list of possible types for union field guardrail_type.
}
שדות
name

string

מזהה. המזהה הייחודי של מעקה הבטיחות. פורמט: projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}
displayName

string

חובה. השם המוצג של מעקה הבטיחות.
description

string

זה שינוי אופציונלי. תיאור של ההנחיה.
enabled

boolean

זה שינוי אופציונלי. אם אמצעי ההגנה מופעל.
action

object (TriggerAction)

זה שינוי אופציונלי. הפעולה שצריך לבצע כשהמעקה מופעל.
createTime

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".
updateTime

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".
etag

string

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

object (ContentFilter)

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

object (LlmPromptSecurity)

זה שינוי אופציונלי. אמצעי הגנה שחוסם את השיחה אם ההנחיה נחשבת לא בטוחה על סמך הסיווג של ה-LLM.
llmPolicy

object (LlmPolicy)

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

object (ModelSafety)

זה שינוי אופציונלי. אמצעי הגנה שחוסם את השיחה אם התשובה של ה-LLM נחשבת לא בטוחה, בהתאם להגדרות הבטיחות של המודל.
codeCallback

object (CodeCallback)

זה שינוי אופציונלי. הנחיה שעשויה לחסום את השיחה על סמך התוצאה של הפעלת ה-callback.
supervisor

object (Supervisor)

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

ContentFilter

ייצוג ב-JSON 
{
  "bannedContents": [
    string
  ],
  "bannedContentsInUserInput": [
    string
  ],
  "bannedContentsInAgentResponse": [
    string
  ],
  "matchType": enum (MatchType),
  "disregardDiacritics": boolean,
  "sensitiveWordsExemptions": [
    string
  ]
}
שדות
bannedContents[]

string

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

string

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

string

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

enum (MatchType)

חובה. סוג ההתאמה של מסנן התוכן.
disregardDiacritics

boolean

זה שינוי אופציונלי. אם הערך הוא True, המערכת מתעלמת מסימנים דיאקריטיים במהלך ההתאמה.
sensitiveWordsExemptions[]

string

זה שינוי אופציונלי. רשומות ברשימת המילים הרגישות שההגנה הזו מאפשרת. רלוונטי רק אם הערך של match_type הוא SENSITIVE_WORDS. כל ערך חייב להיות זהה לרשומה ברשימה (לא תלוי-רישיות, המערכת מתעלמת מרווחים לבנים מסביב). ערכים אחרים לא משפיעים. ההגדרה חלה רק על ההגנה הזו. עד 1,000 רשומות, כל אחת באורך של עד 256 תווים.

LlmPromptSecurity

ייצוג ב-JSON 
{
  "failOpen": boolean,

  // Union field security_config can be only one of the following:
  "defaultSettings": {
    object (DefaultSecuritySettings)
  },
  "customPolicy": {
    object (LlmPolicy)
  }
  // End of list of possible types for union field security_config.
}
שדות
failOpen

boolean

זה שינוי אופציונלי. ההגדרה הזו קובעת מה קורה כשיש שגיאה במודל ה-LLM. - אם הערך הוא True: המערכת עוקפת את מנגנון ההגנה. - אם הערך הוא False (ברירת המחדל): מעקה הבטיחות מופעל או חוסם.

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

object (DefaultSecuritySettings)

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

object (LlmPolicy)

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

DefaultSecuritySettings

ייצוג ב-JSON 
{
  "defaultPromptTemplate": string
}
שדות
defaultPromptTemplate

string

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

LlmPolicy

ייצוג ב-JSON 
{
  "maxConversationMessages": integer,
  "modelSettings": {
    object (ModelSettings)
  },
  "prompt": string,
  "policyScope": enum (PolicyScope),
  "failOpen": boolean,
  "allowShortUtterance": boolean
}
שדות
maxConversationMessages

integer

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

object (ModelSettings)

זה שינוי אופציונלי. הגדרות המודל.
prompt

string

חובה. הנחיה לגבי המדיניות. תומך בפלייסהולדרים של משתני סשן ({var}) וגם ב-{agent_system_instruction} כדי להוסיף את הוראות המערכת שהנציג פתר.
policyScope

enum (PolicyScope)

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

boolean

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

boolean

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

ModelSettings

ייצוג ב-JSON 
{
  "model": string,
  "thinkingLevel": enum (ThinkingLevel),

  // Union field _temperature can be only one of the following:
  "temperature": number
  // End of list of possible types for union field _temperature.
}
שדות
model

string

זה שינוי אופציונלי. מודל ה-LLM שהסוכן צריך להשתמש בו. אם לא מגדירים מודל, הסוכן יורש את המודל מהסוכן הראשי שלו.
thinkingLevel

enum (ThinkingLevel)

זה שינוי אופציונלי. רמת ההעמקה של המודל.

שדה של איחוד _temperature.

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

number

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

ModelSafety

ייצוג ב-JSON 
{
  "safetySettings": [
    {
      object (SafetySetting)
    }
  ]
}
שדות
safetySettings[]

object (SafetySetting)

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

SafetySetting

ייצוג ב-JSON 
{
  "category": enum (HarmCategory),
  "threshold": enum (HarmBlockThreshold)
}
שדות
category

enum (HarmCategory)

חובה. קטגוריית הפגיעה.
threshold

enum (HarmBlockThreshold)

חובה. סף החסימה של תוכן פוגעני.

CodeCallback

ייצוג ב-JSON 
{
  "beforeAgentCallback": {
    object (Callback)
  },
  "afterAgentCallback": {
    object (Callback)
  },
  "beforeModelCallback": {
    object (Callback)
  },
  "afterModelCallback": {
    object (Callback)
  }
}
שדות
beforeAgentCallback

object (Callback)

זה שינוי אופציונלי. הקריאה החוזרת (callback) שצריך להפעיל לפני שקוראים לסוכן. כל פונקציית קריאה חוזרת צריכה להחזיר מבנה (למשל, dict או אובייקט) שמכיל לפחות: - 'decision': ‏ 'OK' או 'TRIGGER'. ‫- "reason": מחרוזת שמסבירה את ההחלטה. החלטה מסוג TRIGGER עשויה לעצור את המשך העיבוד.
afterAgentCallback

object (Callback)

זה שינוי אופציונלי. הקריאה החוזרת (callback) שתבוצע אחרי שהסוכן יופעל. כל פונקציית קריאה חוזרת צריכה להחזיר מבנה (למשל, dict או אובייקט) שמכיל לפחות: - 'decision': ‏ 'OK' או 'TRIGGER'. ‫- "reason": מחרוזת שמסבירה את ההחלטה. החלטה מסוג TRIGGER עשויה לעצור את המשך העיבוד.
beforeModelCallback

object (Callback)

זה שינוי אופציונלי. הקריאה החוזרת (callback) שצריך להפעיל לפני הקריאה למודל. אם יש כמה קריאות למודל, פונקציית ה-callback תופעל כמה פעמים. כל פונקציית קריאה חוזרת צריכה להחזיר מבנה (למשל, dict או אובייקט) שמכיל לפחות: - 'decision': ‏ 'OK' או 'TRIGGER'. ‫- "reason": מחרוזת שמסבירה את ההחלטה. החלטה מסוג TRIGGER עשויה לעצור את המשך העיבוד.
afterModelCallback

object (Callback)

זה שינוי אופציונלי. הקריאה החוזרת (callback) שצריך להפעיל אחרי שהמודל נקרא. אם יש כמה קריאות למודל, פונקציית ה-callback תופעל כמה פעמים. כל פונקציית קריאה חוזרת צריכה להחזיר מבנה (למשל, dict או אובייקט) שמכיל לפחות: - 'decision': ‏ 'OK' או 'TRIGGER'. ‫- "reason": מחרוזת שמסבירה את ההחלטה. החלטה מסוג TRIGGER עשויה לעצור את המשך העיבוד.

התקשרות חזרה

ייצוג ב-JSON 
{
  "description": string,
  "disabled": boolean,
  "proactiveExecutionEnabled": boolean,

  // Union field callback can be only one of the following:
  "pythonCode": string
  // End of list of possible types for union field callback.
}
שדות
description

string

זה שינוי אופציונלי. תיאור קריא לאנשים של הקריאה החוזרת.
disabled

boolean

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

boolean

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

string

חובה. קוד ה-Python שצריך להריץ בשביל הקריאה החוזרת (callback).

מפקח/ת

ייצוג ב-JSON 
{
  "type": enum (Type),
  "detectionMode": enum (DetectionMode)
}
שדות
type

enum (Type)

זה שינוי אופציונלי. סוג המפקח.
detectionMode

enum (DetectionMode)

זה שינוי אופציונלי. מצב הזיהוי של המפקח.

TriggerAction

ייצוג ב-JSON 
{

  // Union field action can be only one of the following:
  "respondImmediately": {
    object (RespondImmediately)
  },
  "transferAgent": {
    object (TransferAgent)
  },
  "generativeAnswer": {
    object (GenerativeAnswer)
  }
  // End of list of possible types for union field action.
}
שדות
שדה של איחוד action. הפעולה שצריך לבצע. הערך action יכול להיות רק אחד מהבאים:
respondImmediately

object (RespondImmediately)

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

object (TransferAgent)

זה שינוי אופציונלי. להעביר את השיחה לנציג אחר.
generativeAnswer

object (GenerativeAnswer)

זה שינוי אופציונלי. להשיב באמצעות תשובה שנוצרה על ידי AI.

RespondImmediately

ייצוג ב-JSON 
{
  "responses": [
    {
      object (Response)
    }
  ]
}
שדות
responses[]

object (Response)

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

תשובה

ייצוג ב-JSON 
{
  "text": string,
  "disabled": boolean
}
שדות
text

string

חובה. הטקסט שהסוכן ישתמש בו כדי להשיב.
disabled

boolean

זה שינוי אופציונלי. אם התשובה מושבתת. הנציג לא משתמש בתשובות מושבתות.

TransferAgent

ייצוג ב-JSON 
{
  "agent": string
}
שדות
agent

string

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

GenerativeAnswer

ייצוג ב-JSON 
{
  "prompt": string
}
שדות
prompt

string

חובה. ההנחיה שמשמשת ליצירת התשובה.

חותמת הזמן

ייצוג ב-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, כולל.

FieldMask

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

string

קבוצת הנתיבים של מסכת השדות.

MatchType

סוג ההתאמה של מסנן התוכן.

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

ThinkingLevel

הגדרת רמת ההעמקה של המודל.

טיפוסים בני מנייה (enum)
THINKING_LEVEL_UNSPECIFIED רמת ההעמקה לא צוינה.
DEFAULT רמת ההעמקה שמוגדרת כברירת מחדל.
LOW רמת העמקה נמוכה.
MEDIUM רמת העמקה בינונית.
HIGH רמת העמקה גבוהה.

PolicyScope

מגדיר מתי להחיל את בדיקת המדיניות במהלך השיחה.

טיפוסים בני מנייה (enum)
POLICY_SCOPE_UNSPECIFIED היקף המדיניות לא צוין.
USER_QUERY בדיקת המדיניות מופעלת על קלט של משתמשים.
AGENT_RESPONSE בדיקת המדיניות מופעלת בתגובה של הנציג. החלת היקף המדיניות הזה תגרום לזמן אחזור נוסף לפני שהנציג יוכל להגיב.
USER_QUERY_AND_AGENT_RESPONSE בדיקת המדיניות מופעלת גם על הקלט של המשתמש וגם על התשובה של הנציג. החלת היקף המדיניות הזה תגרום לזמן אחזור נוסף לפני שהנציג יוכל להגיב.

HarmCategory

קטגוריית הנזק.

טיפוסים בני מנייה (enum)
HARM_CATEGORY_UNSPECIFIED קטגוריית הפגיעה לא צוינה.
HARM_CATEGORY_HATE_SPEECH קטגוריית הנזק היא דברי שטנה.
HARM_CATEGORY_DANGEROUS_CONTENT קטגוריית הנזק היא תוכן מסוכן.
HARM_CATEGORY_HARASSMENT קטגוריית הפגיעה היא הטרדה.
HARM_CATEGORY_SEXUALLY_EXPLICIT קטגוריית הפגיעה היא תוכן מיני בוטה.
HARM_CATEGORY_PROFANITY קטגוריית הפגיעה היא שפה גסה.
HARM_CATEGORY_TOXIC קטגוריית הפגיעה היא רעילות.

HarmBlockThreshold

רמות סף מבוססות-הסתברות לחסימה.

טיפוסים בני מנייה (enum)
HARM_BLOCK_THRESHOLD_UNSPECIFIED סף חסימה לא מוגדר של נזק.
BLOCK_LOW_AND_ABOVE חסימת סף נמוך ומעלה (כלומר, חסימה של יותר תוכן).
BLOCK_MEDIUM_AND_ABOVE חסימה של סף בינוני ומעלה.
BLOCK_ONLY_HIGH לחסום רק סף גבוה (כלומר, לחסום פחות).
BLOCK_NONE לא לחסום אף אחד.
OFF משביתים את מסנן הבטיחות.

סוג

סוג המפקח.

טיפוסים בני מנייה (enum)
TYPE_UNSPECIFIED לא צוין סוג.
INVALID_TEXT סוג הבעיה בטקסט לא תקין.
LANGUAGE_SHIFT סוג הבעיה: שינוי שפה.
SPEAKER_SHIFT סוג הבעיה: שינוי הדובר.
AUDIO_MISMATCH סוג הבעיה: חוסר התאמה באודיו.
MISSING_TOOL_CALL לא צוין סוג הבעיה בקריאת ה-API לכלי.
CUSTOM סוג בעיה מותאם אישית.
CHOPPY_AUDIO סוג הבעיה: אודיו קטוע.
PROFANITY סוג הבעיה: שפה גסה של הנציג.

DetectionMode

מצב הזיהוי של המפקח.

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

סכימת הפלט

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

שכבת הגנה

ייצוג ב-JSON 
{
  "name": string,
  "displayName": string,
  "description": string,
  "enabled": boolean,
  "action": {
    object (TriggerAction)
  },
  "createTime": string,
  "updateTime": string,
  "etag": string,

  // Union field guardrail_type can be only one of the following:
  "contentFilter": {
    object (ContentFilter)
  },
  "llmPromptSecurity": {
    object (LlmPromptSecurity)
  },
  "llmPolicy": {
    object (LlmPolicy)
  },
  "modelSafety": {
    object (ModelSafety)
  },
  "codeCallback": {
    object (CodeCallback)
  },
  "supervisor": {
    object (Supervisor)
  }
  // End of list of possible types for union field guardrail_type.
}
שדות
name

string

מזהה. המזהה הייחודי של מעקה הבטיחות. פורמט: projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}
displayName

string

חובה. השם המוצג של מעקה הבטיחות.
description

string

זה שינוי אופציונלי. תיאור של ההנחיה.
enabled

boolean

זה שינוי אופציונלי. אם אמצעי ההגנה מופעל.
action

object (TriggerAction)

זה שינוי אופציונלי. הפעולה שצריך לבצע כשהמעקה מופעל.
createTime

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".
updateTime

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".
etag

string

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

object (ContentFilter)

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

object (LlmPromptSecurity)

זה שינוי אופציונלי. אמצעי הגנה שחוסם את השיחה אם ההנחיה נחשבת לא בטוחה על סמך הסיווג של ה-LLM.
llmPolicy

object (LlmPolicy)

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

object (ModelSafety)

זה שינוי אופציונלי. אמצעי הגנה שחוסם את השיחה אם התשובה של ה-LLM נחשבת לא בטוחה, בהתאם להגדרות הבטיחות של המודל.
codeCallback

object (CodeCallback)

זה שינוי אופציונלי. הנחיה שעשויה לחסום את השיחה על סמך התוצאה של הפעלת ה-callback.
supervisor

object (Supervisor)

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

ContentFilter

ייצוג ב-JSON 
{
  "bannedContents": [
    string
  ],
  "bannedContentsInUserInput": [
    string
  ],
  "bannedContentsInAgentResponse": [
    string
  ],
  "matchType": enum (MatchType),
  "disregardDiacritics": boolean,
  "sensitiveWordsExemptions": [
    string
  ]
}
שדות
bannedContents[]

string

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

string

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

string

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

enum (MatchType)

חובה. סוג ההתאמה של מסנן התוכן.
disregardDiacritics

boolean

זה שינוי אופציונלי. אם הערך הוא True, המערכת מתעלמת מסימנים דיאקריטיים במהלך ההתאמה.
sensitiveWordsExemptions[]

string

זה שינוי אופציונלי. רשומות ברשימת המילים הרגישות שההגנה הזו מאפשרת. רלוונטי רק אם הערך של match_type הוא SENSITIVE_WORDS. כל ערך חייב להיות זהה לרשומה ברשימה (לא תלוי-רישיות, המערכת מתעלמת מרווחים לבנים מסביב). ערכים אחרים לא משפיעים. ההגדרה חלה רק על ההגנה הזו. עד 1,000 רשומות, כל אחת באורך של עד 256 תווים.

LlmPromptSecurity

ייצוג ב-JSON 
{
  "failOpen": boolean,

  // Union field security_config can be only one of the following:
  "defaultSettings": {
    object (DefaultSecuritySettings)
  },
  "customPolicy": {
    object (LlmPolicy)
  }
  // End of list of possible types for union field security_config.
}
שדות
failOpen

boolean

זה שינוי אופציונלי. ההגדרה הזו קובעת מה קורה כשיש שגיאה במודל ה-LLM. - אם הערך הוא True: המערכת עוקפת את מנגנון ההגנה. - אם הערך הוא False (ברירת המחדל): מעקה הבטיחות מופעל או חוסם.

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

object (DefaultSecuritySettings)

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

object (LlmPolicy)

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

DefaultSecuritySettings

ייצוג ב-JSON 
{
  "defaultPromptTemplate": string
}
שדות
defaultPromptTemplate

string

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

LlmPolicy

ייצוג ב-JSON 
{
  "maxConversationMessages": integer,
  "modelSettings": {
    object (ModelSettings)
  },
  "prompt": string,
  "policyScope": enum (PolicyScope),
  "failOpen": boolean,
  "allowShortUtterance": boolean
}
שדות
maxConversationMessages

integer

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

object (ModelSettings)

זה שינוי אופציונלי. הגדרות המודל.
prompt

string

חובה. הנחיה לגבי המדיניות. תומך בפלייסהולדרים של משתני סשן ({var}) וגם ב-{agent_system_instruction} כדי להוסיף את הוראות המערכת שהנציג פתר.
policyScope

enum (PolicyScope)

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

boolean

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

boolean

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

ModelSettings

ייצוג ב-JSON 
{
  "model": string,
  "thinkingLevel": enum (ThinkingLevel),

  // Union field _temperature can be only one of the following:
  "temperature": number
  // End of list of possible types for union field _temperature.
}
שדות
model

string

זה שינוי אופציונלי. מודל ה-LLM שהסוכן צריך להשתמש בו. אם לא מגדירים מודל, הסוכן יורש את המודל מהסוכן הראשי שלו.
thinkingLevel

enum (ThinkingLevel)

זה שינוי אופציונלי. רמת ההעמקה של המודל.

שדה של איחוד _temperature.

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

number

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

ModelSafety

ייצוג ב-JSON 
{
  "safetySettings": [
    {
      object (SafetySetting)
    }
  ]
}
שדות
safetySettings[]

object (SafetySetting)

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

SafetySetting

ייצוג ב-JSON 
{
  "category": enum (HarmCategory),
  "threshold": enum (HarmBlockThreshold)
}
שדות
category

enum (HarmCategory)

חובה. קטגוריית הפגיעה.
threshold

enum (HarmBlockThreshold)

חובה. סף החסימה של תוכן פוגעני.

CodeCallback

ייצוג ב-JSON 
{
  "beforeAgentCallback": {
    object (Callback)
  },
  "afterAgentCallback": {
    object (Callback)
  },
  "beforeModelCallback": {
    object (Callback)
  },
  "afterModelCallback": {
    object (Callback)
  }
}
שדות
beforeAgentCallback

object (Callback)

זה שינוי אופציונלי. הקריאה החוזרת (callback) שצריך להפעיל לפני שקוראים לסוכן. כל פונקציית קריאה חוזרת צריכה להחזיר מבנה (למשל, dict או אובייקט) שמכיל לפחות: - 'decision': ‏ 'OK' או 'TRIGGER'. ‫- "reason": מחרוזת שמסבירה את ההחלטה. החלטה מסוג TRIGGER עשויה לעצור את המשך העיבוד.
afterAgentCallback

object (Callback)

זה שינוי אופציונלי. הקריאה החוזרת (callback) שתבוצע אחרי שהסוכן יופעל. כל פונקציית קריאה חוזרת צריכה להחזיר מבנה (למשל, dict או אובייקט) שמכיל לפחות: - 'decision': ‏ 'OK' או 'TRIGGER'. ‫- "reason": מחרוזת שמסבירה את ההחלטה. החלטה מסוג TRIGGER עשויה לעצור את המשך העיבוד.
beforeModelCallback

object (Callback)

זה שינוי אופציונלי. הקריאה החוזרת (callback) שצריך להפעיל לפני הקריאה למודל. אם יש כמה קריאות למודל, פונקציית ה-callback תופעל כמה פעמים. כל פונקציית קריאה חוזרת צריכה להחזיר מבנה (למשל, dict או אובייקט) שמכיל לפחות: - 'decision': ‏ 'OK' או 'TRIGGER'. ‫- "reason": מחרוזת שמסבירה את ההחלטה. החלטה מסוג TRIGGER עשויה לעצור את המשך העיבוד.
afterModelCallback

object (Callback)

זה שינוי אופציונלי. הקריאה החוזרת (callback) שצריך להפעיל אחרי שהמודל נקרא. אם יש כמה קריאות למודל, פונקציית ה-callback תופעל כמה פעמים. כל פונקציית קריאה חוזרת צריכה להחזיר מבנה (למשל, dict או אובייקט) שמכיל לפחות: - 'decision': ‏ 'OK' או 'TRIGGER'. ‫- "reason": מחרוזת שמסבירה את ההחלטה. החלטה מסוג TRIGGER עשויה לעצור את המשך העיבוד.

התקשרות חזרה

ייצוג ב-JSON 
{
  "description": string,
  "disabled": boolean,
  "proactiveExecutionEnabled": boolean,

  // Union field callback can be only one of the following:
  "pythonCode": string
  // End of list of possible types for union field callback.
}
שדות
description

string

זה שינוי אופציונלי. תיאור קריא לאנשים של הקריאה החוזרת.
disabled

boolean

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

boolean

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

string

חובה. קוד ה-Python שצריך להריץ בשביל הקריאה החוזרת (callback).

מפקח/ת

ייצוג ב-JSON 
{
  "type": enum (Type),
  "detectionMode": enum (DetectionMode)
}
שדות
type

enum (Type)

זה שינוי אופציונלי. סוג המפקח.
detectionMode

enum (DetectionMode)

זה שינוי אופציונלי. מצב הזיהוי של המפקח.

TriggerAction

ייצוג ב-JSON 
{

  // Union field action can be only one of the following:
  "respondImmediately": {
    object (RespondImmediately)
  },
  "transferAgent": {
    object (TransferAgent)
  },
  "generativeAnswer": {
    object (GenerativeAnswer)
  }
  // End of list of possible types for union field action.
}
שדות
שדה של איחוד action. הפעולה שצריך לבצע. הערך action יכול להיות רק אחד מהבאים:
respondImmediately

object (RespondImmediately)

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

object (TransferAgent)

זה שינוי אופציונלי. להעביר את השיחה לנציג אחר.
generativeAnswer

object (GenerativeAnswer)

זה שינוי אופציונלי. להשיב באמצעות תשובה שנוצרה על ידי AI.

RespondImmediately

ייצוג ב-JSON 
{
  "responses": [
    {
      object (Response)
    }
  ]
}
שדות
responses[]

object (Response)

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

תשובה

ייצוג ב-JSON 
{
  "text": string,
  "disabled": boolean
}
שדות
text

string

חובה. הטקסט שהסוכן ישתמש בו כדי להשיב.
disabled

boolean

זה שינוי אופציונלי. אם התשובה מושבתת. הנציג לא משתמש בתשובות מושבתות.

TransferAgent

ייצוג ב-JSON 
{
  "agent": string
}
שדות
agent

string

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

GenerativeAnswer

ייצוג ב-JSON 
{
  "prompt": string
}
שדות
prompt

string

חובה. ההנחיה שמשמשת ליצירת התשובה.

חותמת הזמן

ייצוג ב-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, כולל.

MatchType

סוג ההתאמה של מסנן התוכן.

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

ThinkingLevel

הגדרת רמת ההעמקה של המודל.

טיפוסים בני מנייה (enum)
THINKING_LEVEL_UNSPECIFIED רמת ההעמקה לא צוינה.
DEFAULT רמת ההעמקה שמוגדרת כברירת מחדל.
LOW רמת העמקה נמוכה.
MEDIUM רמת העמקה בינונית.
HIGH רמת העמקה גבוהה.

PolicyScope

מגדיר מתי להחיל את בדיקת המדיניות במהלך השיחה.

טיפוסים בני מנייה (enum)
POLICY_SCOPE_UNSPECIFIED היקף המדיניות לא צוין.
USER_QUERY בדיקת המדיניות מופעלת על קלט של משתמשים.
AGENT_RESPONSE בדיקת המדיניות מופעלת בתגובה של הנציג. החלת היקף המדיניות הזה תגרום לזמן אחזור נוסף לפני שהנציג יוכל להגיב.
USER_QUERY_AND_AGENT_RESPONSE בדיקת המדיניות מופעלת גם על הקלט של המשתמש וגם על התשובה של הנציג. החלת היקף המדיניות הזה תגרום לזמן אחזור נוסף לפני שהנציג יוכל להגיב.

HarmCategory

קטגוריית הנזק.

טיפוסים בני מנייה (enum)
HARM_CATEGORY_UNSPECIFIED קטגוריית הפגיעה לא צוינה.
HARM_CATEGORY_HATE_SPEECH קטגוריית הנזק היא דברי שטנה.
HARM_CATEGORY_DANGEROUS_CONTENT קטגוריית הנזק היא תוכן מסוכן.
HARM_CATEGORY_HARASSMENT קטגוריית הפגיעה היא הטרדה.
HARM_CATEGORY_SEXUALLY_EXPLICIT קטגוריית הפגיעה היא תוכן מיני בוטה.
HARM_CATEGORY_PROFANITY קטגוריית הפגיעה היא שפה גסה.
HARM_CATEGORY_TOXIC קטגוריית הפגיעה היא רעילות.

HarmBlockThreshold

רמות סף מבוססות-הסתברות לחסימה.

טיפוסים בני מנייה (enum)
HARM_BLOCK_THRESHOLD_UNSPECIFIED סף חסימה לא מוגדר של נזק.
BLOCK_LOW_AND_ABOVE חסימת סף נמוך ומעלה (כלומר, חסימה של יותר תוכן).
BLOCK_MEDIUM_AND_ABOVE חסימה של סף בינוני ומעלה.
BLOCK_ONLY_HIGH לחסום רק סף גבוה (כלומר, לחסום פחות).
BLOCK_NONE לא לחסום אף אחד.
OFF משביתים את מסנן הבטיחות.

סוג

סוג המפקח.

טיפוסים בני מנייה (enum)
TYPE_UNSPECIFIED לא צוין סוג.
INVALID_TEXT סוג הבעיה בטקסט לא תקין.
LANGUAGE_SHIFT סוג הבעיה: שינוי שפה.
SPEAKER_SHIFT סוג הבעיה: שינוי הדובר.
AUDIO_MISMATCH סוג הבעיה: חוסר התאמה באודיו.
MISSING_TOOL_CALL לא צוין סוג הבעיה בקריאת ה-API לכלי.
CUSTOM סוג בעיה מותאם אישית.
CHOPPY_AUDIO סוג הבעיה: אודיו קטוע.
PROFANITY סוג הבעיה: שפה גסה של הנציג.

DetectionMode

מצב הזיהוי של המפקח.

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

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

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

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

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

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