PolyAI 中文文档 下载 App

ADK pull 下来的本地项目结构：YAML 和 Python 文件组织

目录结构总览

一次成功的 poly pull 后，本地目录结构大致是：

project-root/
├── agent_settings/           # 智能体身份和行为
│   ├── role.yaml             # 角色设定
│   ├── personality.yaml      # 语气和风格
│   └── rules.txt             # 固定规则（始终为真的指令）
├── topics/                   # 知识话题（RAG 召回）
│   ├── Frequently Asked Questions.yaml
│   ├── Billing Issues.yaml
│   └── ...
├── functions/                # Python 业务逻辑
│   ├── check_billing.py
│   ├── verify_identity.py
│   └── ...
├── flows/                    # 多步引导式对话
│   ├── greeting/
│   │   ├── flow_config.yaml
│   │   ├── flow_step_welcome.yaml
│   │   └── flow_step_intro.yaml
│   └── reservation/
│       ├── flow_config.yaml
│       ├── flow_step_*.yaml
│       └── transition_check_availability.py
├── config/                   # 其他配置
│   ├── entities/             # 自定义实体类型
│   │   └── billing_amount.yaml
│   ├── handoffs/             # 转接人工配置
│   ├── sms_templates.yaml    # 短信模板
│   └── variant_attributes.yaml
├── voice/                    # 语音渠道配置
├── chat/                     # 聊天渠道配置
├── test_suite/               # 模拟测试用例
└── .polyconfig               # ADK 内部配置（不要手动改）

每类资源的职责

目录职责和 Studio 的对应
agent_settings/智能体始终遵守的设定Agent Settings 页面里的各项配置
topics/知识话题——用户问什么问题，智能体答什么Knowledge → FAQs 区域
functions/Python 业务逻辑——计算、API 调用、条件判断Studio Functions 区域
flows/多步引导式对话的完整步骤Studio Flows 编辑器
config/实体类型、转接配置、短信模板等Studio 分散在各个设置区域
voice/ / chat/渠道专属设置Studio Channels 区域

一个 topic YAML 长什么样

enabled: true
actions: ""
content: |
  本店接受 Visa、Mastercard 和 PayPal 支付。
  退款通常需要 3-5 个工作日处理。
example_queries:
  - What payment methods do you accept?
  - 退款需要多久到账？
  - Can I pay with PayPal?

每个字段对应 Studio 界面里的一个输入框：

字段对应 Studio 输入
enabled话题是否激活
actionsActions 字段（触发 Flow、转接人工等）
content回答内容（多行）
example_queries示例问题列表

资源交叉引用语法

不同文件之间的引用使用占位符语法，ADK 在 push 时自动解析：

语法含义示例
{{fn:function_name}}引用一个 Python 函数Flow 里调用 billing 检查函数
{{entity:entity_name}}引用一个实体类型Flow Collect Step 里指定要收集的实体
{{ho:handoff_name}}引用一个转接目标Flow 里配置转接人工时引用
{{vrbl:variable_name}}引用一个状态变量跨步骤传递数据

这种语法让你在 YAML 里引用 Python 函数、实体类型等都很直观。

知识 vs 行为的边界

ADK 文档里特别强调这个区分，因为这是新手最容易犯的错：

类型放在哪里内容
知识 / 事实topics/主题特定的信息，通过 RAG 动态召回
行为 / 逻辑agent_settings/rules.txt（始终为真的指令）或 flows/ + functions/（条件逻辑）智能体应该做什么、什么时候做

常见错误：