Referensi format ekspor

Dokumen ini menguraikan struktur direktori dan organisasi file untuk file ekspor dan impor aplikasi agen.

Formatnya adalah file zip yang saat diekstrak berisi direktori root yang sesuai dengan nama aplikasi agen.

Semua jalur yang dijelaskan dalam dokumen ini bersifat relatif terhadap direktori root. Semua referensi ke objek lain (agen, alat, dan sebagainya) harus menggunakan nilai displayName-nya.

Nama alat berikut dicadangkan:

  • end_session
  • transfer_to_agent
  • customize_response

Saat mengimpor dan mengekspor, Anda dapat menggunakan JSON atau YAML untuk setiap file. File yang dijelaskan dalam dokumen ini menggunakan YAML, tetapi anggota JSON-nya serupa.

Direktori Utama

Direktori root berisi file konfigurasi utama untuk aplikasi:

  • app.yaml: File konfigurasi pusat untuk aplikasi agen. Ini menentukan:
    • displayName (string): Nama aplikasi yang dapat dibaca manusia.
    • rootAgent (string): Nama Tampilan agen yang memulai percakapan. Jangan gunakan nama file atau nama direktori.
    • audioProcessingConfig (objek): Setelan untuk text-to-speech dan speech-to-text.
      • synthesizeSpeechConfigs (peta): Kunci adalah kode lokal (misalnya, en-US), nilai adalah objek yang berisi voice (string).
      • inactivityTimeout (string): String durasi (misalnya, "2s").
      • ambientSoundConfig (objek): Mengonfigurasi suara bising di latar belakang, yang berisi volumeGainDb (float) dan prebuiltAmbientSound (string).
    • loggingSettings (objek): Konfigurasi untuk log dan perekaman.
      • redactionConfig (objek): Konfigurasi untuk menyamarkan info sensitif.
      • audioRecordingConfig (objek): Berisi gcsBucket (string).
      • bigqueryExportSettings (objek): Berisi enabled (boolean), project (string), dataset (string).
      • cloudLoggingSettings (objek): Berisi enableCloudLogging (boolean).
    • guardrails (daftar string): Daftar nama pembatas yang diterapkan secara global.
    • variableDeclarations (daftar objek): Definisi skema untuk variabel global. Setiap objek berisi:
      • name (string): Nama variabel.
      • description (string): Penjelasan tujuan variabel.
      • schema (objek): Definisi jenis (misalnya, { type: STRING } atau properti bertingkat).
      • default (apa pun): Nilai default untuk variabel.
    • globalInstruction (string): Jalur ke file petunjuk sistem global.
    • languageSettings (objek):
      • defaultLanguageCode (string): misalnya, "en-US".
      • supportedLanguageCodes (daftar string): misalnya, ["fr", "es"].
      • enableMultilingualSupport (boolean).
  • environment.json: Pasangan nilai kunci untuk variabel khusus lingkungan.
  • global_instruction.txt: File teks yang berisi perintah/petunjuk utama.

agents/

Direktori ini berisi definisi untuk semua agen dalam aplikasi.

Struktur Agen (agents/<agent_name>/)

  • <agent_name>.yaml: File konfigurasi untuk agen tertentu.
    • displayName (string): Nama agen.
    • modelSettings (objek): Berisi model (string).
    • instruction (string): Jalur ke file petunjuk relatif terhadap root (misalnya, agents/<agent_name>/instruction.txt).
    • tools (daftar string): Nama Tampilan alat lokal yang tersedia untuk agen ini.
    • toolsets (daftar objek): Kumpulan alat OpenAPI yang tersedia untuk agen ini. Setiap objek berisi:
      • toolset (string): Nama toolset.
      • toolIds (daftar string): ID operasi tertentu yang akan diekspos dari toolset tersebut.
    • childAgents (daftar string): Nama tampilan agen lain yang dapat dituju agen ini. Hubungan ini bersifat satu arah (induk ke turunan); agen turunan tidak boleh mencantumkan induknya sebagai turunan kecuali jika transisi melingkar dimaksudkan secara eksplisit. Agen tidak boleh memiliki lebih dari satu induk (kecuali: agen utilitas bersama seperti Escalation atau Satisfaction). Agen Root tidak dapat dicantumkan sebagai turunan agen lain.
    • *Callbacks (daftar objek): Digunakan untuk beforeModelCallbacks, afterModelCallbacks, dan sebagainya. Setiap objek berisi:
      • pythonCode (string): Jalur ke skrip callback.
      • disabled (boolean): Apakah callback aktif.
      • description (string): Deskripsi logika callback.
  • instruction.txt: Perintah sistem khusus untuk agen ini. Referensi ke alat harus menggunakan sintaksis {@TOOL: <tool_display_name>}, referensi ke agen lain harus menggunakan {@AGENT: <agent_display_name>}, dan variabel harus diakses menggunakan {variable_name} (misalnya, {firstname}).
  • before_model_callbacks/, dan seterusnya: Direktori untuk skrip callback.

tools/

Direktori ini berisi alat "lokal", yang dapat berupa fungsi Python atau pengambil Data Store.

Struktur Alat (tools/<tool_name>/)

  • <tool_name>.yaml: Konfigurasi untuk alat. Gunakan SALAH SATU pythonFunction ATAU dataStoreTool, jangan keduanya.
    • displayName (string): Nama alat.
    • Opsi A: Alat Fungsi Python
      • pythonFunction (objek):
        • name (string): Nama fungsi.
        • pythonCode (string): Jalur ke penerapan Python relatif terhadap root (misalnya, tools/<tool_name>/python_function/python_code.py).
        • description (string): Deskripsi semantik untuk LLM.
    • Opsi B: Alat Penyimpanan Data
      • dataStoreTool (objek):
        • name (string): Nama alat (biasanya cocok dengan nama direktori).
        • description (string): Deskripsi tujuan alat untuk agen.
        • engineSource (objek):
          • dataStoreSources (daftar objek):
            • dataStore (objek):
              • name (string): Nama lengkap resource penyimpanan data (misalnya, projects/...) atau variabel lingkungan (misalnya, $env_var).
        • modalityConfigs (daftar objek): Opsional. Mengonfigurasi perilaku untuk TEXT atau AUDIO.
          • modalityType (enum): TEXT atau AUDIO.
          • groundingConfig (objek):
            • groundingLevel (float): misalnya, 4.0.
    • executionType (enum): misalnya, SYNCHRONOUS.
  • python_function/python_code.py: File kode Python (hanya untuk Alat Fungsi Python).

toolsets/

Direktori ini berisi toolset berbasis OpenAPI.

Struktur Toolset (toolsets/<toolset_name>/)

  • <toolset_name>.yaml: Konfigurasi untuk toolset.
    • displayName (string): Nama toolset.
    • openApiToolset (objek):
      • openApiSchema (string): Jalur ke file skema OpenAPI relatif terhadap root (misalnya, toolsets/<toolset_name>/open_api_toolset/open_api_schema.yaml).
      • apiAuthentication (objek): Konfigurasi autentikasi (misalnya, serviceAgentIdTokenAuthConfig).
  • open_api_toolset/open_api_schema.yaml: File spesifikasi OpenAPI.

guardrails/

Direktori ini menentukan filter keamanan konten.

Struktur Pembatas (guardrails/<guardrail_name>/)

  • <guardrail_name>.yaml:
    • displayName (string): Nama pembatas.
    • description (string): Tujuan.
    • enabled (boolean): Apakah aktif.
    • contentFilter (objek):
      • bannedContentsInUserInput (daftar string): Kata dan frasa yang akan diblokir.
      • matchType (string): misalnya, "WORD_BOUNDARY_STRING_MATCH".
    • action (objek):
      • respondImmediately (objek):
        • responses (daftar objek): Setiap objek berisi text (string).

examples/

Direktori ini berisi definisi untuk contoh few-shot yang digunakan dalam aplikasi agen.

Struktur Contoh (examples/<example_name>/)

  • <example_name>.yaml: Konfigurasi untuk contoh.

evaluations/

Direktori ini berisi definisi pengujian.

Struktur Evaluasi (evaluations/<evaluation_name>/)

  • <evaluation_name>.yaml: Menentukan skenario pengujian dengan input/output yang diharapkan.

evaluationDatasets/

Direktori ini berisi set data evaluasi.

Struktur Set Data Evaluasi (evaluationDatasets/<evaluation_dataset_name>/)

  • <evaluation_dataset_name>.yaml: Konfigurasi untuk set data evaluasi.