本文档概述了代理应用导出和导入文件的目录结构和文件组织。
该格式是一个 zip 文件，解压缩后会包含一个与代理应用名称对应的根目录。
本文档中描述的所有路径均相对于根目录。
对其他对象（代理、工具等）的所有引用都必须使用其 displayName 值。
以下工具名称是保留的：
end_sessiontransfer_to_agentcustomize_response
导入和导出时，您可以为各个文件使用 JSON 或 YAML。 本文档中描述的文件使用 YAML，但 JSON 成员类似。
根目录
根目录包含应用的主要配置文件：
app.yaml：代理应用的核心配置文件。它定义了：displayName（字符串）：应用的人类可读名称。rootAgent（字符串）：启动对话的代理的显示名称 。请勿使用文件名或目录名称。audioProcessingConfig（对象）：文字转语音和语音转文字的设置。synthesizeSpeechConfigs（映射）：键是语言区域代码（例如en-US），值是包含voice（字符串）的对象。inactivityTimeout（字符串）：时长字符串（例如“2s”）。ambientSoundConfig（对象）：配置背景噪声，包含volumeGainDb（浮点数）和prebuiltAmbientSound（字符串）。
loggingSettings（对象）：日志和记录的配置。redactionConfig（对象）：用于修订敏感信息的配置。audioRecordingConfig（对象）：包含gcsBucket（字符串）。bigqueryExportSettings（对象）：包含enabled（布尔值）、project（字符串）、dataset（字符串）。cloudLoggingSettings（对象）：包含enableCloudLogging（布尔值）。
guardrails（字符串列表）：全局应用的安全护栏名称列表。variableDeclarations（对象列表）：全局变量的架构定义。每个对象包含：name（字符串）：变量名称。description（字符串）：对变量用途的说明。schema（对象）：类型定义（例如，{ type: STRING }或嵌套属性）。default（任意）：变量的默认值。
globalInstruction（字符串）：全局系统指令文件的路径。languageSettings（对象）：defaultLanguageCode（字符串）：例如“en-US”。supportedLanguageCodes（字符串列表）： 例如["fr", "es"]。enableMultilingualSupport（布尔值）。
environment.json：特定于环境的变量的键值对。global_instruction.txt：包含主要提示/指令的文本文件。
agents/
此目录包含应用中所有代理的定义。
代理结构 (agents/<agent_name>/)
<agent_name>.yaml：特定代理的配置文件。displayName（字符串）：代理的名称。modelSettings（对象）： 包含model（字符串）。instruction（字符串）： 相对于根目录的指令文件路径 （例如agents/<agent_name>/instruction.txt）。tools（字符串列表）：此代理可用的本地工具的显示名称。toolsets（对象列表）：此代理可用的 OpenAPI 工具集。每个对象包含：toolset（字符串）：工具集的名称。toolIds（字符串列表）：要从该工具集公开的特定操作 ID。
childAgents（字符串列表）：此代理可以转换到的其他代理的显示名称。此关系是单向的（父级到子级）；除非明确打算进行循环转换，否则子代理不应将其父级列为子级。代理不能有多个父级（例外情况：共享实用程序代理，例如 Escalation 或 Satisfaction）。 根代理不能列为任何其他代理的子级。*Callbacks（对象列表）：用于beforeModelCallbacks、afterModelCallbacks等。 每个对象包含：pythonCode（字符串）：回调脚本的路径。disabled（布尔值）：回调是否处于活跃状态。description（字符串）：对回调逻辑的说明。
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（字符串）：工具的名称。- 选项 A：Python 函数工具
pythonFunction（对象）：name（字符串）：函数名称。pythonCode（字符串）： 相对于根目录的 Python 实现路径 （例如tools/<tool_name>/python_function/python_code.py）。description（字符串）：LLM 的语义说明。
- 选项 B：数据存储工具
dataStoreTool（对象）：name（字符串）：工具名称（通常与目录名称一致）。description（字符串）：对代理的工具用途的说明。engineSource（对象）：dataStoreSources（对象列表）：dataStore（对象）：name（字符串）：数据存储区的完整资源名称（例如projects/...）或环境变量（例如$env_var）。
modalityConfigs（对象列表）：可选。配置 TEXT 或 AUDIO 的行为。modalityType（枚举）：TEXT或AUDIO。groundingConfig（对象）：groundingLevel（浮点数）：例如 4.0。
executionType（枚举）：例如SYNCHRONOUS。
python_function/python_code.py：Python 代码文件（仅适用于 Python 函数工具）。
toolsets/
此目录包含基于 OpenAPI 的工具集。
工具集结构 (toolsets/<toolset_name>/)
<toolset_name>.yaml：工具集的配置。displayName（字符串）：工具集的名称。openApiToolset（对象）：openApiSchema（字符串）：相对于根目录的 OpenAPI 架构文件路径（例如toolsets/<toolset_name>/open_api_toolset/open_api_schema.yaml）。apiAuthentication（对象）：身份验证配置（例如serviceAgentIdTokenAuthConfig）。
open_api_toolset/open_api_schema.yaml：OpenAPI 规范文件。
guardrails/
此目录定义了内容安全过滤条件。
安全护栏结构 (guardrails/<guardrail_name>/)
<guardrail_name>.yaml：displayName（字符串）：安全护栏的名称。description（字符串）：用途。enabled（布尔值）：是否处于活跃状态。contentFilter（对象）：bannedContentsInUserInput（字符串列表）：要屏蔽的字词和短语。matchType（字符串）：例如“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：评估数据集的配置。