Referência de formato de exportação

Este documento descreve a estrutura de diretórios e a organização de arquivos para um arquivo de exportação e importação de aplicativos de agente.

O formato é um arquivo zip que, quando extraído, contém um diretório raiz que corresponde ao nome do aplicativo do agente.

Todos os caminhos descritos neste documento são relativos ao diretório raiz. Todas as referências a outros objetos (agentes, ferramentas etc.) precisam usar os valores displayName.

Os seguintes nomes de ferramentas são reservados:

• end_session
• transfer_to_agent
• customize_response

Ao importar e exportar, é possível usar JSON ou YAML para os arquivos individuais. Os arquivos descritos neste documento usam YAML, mas os membros JSON são semelhantes.

Diretório raiz

O diretório raiz contém os principais arquivos de configuração do aplicativo:

• app.yaml: o arquivo de configuração central do aplicativo do agente. Ele define:
  • displayName (string): o nome legível por humanos do aplicativo.
  • rootAgent (string): o nome de exibição do agente que inicia a conversa. Não use o nome do arquivo ou do diretório.
  • audioProcessingConfig (objeto): configurações de conversão de texto em voz e de voz em texto.
    • synthesizeSpeechConfigs (mapa): as chaves são códigos de localidade (por exemplo, en-US), os valores são objetos que contêm voice (string).
    • inactivityTimeout (string): string de duração (por exemplo, "2s").
    • ambientSoundConfig (objeto): configura o ruído de fundo, contendo volumeGainDb (float) e prebuiltAmbientSound (string).
  • loggingSettings (objeto): configuração para registros e gravação.
    • redactionConfig (objeto): configuração para redação de informações confidenciais.
    • audioRecordingConfig (objeto): contém gcsBucket (string).
    • bigqueryExportSettings (objeto): contém enabled (booleano), project (string), dataset (string).
    • cloudLoggingSettings (objeto): contém enableCloudLogging (booleano).
  • guardrails (lista de strings): uma lista de nomes de barreiras de proteção aplicados globalmente.
  • variableDeclarations (lista de objetos): definições de esquema para variáveis globais. Cada objeto contém:
    • name (string): nome da variável.
    • description (string): explicação da finalidade da variável.
    • schema (objeto): definição de tipo (por exemplo, { type: STRING } ou propriedades aninhadas).
    • default (qualquer): o valor padrão da variável.
  • globalInstruction (string): caminho para o arquivo de instrução do sistema global.
  • languageSettings (objeto):
    • defaultLanguageCode (string): por exemplo, "en-US".
    • supportedLanguageCodes (lista de strings): por exemplo, ["fr", "es"].
    • enableMultilingualSupport (booleano).
• environment.json: pares de chave-valor para variáveis específicas do ambiente.
• global_instruction.txt: um arquivo de texto que contém o comando/instrução principal.

agents/

Este diretório contém as definições de todos os agentes no aplicativo.

Estrutura do agente (agents/<agent_name>/)

• <agent_name>.yaml: o arquivo de configuração do agente específico.
  • displayName (string): o nome do agente.
  • modelSettings (objeto): Contém model (string).
  • instruction (string): Caminho para o arquivo de instrução relativo à raiz (por exemplo, agents/<agent_name>/instruction.txt).
  • tools (lista de strings): nomes de exibição de ferramentas locais disponíveis para esse agente.
  • toolsets (lista de objetos): conjuntos de ferramentas da OpenAPI disponíveis para esse agente. Cada objeto contém:
    • toolset (string): o nome do conjunto de ferramentas.
    • toolIds (lista de strings): IDs de operação específicos a serem expostos desse conjunto de ferramentas.
  • childAgents (lista de strings): nomes de exibição de outros agentes para os quais esse agente pode fazer a transição. Esse relacionamento é unidirecional (pai para filho). Os agentes filhos não devem listar os pais como filhos, a menos que uma transição circular seja explicitamente pretendida. Os agentes não podem ter mais de um pai (exceção: agentes de utilitários compartilhados, como escalonamento ou satisfação). O agente raiz não pode ser listado como filho de nenhum outro agente.
  • *Callbacks (lista de objetos): usado para beforeModelCallbacks, afterModelCallbacks e assim por diante. Cada objeto contém:
    • pythonCode (string): caminho para o script de callback.
    • disabled (booleano): indica se o callback está ativo.
    • description (string): descrição da lógica do callback.
• instruction.txt: o comando específico do sistema para esse agente. As referências a ferramentas precisam usar a sintaxe {@TOOL: <tool_display_name>}, as referências a outros agentes precisam usar {@AGENT: <agent_display_name>}, e as variáveis precisam ser acessadas usando {variable_name} (por exemplo, {firstname}).
• before_model_callbacks/e assim por diante: diretórios para scripts de callback.

tools/

Este diretório contém ferramentas "locais", que podem ser funções do Python ou recuperadores do Data Store.

Estrutura da ferramenta (tools/<tool_name>/)

• <tool_name>.yaml: configuração da ferramenta. Use OU pythonFunction OU dataStoreTool, não ambos.
  • displayName (string): o nome da ferramenta.
  • Opção A: ferramenta de função do Python
    • pythonFunction (objeto):
      • name (string): o nome da função.
      • pythonCode (string): Caminho para a implementação do Python relativa à raiz (por exemplo, tools/<tool_name>/python_function/python_code.py).
      • description (string): descrição semântica para o LLM.
  • Opção B: ferramenta do Data Store
    • dataStoreTool (objeto):
      • name (string): o nome da ferramenta (geralmente corresponde ao nome do diretório).
      • description (string): descrição da finalidade da ferramenta para o agente.
      • engineSource (objeto):
        • dataStoreSources (lista de objetos):
          • dataStore (objeto):
            • name (string): o nome completo do recurso do repositório de dados (por exemplo, projects/...) ou uma variável de ambiente (por exemplo, $env_var).
      • modalityConfigs (lista de objetos): opcional. Configura o comportamento para TEXT ou AUDIO.
        • modalityType (enum): TEXT ou AUDIO.
        • groundingConfig (objeto):
          • groundingLevel (float): por exemplo, 4,0.
  • executionType (enum): por exemplo, SYNCHRONOUS.
• python_function/python_code.py: o arquivo de código Python (somente para ferramentas de função do Python).

toolsets/

Este diretório contém conjuntos de ferramentas baseados na OpenAPI.

Estrutura do conjunto de ferramentas (toolsets/<toolset_name>/)

• <toolset_name>.yaml: Configuração do conjunto de ferramentas.
  • displayName (string): nome do conjunto de ferramentas.
  • openApiToolset (objeto):
    • openApiSchema (string): Caminho para o arquivo de esquema da OpenAPI relativo à raiz (por exemplo, toolsets/<toolset_name>/open_api_toolset/open_api_schema.yaml).
    • apiAuthentication (objeto): configuração de autenticação (por exemplo, serviceAgentIdTokenAuthConfig).
• open_api_toolset/open_api_schema.yaml: o arquivo de especificação da OpenAPI.

guardrails/

Este diretório define filtros de segurança de conteúdo.

Estrutura da barreira de proteção (guardrails/<guardrail_name>/)

• <guardrail_name>.yaml:
  • displayName (string): nome da barreira de proteção.
  • description (string): finalidade.
  • enabled (booleano): indica se está ativo.
  • contentFilter (objeto):
    • bannedContentsInUserInput (lista de strings): palavras e frases a serem bloqueadas.
    • matchType (string): por exemplo, "WORD_BOUNDARY_STRING_MATCH".
  • action (objeto):
    • respondImmediately (objeto):
      • responses (lista de objetos): cada objeto contém text (string).

examples/

Este diretório contém as definições de exemplos de poucas demonstrações usados no aplicativo do agente.

Estrutura de exemplo (examples/<example_name>/)

• <example_name>.yaml: configuração do exemplo.

evaluations/

Este diretório contém definições de teste.

Estrutura de avaliação (evaluations/<evaluation_name>/)

• <evaluation_name>.yaml: Define cenários de teste com entradas/saídas esperadas.

evaluationDatasets/

Este diretório contém conjuntos de dados de avaliação.

Estrutura do conjunto de dados de avaliação (evaluationDatasets/<evaluation_dataset_name>/)

• <evaluation_dataset_name>.yaml: Configuração para o conjunto de dados de avaliação.