הפניה לפורמט ייצוא

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

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

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

השמות הבאים של כלים שמורים:

• end_session
• transfer_to_agent
• customize_response

כשמייבאים ומייצאים, אפשר להשתמש ב-JSON או ב-YAML לקבצים בודדים. הקבצים שמתוארים במסמך הזה הם בפורמט YAML, אבל חברי ה-JSON דומים.

תיקיית השורש

תיקיית השורש מכילה את קובצי ההגדרות העיקריים של האפליקציה:

• ‫app.yaml: קובץ ההגדרות המרכזי של אפליקציית הסוכן. היא מגדירה:
  • ‫displayName (מחרוזת): השם של האפליקציה שקריא לבני אדם.
  • rootAgent (string): השם המוצג של הסוכן שהתחיל את השיחה. אל תשתמשו בשם הקובץ או בשם הספרייה.
  • ‫audioProcessingConfig (object): הגדרות להמרת טקסט לדיבור ולהמרת דיבור לטקסט.
    • ‫synthesizeSpeechConfigs (map): המפתחות הם קודי לוקאל (לדוגמה, en-US), הערכים הם אובייקטים שמכילים voice (מחרוזת).
    • ‫inactivityTimeout (string): מחרוזת משך (לדוגמה, ‎"2s"‎).
    • ‫ambientSoundConfig (object): הגדרת רעשי רקע, כולל volumeGainDb (float) ו-prebuiltAmbientSound (string).
  • ‫loggingSettings (object): הגדרות ליומנים ולהקלטה.
    • ‫redactionConfig (object): הגדרות להשמטת מידע רגיש.
    • ‫audioRecordingConfig (object): מכיל gcsBucket (string).
    • ‫bigqueryExportSettings (אובייקט): מכיל enabled (בוליאני), project (מחרוזת), dataset (מחרוזת).
    • ‫cloudLoggingSettings (אובייקט): מכיל enableCloudLogging (בוליאני).
  • ‫guardrails (רשימה של מחרוזות): רשימה של שמות של אמצעי בקרה שמוחלים באופן גלובלי.
  • ‫variableDeclarations (רשימת אובייקטים): הגדרות סכימה למשתנים גלובליים. כל אובייקט מכיל את הפרטים הבאים:
    • name (string): שם המשתנה.
    • description (string): הסבר על מטרת המשתנה.
    • ‫schema (object): הגדרת סוג (לדוגמה, { type: STRING } או מאפיינים מוצבים בתוך רכיב).
    • ‫default (כלשהו): ערך ברירת המחדל של המשתנה.
  • ‫globalInstruction (מחרוזת): הנתיב לקובץ ההוראות הגלובליות למערכת.
  • languageSettings (אובייקט):
    • ‫defaultLanguageCode (string): לדוגמה, 'en-US'.
    • ‫supportedLanguageCodes (list of strings): לדוגמה, ["fr", "es"].
    • enableMultilingualSupport (בוליאני).
• ‫environment.json: צמדי מפתח/ערך למשתנים ספציפיים לסביבה.
• ‫global_instruction.txt: קובץ טקסט שמכיל את ההנחיה או ההוראה העיקרית.

agents/

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

מבנה הנציגים (agents/<agent_name>/)

• ‫<agent_name>.yaml: קובץ ההגדרות של הסוכן הספציפי.
  • ‫displayName (מחרוזת): שם הסוכן.
  • ‫modelSettings (object): מכיל model (string).
  • ‫instruction (מחרוזת): הנתיב לקובץ ההוראות ביחס לספריית הבסיס (לדוגמה, agents/<agent_name>/instruction.txt).
  • ‫tools (רשימת מחרוזות): שמות התצוגה של כלים מקומיים שזמינים לסוכן הזה.
  • ‫toolsets (רשימת אובייקטים): ערכות כלים של OpenAPI שזמינות לסוכן הזה. כל אובייקט מכיל את הפרטים הבאים:
    • ‫toolset (string): השם של ערכת הכלים.
    • ‫toolIds (רשימה של מחרוזות): מזהי פעולות ספציפיים לחשיפה מתוך ערכת הכלים.
  • ‫childAgents (רשימה של מחרוזות): השמות המוצגים של סוכנים אחרים שהסוכן הזה יכול לעבור אליהם. הקשר הזה הוא חד-כיווני (מהורה לצאצא); סוכני צאצא לא צריכים לציין את ההורים שלהם כצאצאים אלא אם מעבר מעגלי מיועד באופן מפורש. לא יכולים להיות יותר מתיקיית אם אחת לסוכנים (יוצאים מן הכלל: סוכנים שיתופיים כמו Escalation או Satisfaction). אי אפשר להגדיר את סוכן הבסיס כסוכן משני של סוכן אחר.
  • ‫*Callbacks (רשימת אובייקטים): משמש ל-beforeModelCallbacks, ל-afterModelCallbacks וכן הלאה. כל אובייקט מכיל את הפרטים הבאים:
    • ‫pythonCode (מחרוזת): הנתיב לסקריפט של הקריאה החוזרת.
    • ‫disabled (boolean): האם הקריאה החוזרת פעילה.
    • ‫description (string): תיאור של הלוגיקה של הקריאה החוזרת.
• ‫instruction.txt: ההנחיה הספציפית למערכת של הסוכן הזה. הפניות לכלים צריכות להיות בתחביר {@TOOL: <tool_display_name>}, הפניות לסוכנים אחרים צריכות להיות בתחביר {@AGENT: <agent_display_name>}, וצריך לגשת למשתנים באמצעות {variable_name} (לדוגמה, {firstname}).
• ‫before_model_callbacks/ וכן הלאה: ספריות לסקריפטים של בקשות להחזרת שיחה.

tools/

הספרייה הזו מכילה כלים 'מקומיים', שיכולים להיות פונקציות Python או כלי אחזור של מאגר נתונים.

מבנה הכלי (tools/<tool_name>/)

• ‫<tool_name>.yaml: הגדרות הכלי. צריך להשתמש ב-pythonFunction או ב-dataStoreTool, ולא בשניהם.
  • ‫displayName (string): השם של הכלי.
  • אפשרות א': כלי פונקציית Python
    • pythonFunction (אובייקט):
      • ‫name (string): שם הפונקציה.
      • ‫pythonCode (string): הנתיב להטמעה של Python ביחס לתיקיית הבסיס (לדוגמה, tools/<tool_name>/python_function/python_code.py).
      • ‫description (מחרוזת): תיאור סמנטי עבור ה-LLM.
  • אפשרות ב': הכלי Data Store
    • dataStoreTool (אובייקט):
      • name (string): שם הכלי (בדרך כלל זהה לשם המדריך).
      • description (string): תיאור של מטרת הכלי עבור הסוכן.
      • engineSource (אובייקט):
        • ‫dataStoreSources (רשימת אובייקטים):
          • dataStore (אובייקט):
            • ‫name (מחרוזת): שם המשאב המלא של מאגר הנתונים (לדוגמה, projects/...) או משתנה סביבתי (לדוגמה, $env_var).
      • ‫modalityConfigs (רשימת אובייקטים): אופציונלי. ההגדרה קובעת את ההתנהגות של TEXT או AUDIO.
        • ‫modalityType (enum): ‫TEXT או AUDIO.
        • groundingConfig (אובייקט):
          • ‫groundingLevel (float): לדוגמה, 4.0.
  • ‫executionType (enum): לדוגמה, SYNCHRONOUS.
• ‫python_function/python_code.py: קובץ קוד Python (רק עבור Python Function Tools).

toolsets/

הספרייה הזו מכילה ערכות כלים שמבוססות על OpenAPI.

מבנה ערכת הכלים (toolsets/<toolset_name>/)

• ‫<toolset_name>.yaml: הגדרות של ערכת הכלים.
  • displayName (מחרוזת): שם ערכת הכלים.
  • openApiToolset (אובייקט):
    • ‫openApiSchema (string): הנתיב לקובץ הסכימה של OpenAPI ביחס לתיקיית הבסיס (לדוגמה, toolsets/<toolset_name>/open_api_toolset/open_api_schema.yaml).
    • ‫apiAuthentication (object): הגדרת אימות (לדוגמה, serviceAgentIdTokenAuthConfig).
• ‫open_api_toolset/open_api_schema.yaml: קובץ המפרט של OpenAPI.

guardrails/

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

מבנה אמצעי הבקרה (guardrails/<guardrail_name>/)

• <guardrail_name>.yaml:
  • ‫displayName (string): שם אמצעי הבקרה.
  • description (מחרוזת): מטרה.
  • ‫enabled (boolean): האם הוא פעיל.
  • contentFilter (אובייקט):
    • ‫bannedContentsInUserInput (רשימת מחרוזות): מילים וביטויים לחסימה.
    • ‫matchType (string): לדוגמה, 'WORD_BOUNDARY_STRING_MATCH'.
  • action (אובייקט):
    • respondImmediately (אובייקט):
      • ‫responses (רשימת אובייקטים): כל אובייקט מכיל text (מחרוזת).

examples/

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

מבנה לדוגמה (examples/<example_name>/)

• ‫<example_name>.yaml: הגדרות לדוגמה.

evaluations/

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

מבנה ההערכה (evaluations/<evaluation_name>/)

• ‫<evaluation_name>.yaml: מגדיר תרחישי בדיקה עם קלט/פלט צפויים.

evaluationDatasets/

הספרייה הזו מכילה מערכי נתונים להערכה.

מבנה מערך נתוני ההערכה (evaluationDatasets/<evaluation_dataset_name>/)

• ‫<evaluation_dataset_name>.yaml: הגדרות של מערך נתוני ההערכה.