Referencia del formato de exportación

En este documento, se describe la estructura de directorios y la organización de archivos para un archivo de importación y exportación de aplicaciones de agentes.

El formato es un archivo ZIP que, cuando se extrae, contiene un directorio raíz que corresponde al nombre de la aplicación del agente.

Todas las rutas de acceso que se describen en este documento son relativas al directorio raíz. Todas las referencias a otros objetos (agentes, herramientas, etcétera) deben usar sus valores displayName.

Los siguientes nombres de herramientas están reservados:

  • end_session
  • transfer_to_agent
  • customize_response

Cuando importas y exportas, puedes usar JSON o YAML para los archivos individuales. Los archivos que se describen en este documento usan YAML, pero los miembros de JSON son similares.

Directorio raíz

El directorio raíz contiene los archivos de configuración principales de la aplicación:

  • app.yaml: Es el archivo de configuración central de la aplicación del agente. Define lo siguiente:
    • displayName (string): Es el nombre legible de la aplicación.
    • rootAgent (string): Es el nombre visible del agente que inicia la conversación. No uses el nombre del archivo ni del directorio.
    • audioProcessingConfig (objeto): Es la configuración de texto a voz y de voz a texto.
      • synthesizeSpeechConfigs (mapa): Las claves son códigos de configuración regional (por ejemplo, en-US) y los valores son objetos que contienen voice (string).
      • inactivityTimeout (string): Es la cadena de duración (por ejemplo, "2s").
      • ambientSoundConfig (objeto): Configura el ruido de fondo, que contiene volumeGainDb (float) y prebuiltAmbientSound (string).
    • loggingSettings (objeto): Es la configuración de registros y grabación.
      • redactionConfig (objeto): Es la configuración para redactar información sensible.
      • audioRecordingConfig (objeto): Contiene gcsBucket (string).
      • bigqueryExportSettings (objeto): Contiene enabled (booleano), project (string) y dataset (string).
      • cloudLoggingSettings (objeto): Contiene enableCloudLogging (booleano).
    • guardrails (lista de cadenas): Es una lista de nombres de límites aplicados de forma global.
    • variableDeclarations (lista de objetos): Son las definiciones de esquema para las variables globales. Cada objeto contiene lo siguiente:
      • name (string): Es el nombre de la variable.
      • description (string): Es la explicación del propósito de la variable.
      • schema (objeto): Es la definición de tipo (por ejemplo, { type: STRING } o propiedades anidadas).
      • default (cualquier tipo): Es el valor predeterminado de la variable.
    • globalInstruction (string): Es la ruta de acceso al archivo de instrucciones del sistema global.
    • languageSettings (objeto):
      • defaultLanguageCode (string): Por ejemplo, "en-US".
      • supportedLanguageCodes (lista de cadenas): por ejemplo, ["fr", "es"].
      • enableMultilingualSupport (booleano).
  • environment.json: Son los pares clave-valor para las variables específicas del entorno.
  • global_instruction.txt: Es un archivo de texto que contiene el mensaje o la instrucción principal.

agents/

Este directorio contiene las definiciones de todos los agentes de la aplicación.

Estructura del agente (agents/<agent_name>/)

  • <agent_name>.yaml: Es el archivo de configuración del agente específico.
    • displayName (string): Es el nombre del agente.
    • modelSettings (objeto): Contiene model (string).
    • instruction (string): Es la ruta de acceso al archivo de instrucciones en relación con la raíz (por ejemplo, agents/<agent_name>/instruction.txt).
    • tools (lista de cadenas): Son los nombres visibles de las herramientas locales disponibles para este agente.
    • toolsets (lista de objetos): Son los conjuntos de herramientas de OpenAPI disponibles para este agente. Cada objeto contiene lo siguiente:
      • toolset (string): Es el nombre del conjunto de herramientas.
      • toolIds (lista de cadenas): Son los IDs de operación específicos que se expondrán desde ese conjunto de herramientas.
    • childAgents (lista de cadenas): Son los nombres visibles de otros agentes a los que este agente puede hacer la transición. Esta relación es unidireccional (de superior a secundario). Los agentes secundarios no deben enumerar a sus superiores como secundarios, a menos que se pretenda explícitamente una transición circular. Los agentes no pueden tener más de un superior (excepción: agentes de utilidad compartidos, como Escalation o Satisfaction). El agente raíz no se puede enumerar como secundario de ningún otro agente.
    • *Callbacks (lista de objetos): Se usa para beforeModelCallbacks, afterModelCallbacks, etcétera. Cada objeto contiene lo siguiente:
      • pythonCode (string): Es la ruta de acceso a la secuencia de comandos de devolución de llamada.
      • disabled (booleano): Indica si la devolución de llamada está activa.
      • description (string): Es la descripción de la lógica de la devolución de llamada.
  • instruction.txt: Es el mensaje del sistema específico para este agente. Las referencias a las herramientas deben usar la sintaxis {@TOOL: <tool_display_name>}, las referencias a otros agentes deben usar {@AGENT: <agent_display_name>}, y se debe acceder a las variables con {variable_name} (por ejemplo, {firstname}).
  • before_model_callbacks/, etcétera: Son los directorios de las secuencias de comandos de devolución de llamada.

tools/

Este directorio contiene herramientas "locales", que pueden ser funciones de Python o recuperadores de Data Store.

Estructura de la herramienta (tools/<tool_name>/)

  • <tool_name>.yaml: Es la configuración de la herramienta. Usa pythonFunction o dataStoreTool, no ambos.
    • displayName (string): Es el nombre de la herramienta.
    • Opción A: Herramienta de función de Python
      • pythonFunction (objeto):
        • name (string): Es el nombre de la función.
        • pythonCode (string): Ruta de acceso a la implementación de Python en relación con la raíz (por ejemplo, tools/<tool_name>/python_function/python_code.py).
        • description (string): Es la descripción semántica para el LLM.
    • Opción B: Herramienta de Data Store
      • dataStoreTool (objeto):
        • name (string): Es el nombre de la herramienta (por lo general, coincide con el nombre del directorio).
        • description (string): Es la descripción del propósito de la herramienta para el agente.
        • engineSource (objeto):
          • dataStoreSources (lista de objetos):
            • dataStore (objeto):
              • name (string): Es el nombre completo del recurso del almacén de datos (por ejemplo, projects/...) o una variable de entorno (por ejemplo, $env_var).
        • modalityConfigs (lista de objetos): Es opcional. Configura el comportamiento para TEXT o AUDIO.
          • modalityType (enum): TEXT o AUDIO.
          • groundingConfig (objeto):
            • groundingLevel (float): Por ejemplo, 4.0.
    • executionType (enum): Por ejemplo, SYNCHRONOUS.
  • python_function/python_code.py: Es el archivo de código de Python (solo para las herramientas de función de Python).

toolsets/

Este directorio contiene conjuntos de herramientas basados en OpenAPI.

Estructura del conjunto de herramientas (toolsets/<toolset_name>/)

  • <toolset_name>.yaml: Es la configuración del conjunto de herramientas.
    • displayName (string): Es el nombre del conjunto de herramientas.
    • openApiToolset (objeto):
      • openApiSchema (string): Ruta de acceso al archivo de esquema de OpenAPI en relación con la raíz (por ejemplo, toolsets/<toolset_name>/open_api_toolset/open_api_schema.yaml).
      • apiAuthentication (objeto): Es la configuración de autenticación (por ejemplo, serviceAgentIdTokenAuthConfig).
  • open_api_toolset/open_api_schema.yaml: Es el archivo de especificación de OpenAPI.

guardrails/

Este directorio define los filtros de seguridad de contenido.

Estructura de los límites (guardrails/<guardrail_name>/)

  • <guardrail_name>.yaml:
    • displayName (string): Es el nombre del límite.
    • description (string): Es el propósito.
    • enabled (booleano): Indica si está activo.
    • contentFilter (objeto):
      • bannedContentsInUserInput (lista de cadenas): Son las palabras y frases que se bloquearán.
      • matchType (string): Por ejemplo, "WORD_BOUNDARY_STRING_MATCH".
    • action (objeto):
      • respondImmediately (objeto):
        • responses (lista de objetos): Cada objeto contiene text (string).

examples/

Este directorio contiene las definiciones de los ejemplos de pocos intentos que se usan en la aplicación del agente.

Estructura del ejemplo (examples/<example_name>/)

  • <example_name>.yaml: Es la configuración del ejemplo.

evaluations/

Este directorio contiene definiciones de pruebas.

Estructura de la evaluación (evaluations/<evaluation_name>/)

  • <evaluation_name>.yaml: Define situaciones de prueba con entradas y salidas esperadas.

evaluationDatasets/

Este directorio contiene conjuntos de datos de evaluación.

Estructura del conjunto de datos de evaluación (evaluationDatasets/<evaluation_dataset_name>/)

  • <evaluation_dataset_name>.yaml: Es la configuración del conjunto de datos de evaluación.