COTA 文档

欢迎使用 COTA (COllaborative Task Agent) - 生成式多对话平台！

🚀 什么是 COTA？

COTA 是一个强大的生成式多对话平台，专为构建智能对话机器人和任务执行代理而设计。

✨ 核心特性

  • 🤖 多智能体架构: 支持 simplebot 和 taskbot 等多种智能体类型
  • 💬 多通道支持: 命令行、WebSocket、Socket.IO、SSE 等多种交互方式
  • 🧠 LLM 集成: 支持 OpenAI、DeepSeek、通义千问等主流大语言模型
  • 📝 对话管理: 内置 DST(对话状态跟踪) 和对话流程控制
  • 🔧 灵活配置: 支持 YAML 配置和插件扩展
  • 📊 任务编排: 强大的任务执行和状态管理能力

🏃‍♂️ 快速开始

如果你是第一次使用 COTA，建议从以下步骤开始：

  1. 安装和环境准备
  2. 安装 COTA
  3. 快速开始教程

📚 文档导航

  • 安装指南: 环境准备和安装步骤
  • 教程: 从基础到高级的使用教程
  • 基础概念: 了解 COTA 的核心概念和架构
  • API 参考: 详细的 API 文档和示例

🤝 社区与支持

💡 提示: 使用左侧导航菜单浏览不同章节，或使用顶部搜索功能快速找到所需内容。

虚拟环境设置

推荐使用虚拟环境来隔离Python项目。如使用virtualenv创建隔离的Python环境，来防止了依赖冲突。

推荐Python版本

使用Python 3.12及以上版本，以确保兼容性和最新的语言特性。

Ubuntu

  1. 创建虚拟环境：

    python3 -m venv ./venv

  2. 激活虚拟环境：

    source ./venv/bin/activate

macOS

  1. 创建虚拟环境：

    python3 -m venv ./venv

  2. 激活虚拟环境：

    source ./venv/bin/activate

Windows

  1. 创建虚拟环境：

    C:\> python3 -m venv ./venv

  2. 激活虚拟环境：

    C:\> .\venv\Scripts\activate

激活虚拟环境后，你就可以在这个环境中安装项目所需的Python包，而不会影响系统的其他部分。

提醒

  • 确保你使用的Python版本符合项目要求。
  • 激活虚拟环境后，你可以在环境中安装项目所需的Python包，而不会影响系统的其他部分。
  • 当你完成工作后，可以通过运行deactivate命令来退出虚拟环境。

安装COTA

Ubuntu / macOS / Windows

可以选择通过pip安装（推荐）或通过源代码安装。

  • pip安装：适合大多数用户，简单快捷
  • 源代码安装：适合开发者或需要最新开发版本的用户

提醒

请确保准备好虚拟环境，以下操作建议在虚拟环境中进行

通过pip安装（推荐）

Pip是Python的包管理工具，可以方便地安装和管理Python包。这是最简单快捷的安装方式，推荐大多数用户使用。以下是通过pip安装COTA的步骤：

  1. 确保你已经安装了Python和pip：

    • 你可以通过运行以下命令来检查是否安装了Python和pip： 
      python3 --version
pip3 --version
    • 如果没有安装，请先安装Python和pip。
    • 同时确保pip更新到最新的版本 
      pip3 install -U pip

  2. 使用pip安装COTA：

    • 打开终端或命令提示符，运行以下命令： 
      pip3 install cota
    • 安装过程中会自动下载并安装所需的依赖包。

  3. 验证安装：

    • 安装完成后，你可以通过运行以下命令来验证COTA是否安装成功： 
      cota --version
    • 如果显示版本号，说明安装成功！

  4. 开始使用：

    • 创建你的第一个智能体项目： 
      cota init
    • 进入项目目录并配置： 
      cd cota_projects/simplebot
# 编辑 endpoints.yml 配置你的LLM API密钥
    • 启动对话测试： 
      cota shell --debug

通过源代码安装

如果你需要最新的开发版本、想要参与开发或自定义安装，可以通过源代码安装COTA。以下是通过源代码安装COTA的步骤：

  1. 安装Poetry：

    • Poetry是一个依赖管理和打包工具，可以帮助你更方便地管理Python项目。首先，你需要安装Poetry。

      方式1：通过pip安装Poetry（推荐）：

      pip3 install poetry

      方式2：同样也可直接安装

      curl -sSL https://install.python-poetry.org | python3 -

    • 安装完成后，你可以通过运行以下命令来验证Poetry是否安装成功：

      poetry --version

  2. 克隆COTA的源代码仓库：

    • 打开终端或命令提示符，运行以下命令来克隆COTA的源代码仓库： 
      git clone https://github.com/CotaAI/cota.git

  3. 进入源代码目录：

    • 进入克隆下来的COTA源代码目录： 
      cd cota

  4. 使用Poetry安装依赖：

    • 使用Poetry来安装COTA所需的依赖包。运行以下命令： 
      poetry install

  5. 激活虚拟环境：

    • 激活Poetry创建的虚拟环境： 
      poetry shell

  6. 验证安装：

    • 安装完成后，你可以通过运行以下命令来验证COTA是否安装成功： 
      cota --version

  7. 开始使用：

    • 创建你的第一个智能体项目： 
      cota init

快捷创建智能体

cota提供了多个场景的智能体示例，方便测试和参考

cota init

执行上面初始化命令后，得到cota_projects目录，cota_projects中的每个目录都是一个智能体示例：

  • weather: 天气查询机器人，展示基础配置和Chain of Thought推理过程
  • pet: 宠物问诊机器人，展示代理用户模式（proxy user）和数据生成功能

文件说明

每个智能体至少包括endpoints.yml和agent.yml两个配置文件。

endpoints.yml 定义agent运行需要的服务配置，包括数据库类型及配置（用于维护对话状态）、通道类型及配置、大语言模型配置等。 agent.yml 定义了agent的基本元素，包括智能体的系统描述、可执行动作、对话配置和策略配置等。

运行智能体

选择cota_projects中的文件夹进入，如weather示例：

cd cota_projects/weather

配置LLM

编辑endpoints.yml文件，配置您的LLM API密钥：

llms:
  deepseek:
    type: openai
    model: deepseek-chat
    key: your_actual_api_key_here  # 替换为您的真实API密钥
    apibase: https://api.deepseek.com/v1

启动调试模式

使用命令行与智能体交互，适用于调试和验证：

cota shell --debug

启动服务模式

如果需要部署到生产环境提供API服务：

# WebSocket服务
cota run --channel=websocket --host=0.0.0.0 --port=5005

# 或启动HTTP API服务器
cota server --host=0.0.0.0 --port=8000

💡 提示：初次测试建议使用Memory存储类型，生产环境推荐配置数据库以获得更好的性能和可靠性。

实践1：构建智能天气查询机器人

学习目标：掌握COTA框架的基础配置和Chain of Thought推理机制

这个实践将基于weather bot示例，带您从零开始构建一个具有思维链推理能力的天气查询机器人。

📋 项目概览

功能特性

  • ✅ 智能天气查询（单城市/多城市对比）
  • ✅ 思维链推理过程完全可视化
  • ✅ 多轮对话状态管理
  • ✅ 表单式信息收集
  • ✅ 人工客服转接

技术亮点

  • Chain of Thought: 每个决策都有明确的推理过程
  • 状态管理: 智能收集和管理对话状态
  • 策略组合: trigger + match双重策略保证响应质量

🏗️ 项目结构

weather/
├── agent.yml          # 智能体核心配置
├── endpoints.yml       # LLM和服务配置
├── policy/
│   ├── data.yml       # Chain of Thought标注数据
│   └── rules.yml      # 触发规则配置
└── README.md          # 文档说明

⚙️ 配置详解

1. 智能体配置 (agent.yml)

系统描述

system:
  description: 你是一个智能助手，你需要认真负责的回答帮用户解决问题;要求回答的尽量精准和谨慎

对话配置

dialogue:
  use_proxy_user: false  # 真实用户交互模式
  max_proxy_step: 30     # 最大对话轮次
  max_tokens: 500        # 控制回复长度

策略配置

policies:
  - type: trigger        # 基于规则的快速响应
  - type: match         # 基于标注的思维链推理

2. 核心动作定义

BotUtter - 智能回复动作

BotUtter:
  description: "回复用户"
  prompt: |
    你是一个智能助手，需要根据当前对话历史生成合适的回复。
    
    **输出格式要求：**
    你必须严格按照以下JSON格式响应：
    ```json
    {"thought": "<你的推理过程>", "text": "<你的回复内容>"}
    ```
    
    **对话历史：**
    {{history_actions_with_thoughts}}

Selector - 动作选择器

Selector:
  description: "选择合适的Actions"
  prompt: |
    你是一个智能对话助手，需要根据当前对话状态选择下一个最合适的Action。
    
    **输出格式：**
    ```json
    {"thought": "<你的推理过程>", "action": "<工具名称>"}
    ```
    
    **可用的Action工具：**
    {{action_descriptions}}
    
    **当前对话状态：**
    {{history_actions_with_thoughts}}

Weather - 天气查询表单

Weather:
  description: "查询天气信息"
  slots:
    city:
      description: "用户询问的城市名称"
    time:
      description: "用户询问的时间（今天、明天等）"
  executer:
    type: script
    script: |
      # 模拟天气查询
      return {"text": "sunny", "metadata": {}}

3. LLM配置 (endpoints.yml)

llms:
  deepseek:
    type: openai
    model: deepseek-chat
    key: your_api_key_here  # 请替换为真实API密钥
    apibase: https://api.deepseek.com/v1

channel:
  type: redis
  host: localhost
  port: 6379
  db: 1

🧠 Chain of Thought 核心机制

思维链标注数据 (policy/data.yml)

policies:
- title: 复杂查天气  
  actions:
    - name: UserUtter
      result: 成都和重庆天气咋样哪个好，我要看下去哪个城市旅游
    - name: Selector
      thought: 用户询问天气，同时问了成都和重庆天气，并让我做比较，我应该先执行Weather得到成都的天气，然后再执行Weather得到重庆的天气，然后比较
      result: Weather
    - name: Weather
      slots:
        city: 成都
        time: 今天
      state: end
      result: 
        text: sunny
        metadata: {}
    - name: Selector  
      thought: 已经查询了成都天气，现在需要查询重庆天气进行对比
      result: Weather
    - name: Weather
      slots:
        city: 重庆  
        time: 今天
      state: end
      result:
        text: cloudy
        metadata: {}
    - name: Selector
      thought: 已获取成都(sunny)和重庆(cloudy)的天气，现在需要对比并给出旅游建议
      result: BotUtter
    - name: BotUtter
      result:
        text: 成都今天天气晴朗(sunny)，重庆今天是阴天(cloudy)。从天气角度来看，成都的天气更适合旅游活动。不过您也可以考虑其他因素如景点、美食等来做最终决定。
        thought: 对比两个城市天气后，成都天气更好，但也要提醒用户考虑其他旅游因素

🚀 实战演练

步骤1：环境准备

# 1. 进入示例目录
cd /path/to/cota/bots/weather

# 2. 配置API密钥
vim endpoints.yml
# 将your_api_key_here替换为实际的API密钥

# 3. 启动调试模式
cota shell --debug

步骤2：基础对话测试

用户输入: 你好
预期回复: 你好，请问有什么可以帮您？

用户输入: 我想查天气
预期回复: 好的，我可以帮您查询天气。请告诉我您想查询哪个城市的天气？

步骤3：复杂场景测试

用户输入: 帮我查下杭州和上海的天气，我看下去哪里旅游
系统行为: 
1. Selector识别需要查询两个城市天气
2. 先查询杭州天气
3. 再查询上海天气  
4. 对比结果并给出建议

📊 思维链可视化

每一步决策都包含完整的推理过程：

{
  "action": "Selector",
  "thought": "用户请求查询杭州和上海的天气以帮助决定旅游目的地，这类似于决策参考模式中的复杂查天气示例，其中用户询问多个城市天气并做比较。Weather工具只支持单个城市查询，因此需要先查询上海的天气。",
  "result": "Weather"
}

这种透明的推理过程确保了：

  • 可解释性: 每个决策都有明确理由
  • 可调试性: 便于发现和修复逻辑问题
  • 可优化性: 基于推理过程持续改进

🎯 最佳实践总结

1. 配置策略

  • 渐进式配置: 从简单trigger开始，逐步添加match策略
  • 思维链标注: 提供高质量的推理过程示例
  • 错误处理: 配置合适的fallback机制

2. 提示词工程

  • 结构化输出: 统一JSON格式确保解析稳定
  • 上下文管理: 合理使用{{history_actions_with_thoughts}}
  • 角色定义: 清晰的系统描述和动作描述

3. 调试技巧

  • 调试模式: 使用--debug查看完整推理过程
  • 分步测试: 从简单对话到复杂场景逐步验证
  • 日志分析: 关注thought字段定位问题

4. 生产部署

  • API密钥管理: 使用环境变量保护敏感信息
  • 持久化存储: 配置Redis和数据库确保状态持久化
  • 监控告警: 设置appropriate的监控和日志

通过这个实践，您已经掌握了COTA框架的核心能力。接下来可以尝试实践2，学习更高级的代理模式功能。

实践2：代理模式的数据生成与自动化测试

学习目标：掌握COTA框架的代理模式(Proxy User Mode)和自动化对话生成技术

这个实践将基于pet bot示例，展示如何使用COTA的代理模式进行大规模数据生成、系统测试和产品演示。

📋 项目概览

核心功能

  • 🤖 自动化对话: 无需人工干预，系统自动生成完整对话
  • 📊 数据生成: 批量生成高质量训练数据
  • 🧪 系统测试: 自动化测试对话系统的各个分支
  • 🎭 产品演示: 为客户展示完整的业务流程

技术特色

  • 双角色模拟: UserUtter模拟用户，BotUtter作为专业助手
  • 智能对话控制: 自动判断对话是否应该继续或结束
  • 场景化生成: 根据业务场景生成特定类型的对话数据

🏗️ 项目结构

pet/
├── agent.yml          # 代理模式配置和双角色定义
├── endpoints.yml       # LLM配置（支持RAG增强）
└── policy/
    ├── data.yml       # 宠物问诊场景标注数据
    └── rules.yml      # 快速响应规则

⚙️ 代理模式配置详解

1. 核心配置 (agent.yml)

启用代理模式

dialogue:
  use_proxy_user: true   # 🔑 核心配置：启用代理模式
  max_proxy_step: 50     # 最大对话轮次
  max_tokens: 800        # 较大token限制支持复杂对话

系统角色定义

system:
  description: 你是一个专业的宠物疾病问诊助手，擅长收集宠物症状信息并提供初步的诊断建议

2. 双角色动作设计

UserUtter - 宠物主人模拟器

UserUtter:
  description: '用户向医生的提问'
  prompt: |
    你是一个关心宠物健康的宠物主人，正在与专业的宠物医生对话咨询。
    请根据历史对话内容，以宠物主人的身份和口吻提出下一个合理的问题或回应。

    **角色设定：**
    - 你是一个关心宠物健康的宠物主人
    - 你可能需要咨询宠物的症状、疾病、护理等问题
    - 你会像真实的宠物主人一样自然地交流，包括描述症状、表达担忧等
    - 你希望得到专业的医疗建议

    **任务要求：**
    1. 根据对话历史，判断当前咨询进展
    2. 如果咨询刚开始或需要继续，提出关于宠物健康的问题
    3. 如果已经得到满意的医疗建议，可以表示感谢并结束咨询
    4. 保持宠物主人的自然对话风格，真实表达关切

    **输出格式（严格按照JSON格式）：**
    ```json
    {
      "thought": "你的内心想法和推理过程，分析当前咨询状态和下一步应该说什么",
      "text": "你作为宠物主人要说的话，自然、真实的表达",
      "state": "continue/stop - continue表示咨询继续，stop表示咨询可以结束"
    }
    ```

BotUtter - 专业问诊助手

BotUtter:
  description: '回复用户的提问'
  prompt: |
    你是一名专业的宠物医生，需要根据当前对话历史生成合适的医疗建议回复。

    **输出格式要求：**
    你必须严格按照以下JSON格式响应：
    ```json
    {"thought": "<你的推理过程>", "text": "<你的回复内容>"}
    ```

    **=============== 实际对话历史 ===============**
    （以下是真实的对话历史，请基于此内容生成回复）
    {{history_actions}}
    **============== 实际对话历史结束 ==============**

    请分析上述实际对话历史，参考学习资料中的思维模式，
    生成专业的医疗建议并输出JSON格式回复：

3. 增强LLM配置 (endpoints.yml)

llms:
  deepseek: # 基础模型
    type: openai
    model: deepseek-chat
    key: your_api_key_here
    apibase: https://api.deepseek.com/v1

  # RAG增强配置示例（可选）
  rag-glm-4:
    type: openai-rag
    model: glm-4
    key: your_glm4_api_key
    apibase: https://open.bigmodel.cn/api/paas/v4/
    knowledge_id: your_knowledge_id
    rag_prompt: |
      从宠物疾病文档中找到问题的答案，找到答案就仅使用文档语句回答问题，
      找不到答案就用自身宠物医疗知识回答并且告诉用户该信息不是来自专业文档，建议咨询兽医。

🤖 自动对话生成机制

对话控制流程

  1. 启动阶段: 系统自动生成第一个用户消息
  2. 对话循环:
    • UserUtter生成宠物主人的问题/回应
    • BotUtter提供专业的医疗建议
    • 系统判断对话是否应该继续
  3. 结束条件: UserUtter返回"state": "stop"时自动结束

智能状态控制

// UserUtter的智能判断逻辑
{
  "thought": "医生已经给出了详细的建议和注意事项，我作为宠物主人已经得到了满意的回复，应该表示感谢并结束咨询",
  "text": "好的医生，我明白了，非常感谢您的详细解答！我会按您说的方法处理，如果情况没有改善会及时带它去医院检查的。",
  "state": "stop"
}

🚀 实战演练

步骤1：启动代理模式

# 1. 进入pet bot目录
cd /path/to/cota/bots/pet

# 2. 配置API密钥
vim endpoints.yml

# 3. 启动代理模式
cota shell --debug

步骤2：观察自动对话生成

启动后，系统会自动进行如下对话：

🤖 [代理用户] 医生您好，我家的狗狗最近不太爱吃东西，精神也不如以前好，请问这可能是什么原因？

👨‍⚕️ [问诊助手] 您好！狗狗出现食欲不振和精神状态差的情况确实需要关注。为了更好地帮助您，我需要了解一些详细信息：您的狗狗多大了？什么品种？这种情况持续多长时间了？还有其他症状吗？

🤖 [代理用户] 它是一只2岁的金毛，大概30公斤重。不爱吃东西已经有3天了，以前很活泼，现在总是趴着不愿意动，也没有呕吐或者腹泻的情况。

👨‍⚕️ [问诊助手] 根据您描述的情况，2岁金毛正值壮年，突然出现食欲不振和精神萎靡需要重视。可能的原因包括：1) 消化系统问题 2) 感染性疾病 3) 环境应激 4) 口腔问题。建议先检查口腔是否有异常，确保饮水正常。

🤖 [代理用户] 那我需要带它去医院检查吗？需要注意什么？

👨‍⚕️ [问诊助手] 建议您先观察24-48小时，期间注意：1) 确保充足饮水 2) 提供易消化食物 3) 观察体温和排便情况。如果出现呕吐、腹泻、高热或持续拒食，需要立即就医。必要时可以做血常规和生化检查。

🤖 [代理用户] 好的，我明白了，非常感谢医生的建议！我会按您说的方法先观察，如果情况没有改善会及时带它去医院的。

👨‍⚕️ [问诊助手] 不客气！您作为负责任的宠物主人做得很好。请密切观察狗狗的情况，有任何疑问随时咨询。祝您的金毛早日恢复健康！

步骤3：批量数据生成

# 生成多轮对话数据
for i in {1..10}
do
  echo "生成第 $i 轮对话..."
  cota shell --config . --auto-exit
  sleep 2
done

📊 应用场景详解

1. 训练数据生成

优势:

  • 规模化: 快速生成千万级对话数据
  • 多样化: 覆盖各种宠物疾病场景
  • 标准化: 统一的数据格式和质量

数据质量示例:

{
  "dialogue_id": "pet_consult_001",
  "turns": [
    {
      "role": "user",
      "text": "医生您好，我家猫咪最近总是呕吐...",
      "thought": "刚开始咨询，需要描述主要症状"
    },
    {
      "role": "assistant", 
      "text": "您好！猫咪呕吐确实需要关注...",
      "thought": "需要收集更多症状信息进行判断"
    }
  ],
  "metadata": {
    "pet_type": "cat",
    "symptoms": ["vomiting"],
    "consultation_result": "completed"
  }
}

2. 系统压力测试

测试维度:

  • 并发性能: 同时运行多个代理对话测试系统负载
  • 稳定性: 长时间运行验证内存泄漏等问题
  • 边界情况: 自动触发各种异常场景
# 压力测试脚本
#!/bin/bash
for i in {1..50}
do
  {
    cota shell --config ./pet --session-id "test_$i" &
  }
done
wait

3. 产品演示

演示价值:

  • 完整流程: 展示从问诊到建议的完整业务流程
  • 专业性: 体现AI在专业领域的应用能力
  • 交互性: 实时展示AI的思考和决策过程

🎯 高级技巧

1. 场景定制

通过修改UserUtter的prompt来生成特定场景的数据:

# 针对紧急情况的场景配置
UserUtter:
  prompt: |
    你是一个遇到宠物紧急情况的主人，情况比较严重，语气要体现出焦急和担心。
    常见的紧急情况包括：误食异物、严重外伤、呼吸困难、意识不清等。

2. 质量控制

# 在BotUtter中添加质量检查
BotUtter:
  prompt: |
    你必须确保回复的专业性和安全性：
    1. 不能给出确定性诊断，只能提供建议
    2. 严重情况必须建议立即就医
    3. 回复要包含具体的观察指标和注意事项

3. 数据后处理

# 对话数据清洗和标注脚本
import json

def process_dialogue(dialogue_data):
    # 提取关键信息
    symptoms = extract_symptoms(dialogue_data)
    pet_info = extract_pet_info(dialogue_data)
    advice = extract_medical_advice(dialogue_data)
    
    # 数据质量评估
    quality_score = evaluate_dialogue_quality(dialogue_data)
    
    return {
        "dialogue": dialogue_data,
        "extracted_info": {
            "symptoms": symptoms,
            "pet_info": pet_info,
            "advice": advice
        },
        "quality_score": quality_score
    }

📈 与传统方法对比

对比维度传统人工标注COTA代理模式
数据规模百条级别万条级别
标注时间数月数小时
一致性人工差异大高度一致
成本高人力成本低算力成本
场景覆盖有限全面
迭代速度缓慢快速

🎯 最佳实践总结

1. 配置优化

  • 角色清晰: 明确定义UserUtter和BotUtter的角色职责
  • 状态控制: 合理设置max_proxy_step防止无限循环
  • 提示词工程: 针对业务场景优化提示词

2. 数据管理

  • 结构化存储: 使用JSON格式确保数据结构一致性
  • 版本控制: 对生成的数据集进行版本管理
  • 质量监控: 定期评估生成数据的质量和多样性

3. 系统集成

  • API封装: 将代理模式封装为API服务
  • 监控告警: 设置生成过程的监控和异常处理
  • 资源管理: 合理分配计算资源避免过载

4. 扩展应用

  • 多领域适配: 将此模式扩展到其他专业领域
  • 多语言支持: 生成多语言对话数据
  • 个性化定制: 根据不同用户群体定制对话风格

通过掌握代理模式，您不仅能够高效生成训练数据，还能够建立完整的自动化测试和演示系统，大大提升AI产品的开发和部署效率。

配置说明总览

COTA框架使用YAML格式的配置文件来定义智能体的行为、策略和外部服务连接。一个完整的COTA机器人配置包含以下几个核心部分。

📁 配置文件结构

bot/                    # 机器人项目目录
├── agent.yml               # 智能体配置文件（核心）
├── endpoints.yml            # 端点配置文件（连接配置）
└── policy/                  # 策略配置目录
    ├── data.yml            # 策略数据文件
    └── rules.yml           # 触发规则文件

🔧 核心配置组件

1. Agent配置 (agent.yml)

定义智能体的基本信息、对话模式、策略和动作。

主要配置项：

  • system: 智能体基本信息
  • dialogue: 对话模式和参数
  • policies: 对话策略配置
  • actions: 动作定义和提示词
  • knowledge: 知识库配置（RAG功能）

2. Endpoints配置 (endpoints.yml)

配置外部服务连接，包括数据库、缓存、LLM等。

主要配置项：

  • base_store: 数据存储配置
  • channel: 通道缓存配置
  • llms: 大语言模型配置

3. Policy配置 (policy/data.yml)

定义对话策略和示例，用于训练智能体的对话模式。

主要配置项：

  • policies: 策略示例列表
  • 每个策略包含完整的对话流程示例

4. Trigger配置 (policy/rules.yml)

定义触发规则，当用户输入匹配特定模式时自动执行相应动作。

主要配置项：

  • triggers: 触发规则列表
  • 每个规则包含触发条件和执行动作

🔗 相关配置

核心配置文件

  • agent.yml: 智能体核心配置，定义系统描述、对话参数、策略和动作
  • endpoints.yml: 外部服务配置，包括LLM、数据库和缓存连接
  • policy/data.yml: 策略示例数据，用于match类型的策略学习
  • policy/rules.yml: 触发规则配置，定义特定条件下的自动响应

配置建议

通过合理的配置，你可以创建功能强大、响应准确的COTA智能体：

  1. 从简单开始: 使用基础的trigger策略，逐步添加高级功能
  2. RAG增强: 通过knowledge配置集成知识库，提升回答准确性
  3. 策略组合: 结合trigger和match策略，平衡响应速度和智能程度，通过llm DPL结合知识库持续优化DPL能力
  4. 生产优化: 配置持久化存储和缓存，确保系统稳定性

Agent配置详解

Agent配置文件(agent.yml)是COTA智能体的核心配置文件，定义了智能体的身份、对话策略、知识管理和动作能力。它是智能体的“大脑“，决定了智能体如何思考、决策和响应用户。

🎯 Agent配置的作用与角色

核心作用：

  • 身份定义：通过system配置智能体的角色和性格
  • 对话控制：通过dialogue控制对话流程和参数
  • 策略管理：通过policies定义智能体的思维和决策模式
  • 知识整合：通过knowledge配置知识来源和检索策略
  • 能力扩展：通过actions定义智能体可执行的具体动作

在COTA架构中的角色：

  • 被Agent类加载并解析为智能体实例
  • 与endpoints.yml协同工作，前者定义能力，后者提供服务连接
  • 通过Processor类驱动整体对话流程

📋 配置项总览

system:      # 智能体身份 - 定义角色和基本信息
dialogue:    # 对话控制 - 控制对话模式和参数限制  
policies:    # 决策策略 - 定义思维模式和决策逻辑
knowledge:   # 知识管理 - 配置知识来源和检索策略
actions:     # 动作定义 - 定义智能体的具体能力和行为
配置项对应模块核心作用
systemAgent类初始化设定智能体身份和描述
dialogueProcessor对话处理控制对话流程和限制
policiesDPL策略学习驱动智能体思考和决策
knowledgeKnowledge知识管理提供外部知识支持
actionsAction系统定义智能体的具体行为

🔧 详细配置说明

1. System配置 - 智能体身份

作用：定义智能体的基本身份信息，影响所有后续交互的语调和行为风格。

system:
  description: "你是一个智能助手，你需要认真负责的回答帮用户解决问题"
  name: "assistant"  # 可选

配置参数：

参数必需默认值说明
description✅-智能体角色描述，作为系统提示词的基础
name❌“agent”智能体名称，用于日志和多Agent场景

2. Dialogue配置 - 对话控制

作用：控制对话的基本参数和流程限制，对应Processor类的对话处理逻辑。

dialogue:
  use_proxy_user: false   # 是否启用代理用户模式
  max_proxy_step: 20      # 代理模式下的最大步骤数
  max_tokens: 500         # LLM生成最大令牌数

配置参数：

参数必需默认值说明
use_proxy_user❌false是否启用代理用户功能，用于自动化模拟用户交互
max_proxy_step❌20代理模式下的最大对话步数，防止无限循环
max_tokens❌500LLM生成的最大令牌数，控制回复长度

3. Policies配置 - 决策策略

作用：配置智能体的思维模式和决策策略，对应COTA的DPL(Dialogue Policy Learning)系统。

policies:
  - type: trigger    # 触发式策略，基于规则快速响应
  - type: match      # 匹配策略，基于标注数据进行思维链学习
  - type: llm        # LLM策略，基于大模型推理 (三种策略中的一个或过个)
    config:
      llms:                   # LLM配置列表
        - name: rag-glm-4    # 默认LLM
        - name: rag-utter    # BotUtter动作专用LLM
          action: BotUtter
        - name: rag-selector  # Selector动作专用LLM
          action: Selector

策略类型说明：

策略类型对应类作用机制
triggerTriggerDPL基于policy/rules.yml中定义的触发规则进行快速响应
matchMatchDPL基于policy/data.yml中的标注数据学习思维链推理过程
llmLLMDPL基于大模型推理，支持动作级别的LLM绑定配置

配置说明：

  • trigger策略：适用于简单、确定性的对话场景，响应速度快
  • match策略：适用于复杂推理场景，通过学习标注数据生成思维链
  • llm策略：基于大模型推理，支持为不同动作配置专用LLM
  • 策略组合：可以同时配置多种策略，系统会根据场景选择合适的策略

4. Knowledge配置 - 知识管理（可选）

作用：配置智能体的知识来源和检索策略，对应Knowledge和KnowledgeFactory类。主要用于RAG（检索增强生成）功能。

knowledge:
  - type: llm                 # LLM类型知识源
    config:
      llms: 
        - name: rag-glm-4    # 知识检索使用的LLM
          action: BotUtter   # 绑定到BotUtter动作
        - name: rag-glm-4
          action: Selector   # 绑定到Selector动作
        - name: rag-glm-4    # 默认知识LLM

知识配置参数：

参数说明
type知识源类型，当前支持“llm“
config.llms知识检索使用的LLM配置列表

5. Actions配置 - 动作定义

作用：定义智能体可执行的具体动作，每个动作对应一个Action类或其子类。

5.1 基础动作

UserUtter - 用户输入处理

UserUtter:
  description: "用户的action - 用户向智能体提问"
  prompt: |
    历史对话:
    {{history_messages}}
    请输出对医生说的话
    
  breaker:  # 对话中断判断器
    description: "判断是否跳出"
    prompt: |
      根据对话内容，判断对话是否满足要求
      对话内容: {{history_messages}}
      如果对话完整且可以结束, 输出标识符true。
      如果对话还需要继续, 输出标识符false。
      输出格式为: <标识符>

BotUtter - 智能体回复

BotUtter:
  description: "回复用户"
  prompt: |
    你是一个智能助手，需要根据当前对话历史生成合适的回复。
    
    **任务描述：** {{task_description}}
    **输出格式要求：**
    你必须严格按照以下JSON格式响应，不要有任何其他内容：
    ```json
    {"thought": "<你的推理过程>", "text": "<你的回复内容>"}
    ```
    
    **学习参考资料：** {{policies}}
    **实际对话历史：** {{history_actions}}
    
    请分析上述实际对话历史，参考学习资料中的思维模式，生成合适的JSON格式回复：

Selector - 动作选择器

Selector:
  description: "选择合适的Actions"
  prompt: |
    你是一个智能对话助手，需要根据当前对话状态选择下一个最合适的Action。
    
    **输出格式要求：**
    ```json
    {"thought": "<你的推理过程>", "action": "<工具名称>"}
    ```
    
    **可用的Action工具：** {{action_descriptions}}
    **决策参考模式：** {{policies}}
    **当前对话状态：** {{history_actions}}
    
    请分析当前对话状态，参考决策模式，选择最合适的下一个Action并输出JSON格式结果：

5.2 Form动作 - 表单处理

作用：Form动作用于收集用户信息并执行外部API调用，对应Form类。

核心组件：

  • prompt: 统一处理槽位更新和结果返回的主要提示词
  • slots: 需要收集的信息槽位定义
  • executer: 外部服务执行器

配置示例：

Weather:  # 天气查询Form动作
  description: "查询天气"
  prompt: |
    当前正在执行{{current_form_name}}，其描述为{{current_form_description}}。
    根据对话内容及Action序列，结合当前slot的状态，填充或重置slot的值。
    
    历史Action序列为:
    {{history_actions_with_thoughts}}
    
    Action的描述为:
    {{action_descriptions}}
    
    当前slots为:
    {{current_form_slot_states}}
    
    slots的含义为:
    {{current_form_slot_descriptions}}
    
    填充或重置slot的值，保持slots格式输出json字符串。

  slots:  # 槽位定义
    city:
      description: "城市，注意：接口只支持输入单个城市"
      prompt: |
        当前正在执行Action {{current_form_name}}, 其描述为 {{current_form_description}}。
        接下来需要询问用户，需要查询哪个城市的天气。
        
        你必须严格按照以下JSON格式响应：
        {"text": "<你的回复内容>"}

    time:
      description: "时间"
      prompt: |
        当前正在执行Action {{current_form_name}}, 其描述为 {{current_form_description}}。
        接下来需要询问用户，需要查询哪天的天气。

        你必须严格按照以下JSON格式响应：
        {"text": "<你的回复内容>"}

  executer:  # 执行器配置
    url: http://rap2api.taobao.org/app/mock/319677/Weather
    method: GET      # HTTP方法，可选GET、POST等
    output: ["<text>", "接口异常"]  # 预期输出格式
    mock: false      # 是否使用模拟数据

Form动作工作流程：

  1. 槽位收集：依次询问用户填充slots中定义的信息
  2. 状态更新：通过主prompt智能解析用户输入并更新槽位状态
  3. 完整性检查：当所有必需槽位填充完成后，进入执行阶段
  4. 外部调用：通过executer调用外部API获取结果
  5. 结果返回：返回执行结果给用户

为什么要这样配置：

  • prompt: 统一处理槽位更新逻辑，简化配置结构
  • slots: 结构化收集用户信息，避免信息遗漏
  • executer: 标准化外部服务调用，支持HTTP、模拟等多种方式

配了可以做什么：

  • 实现结构化信息收集（如订单、预约、查询等）
  • 集成外部API服务（天气、计算、数据库等）
  • 提供交互式任务执行能力

5.3 模板变量

所有Action的prompt支持丰富的模板变量：

变量名说明适用动作
{{task_description}}任务描述所有动作
{{history_messages}}历史消息列表UserUtter
{{history_actions_with_thoughts}}带思维链的历史动作序列BotUtter, Selector
{{policies}}策略思维链参考（来自policy/data.yml）BotUtter, Selector
{{action_descriptions}}可用动作描述Selector
{{current_form_name}}当前表单名称Form动作
{{current_form_description}}当前表单描述Form动作
{{current_form_slot_states}}当前槽位状态Form动作
{{current_form_slot_descriptions}}槽位描述信息Form动作
{{current_form_execute_result}}执行结果Form动作执行后
{{knowledge}}知识库检索结果BotUtter（当配置knowledge时）

重要说明：

  • history_actions_with_thoughts 包含完整的动作历史和思维过程，是推理的重要依据
  • policies 变量提供标注数据作为思维链学习的参考模式

📚 推荐配置示例

1. 简单问答助手

system:
  description: "你是一个智能问答助手，提供准确、有用的回答"

dialogue:
  use_proxy_user: false
  max_proxy_step: 20
  max_tokens: 300

policies:
  - type: trigger
  - type: match

actions:
  BotUtter:
    description: "回复用户"
    prompt: |
      你是一个智能助手，需要根据当前对话历史生成合适的回复。
      
      **任务描述：**
      {{task_description}}
      
      **输出格式要求：**
      ```json
      {"thought": "<你的推理过程>", "text": "<你的回复内容>"}
      ```
      
      **学习参考资料：**
      {{policies}}
      
      **实际对话历史：**
      {{history_actions_with_thoughts}}
      
  Selector:
    description: "选择动作"
    prompt: |
      你是一个智能对话助手，需要根据当前对话状态选择下一个最合适的Action。
      
      **输出格式要求：**
      ```json
      {"thought": "<你的推理过程>", "action": "<工具名称>"}
      ```
      
      **可用的Action工具：**
      {{action_descriptions}}
      
      **当前对话状态：**
      {{history_actions_with_thoughts}}

2. 带知识检索的客服助手

system:
  description: "你是专业的客服助手，基于知识库提供准确服务"

dialogue:
  use_proxy_user: false
  max_proxy_step: 30
  max_tokens: 500

policies:
  - type: trigger
  - type: match

knowledge:
  - type: llm
    config:
      llms:
        - name: rag-glm-4
          action: BotUtter
        - name: rag-glm-4
          action: Selector
        - name: rag-glm-4  # 默认知识检索LLM

actions:
  BotUtter:
    description: "客服回复"
    prompt: |
      你是专业客服，需要提供准确、友好的服务。
      
      **任务描述：**
      {{task_description}}
      
      **输出格式要求：**
      ```json
      {"thought": "<你的分析过程>", "text": "<你的回复内容>"}
      ```
      
      **知识库信息：**
      {{knowledge}}
      
      **学习参考资料：**
      {{policies}}
      
      **实际对话历史：**
      {{history_actions_with_thoughts}}
      
  Selector:
    description: "动作选择器"
    prompt: |
      根据用户需求和知识库信息选择合适的响应动作。
      
      **可用动作：**
      {{action_descriptions}}
      
      **当前对话状态：**
      {{history_actions_with_thoughts}}
      
      **输出格式：**
      ```json
      {"thought": "<分析过程>", "action": "<动作名称>"}
      ```

3. 代理模式助手（自动化对话）

system:
  description: "你是一个专业的宠物疾病问诊助手，擅长收集宠物症状信息并提供初步的诊断建议"

dialogue:
  use_proxy_user: true    # 启用代理模式
  max_proxy_step: 30
  max_tokens: 800

policies:
  - type: trigger
  - type: match

actions:
  UserUtter:              # 代理模式下必须配置UserUtter
    description: "用户的action - 宠物主人向问诊助手咨询宠物疾病"
    prompt: |
      你是一个关心宠物健康的主人，你的宠物可能出现了一些健康问题，你想要咨询专业的宠物问诊助手。
      
      **角色设定：**
      - 你是一个关心宠物的主人
      - 你会描述宠物的症状、行为变化等
      - 当得到满意的建议时，你会表示感谢并结束对话
      
      **历史对话：**
      {{history_messages}}
      
      **输出格式（严格按照JSON格式）：**
      ```json
      {
        "thought": "你的内心想法和推理过程",
        "text": "你作为宠物主人要说的话",
        "state": "continue/stop"
      }
      ```
      
  BotUtter:
    description: "专业宠物问诊助手回复用户"
    prompt: |
      你是一个专业的宠物疾病问诊助手，需要根据当前对话历史生成合适的回复。
      
      **输出格式要求：**
      ```json
      {"thought": "<你的推理过程>", "text": "<你的回复内容>"}
      ```
      
      **学习参考资料：**
      {{policies}}
      
      **实际对话历史：**
      {{history_actions_with_thoughts}}
      
  Selector:
    description: "选择合适的Actions"
    prompt: |
      你是一个专业的宠物问诊助手，需要根据当前对话状态选择下一个最合适的Action。
      
      **输出格式要求：**
      ```json
      {"thought": "<你的推理过程>", "action": "<工具名称>"}
      ```
      
      **可用的Action工具：**
      {{action_descriptions}}
      
      **当前对话状态：**
      {{history_actions_with_thoughts}}

通过合理配置Agent，可以创建功能强大、响应准确的COTA智能体。建议从简单配置开始，逐步增加复杂功能和Form动作。

Endpoints配置详解

Endpoints配置文件(endpoints.yml)定义了COTA智能体的核心组件连接配置，负责数据存储、通道缓存和大语言模型的统一管理。

📋 配置结构

base_store:      # 对话数据存储
channel:         # 会话状态缓存  
llms:           # 大语言模型服务

🗄️ 数据存储配置 (base_store)

作用：管理对话历史和会话数据的持久化存储，由Store类实现。

内存存储 (MemoryStore)

base_store:
  type: Memory
  • 用途：开发测试环境，数据存储在进程内存中
  • 特点：快速响应，进程重启后数据丢失

SQL数据库存储 (SQLStore)

base_store:
  type: SQL
  dialect: mysql+pymysql    # 数据库驱动
  host: localhost           # 数据库地址
  port: 3306               # 端口
  db: chatbot_db           # 数据库名
  username: ${DB_USER}     # 用户名
  password: ${DB_PASS}     # 密码
  query: {}                # 连接参数(可选)

配置参数：

参数必需默认值说明
type✅-存储类型：Memory/SQL
dialect✅(SQL)mysql+pymysqlSQLAlchemy方言
host✅(SQL)127.0.0.1数据库主机
port❌3306数据库端口
db✅(SQL)mysql数据库名
username✅(SQL)root用户名
password✅(SQL)-密码
query❌{}额外连接参数

支持的数据库：

  • MySQL: mysql+pymysql
  • PostgreSQL: postgresql+psycopg2
  • SQLite: sqlite:///path/to/db

🔄 通道缓存配置 (channel)

作用：管理会话状态的临时缓存，支持分布式部署。

channel:
  type: redis
  host: localhost
  port: 6379
  db: 0
  password: ${REDIS_PASS}   # 可选

配置参数：

参数必需默认值说明
type✅-缓存类型(当前仅支持redis)
host✅localhostRedis主机
port❌6379Redis端口
db❌0Redis数据库号
password❌-Redis密码

🤖 大语言模型配置 (llms)

作用：配置智能体使用的大语言模型服务，通过LLMClientFactory创建客户端实例。

配置格式

llms:
  model_name:              # 模型标识符
    type: openai          # 客户端类型
    model: actual_name    # 实际模型名
    key: ${API_KEY}       # API密钥
    apibase: https://...  # API地址

支持的客户端类型

1. OpenAI兼容客户端 (OpenAIClient)

llms:
  qwen-max:
    type: openai
    model: qwen-max
    key: ${QWEN_KEY}
    apibase: https://dashscope.aliyuncs.com/compatible-mode/v1
  • 用途：标准OpenAI API调用，支持工具调用
  • 实现：OpenAIClient类

2. RAG增强客户端 (OpenAIRAGClient)

llms:
  rag-glm-4:
    type: openai-rag
    model: glm-4
    key: ${GLM_KEY}
    apibase: https://open.bigmodel.cn/api/paas/v4/
    knowledge_id: "123456"           # 知识库ID
    rag_prompt: "从文档{{knowledge}}中找问题{{question}}的答案"  # RAG提示模板
  • 用途：自动添加知识检索功能
  • 实现：OpenAIRAGClient类，自动注入检索工具

3. 自定义HTTP客户端 (CustomHttpClient)

llms:
  custom-model:
    type: custom
    model: custom-llm
    key: ${CUSTOM_KEY}
    apibase: https://your-api.com/chat
    # 所有额外参数都会传递给HTTP接口
    knowledge_id: "kb123"
    user_id: "user456"
    custom_param: "value"
  • 用途：支持任意HTTP API，所有配置参数都传递给接口
  • 实现：CustomHttpClient类，最大灵活性

通用配置参数

参数必需说明
type✅客户端类型：openai/openai-rag/custom
model✅模型名称
key✅API密钥
apibase✅API基础URL
knowledge_id❌知识库ID(仅RAG/custom类型)
rag_prompt❌RAG提示模板(仅RAG类型)

常用模型配置示例

DeepSeek:

deepseek-chat:
  type: openai
  model: deepseek-chat
  key: ${DEEPSEEK_KEY}
  apibase: https://api.deepseek.com/v1

通义千问:

qwen-max:
  type: openai
  model: qwen-max
  key: ${QWEN_KEY}
  apibase: https://dashscope.aliyuncs.com/compatible-mode/v1

ChatGLM RAG:

rag-glm-4:
  type: openai-rag
  model: glm-4
  key: ${GLM_KEY}
  apibase: https://open.bigmodel.cn/api/paas/v4/
  knowledge_id: "1853628378662457344"
  rag_prompt: |
    从文档'''{{knowledge}}'''中找问题'''{{question}}'''的答案，
    找到答案就仅使用文档语句回答，找不到答案就用自身知识回答并告知用户。

🔐 环境变量配置

推荐所有敏感信息使用环境变量：

# .env文件
QWEN_KEY=sk-your-qwen-key
DEEPSEEK_KEY=sk-your-deepseek-key
GLM_KEY=your-glm-key.suffix
DB_USER=chatbot_user
DB_PASS=secure_password
REDIS_PASS=redis_secret

📋 配置模板

开发环境

base_store:
  type: Memory

channel:
  type: redis
  host: localhost
  port: 6379

llms:
  qwen-max:
    type: openai
    model: qwen-max
    key: ${QWEN_KEY}
    apibase: https://dashscope.aliyuncs.com/compatible-mode/v1

生产环境

base_store:
  type: SQL
  dialect: mysql+pymysql
  host: ${DB_HOST}
  db: ${DB_NAME}
  username: ${DB_USER}
  password: ${DB_PASS}

channel:
  type: redis
  host: ${REDIS_HOST}
  password: ${REDIS_PASS}

llms:
  qwen-max:
    type: openai
    model: qwen-max
    key: ${QWEN_KEY}
    apibase: https://dashscope.aliyuncs.com/compatible-mode/v1
    
  rag-glm-4:
    type: openai-rag
    model: glm-4
    key: ${GLM_KEY}
    apibase: https://open.bigmodel.cn/api/paas/v4/
    knowledge_id: ${KNOWLEDGE_ID}

标注数据配置详解

标注数据是COTA智能体的“学习材料“，通过提供带思维链的对话示例和触发规则，训练智能体学习对话策略、决策模式和自动响应机制。这些数据直接影响智能体的表现质量和交互能力。

🎯 标注数据的作用与价值

核心价值：

  • 策略学习：通过完整对话流程示例，让智能体学习复杂的对话处理策略
  • 思维训练：通过思维链标注，训练智能体的推理和决策能力
  • 快速响应：通过触发规则，实现对特定输入的即时准确响应
  • 质量保证：通过精心设计的标注数据，确保智能体输出的一致性和准确性

对COTA运行的影响：

  • DPL策略生成：DPL系统根据标注数据生成思维链和动作预测
  • 触发匹配：TriggerDPL基于触发规则进行快速模式匹配
  • 响应质量：标注数据的质量直接决定智能体的回答质量
  • 行为一致性：规范化的标注确保智能体行为的可预测性

📁 配置文件位置

标注数据配置位于机器人项目的policy/目录下：

your_bot/                    # 机器人项目根目录
├── agent.yml              # 智能体配置
├── endpoints.yml           # 服务连接配置
└── policy/                 # 标注数据目录 ⭐
    ├── data.yml           # 对话策略数据（Policy配置）
    ├── rules.yml          # 触发规则数据（Trigger配置）  
    └── *.md               # RAG知识库文件（可选）

加载机制：

  • Agent.load_from_path()方法会自动扫描policy/目录
  • DPLFactory.create()负责加载和解析标注数据
  • MatchDPL和TriggerDPL分别处理策略数据和触发规则

📋 配置项概览

配置文件对应组件主要作用数据格式
policy/data.ymlMatchDPL对话策略学习，生成思维链完整对话流程+思考过程
policy/rules.ymlTriggerDPL快速触发响应，精确匹配关键词匹配+预定义动作

🧠 Policy配置 - 对话策略学习数据

作用：提供完整的对话流程示例，训练智能体的推理能力和对话策略。

配置结构

# policy/data.yml
policies:                    # 策略数据列表
  - title: "策略标题"        # 策略名称，用于识别
    actions:                 # 完整动作序列
      - name: UserUtter      # 用户输入动作
        result: "用户说的话"  # 用户输入内容
      - name: Selector       # 动作选择器  
        thought: "选择理由"   # 思维链：为什么选择这个动作
        result: BotUtter     # 选择的动作名
      - name: BotUtter       # 机器人回复动作
        thought: "回复思考"   # 思维链：如何生成回复
        result: "回复内容"    # 实际回复内容

Policy数据类型

1. 基础问答策略

policies:
  - title: "简单问答"
    actions:
      - name: UserUtter
        result: "你是谁？"
        
      - name: Selector
        thought: "用户询问身份，我应该简洁地介绍自己的角色和能力"
        result: BotUtter
        
      - name: BotUtter
        thought: "需要友好地介绍自己，让用户了解我能提供什么帮助"
        result: "我是智能助手，可以帮助您解答问题、查询信息和处理各种任务。"

2. 多轮对话策略

policies:
  - title: "天气查询多轮对话"
    actions:
      - name: UserUtter
        result: "今天天气怎么样？"
        
      - name: Selector
        thought: "用户询问天气，但没有指定城市，需要先获取位置信息"
        result: Weather
        
      - name: Weather  # Form动作第一次执行，询问缺失信息
        result: "请问您想查询哪个城市的天气？"
        
      - name: UserUtter
        result: "北京"
        
      - name: Weather  # Form动作第二次执行，返回查询结果
        result: "北京今天多云，气温18-25°C"
        
      - name: Selector
        thought: "已获取天气信息，需要以用户友好的方式告知结果"
        result: BotUtter
        
      - name: BotUtter
        thought: "整合天气信息，提供完整有用的回复"
        result: "北京今天多云，气温18-25°C，天气不错，适合出行！记得适当增减衣物。"

3. 复杂业务策略

policies:
  - title: "订单查询处理"
    actions:
      - name: UserUtter
        result: "我的订单什么时候到？"
        
      - name: Selector
        thought: "用户询问订单状态，但没提供订单号，需要先获取订单信息"
        result: OrderQuery
        
      - name: OrderQuery
        result: "请提供您的订单号，我来帮您查询配送状态"
        
      - name: UserUtter
        result: "订单号：202310151234"
        
      - name: OrderQuery  # 执行订单查询
        result: "订单202310151234正在配送中，预计明天下午送达"
        
      - name: Selector
        thought: "已获取订单信息，需要详细告知用户配送情况"
        result: BotUtter
        
      - name: BotUtter
        thought: "提供完整的订单状态信息，包括配送进度和预计时间"
        result: "您的订单202310151234正在配送中，预计明天下午送达。配送员会提前联系您，请保持手机畅通。"

Policy配置要点

思维链设计原则：

  • 具体化：描述具体的推理过程，而非简单的结论
  • 逻辑性：体现清晰的因果关系和决策依据
  • 一致性：保持思维模式的统一性
  • 实用性：贴近真实的对话处理场景

动作序列设计：

  • 完整性：从用户输入到最终回复的完整流程
  • 真实性：模拟真实的人机对话场景
  • 多样性：覆盖不同的对话模式和处理方式

⚡ Trigger配置 - 触发规则数据

作用：定义关键词触发规则，实现对特定输入的快速精确响应。

配置结构

# policy/rules.yml
triggers:                    # 触发规则列表
  - title: "规则标题"        # 触发规则名称
    actions:                 # 触发的动作序列
      - name: UserUtter      # 用户输入匹配
        result:              # 匹配的关键词列表
          - "关键词1"
          - "关键词2"
      - name: ActionName     # 触发执行的动作
        result: "预期结果"   # 预期的执行结果

Trigger规则类型

1. 服务转接类

triggers:
  - title: "转人工客服"
    actions:
      - name: UserUtter
        result:
          - "转人工"
          - "人工客服"
          - "真人服务"
          - "客服专员"
          - "manual service"
          - "human agent"
      - name: TransferToHuman
        result: "正在为您转接人工客服，请稍候..."

  - title: "技术支持转接"
    actions:
      - name: UserUtter
        result:
          - "技术支持"
          - "技术问题"
          - "bug反馈"
          - "系统故障"
          - "technical support"
      - name: TransferToTech
        result: "正在为您转接技术支持专家..."

2. 业务操作类

triggers:
  - title: "退款申请"
    actions:
      - name: UserUtter
        result:
          - "退款"
          - "退钱"
          - "申请退款"
          - "我要退款"
          - "refund"
      - name: RefundProcess
        result: "已为您启动退款流程，请稍后填写退款信息"

  - title: "订单查询"
    actions:
      - name: UserUtter
        result:
          - "查订单"
          - "订单状态"
          - "我的订单"
          - "订单查询"
          - "order status"
      - name: OrderQuery
        result: "请提供您的订单号，我来帮您查询"

3. 紧急处理类

triggers:
  - title: "紧急情况处理"
    actions:
      - name: UserUtter
        result:
          - "紧急"
          - "urgent"
          - "emergency"
          - "很急"
          - "马上处理"
      - name: UrgentHandler
        result: "已标记为紧急事件，将优先为您处理"

  - title: "投诉升级"
    actions:
      - name: UserUtter
        result:
          - "投诉"
          - "complaint"
          - "不满意"
          - "差评"
          - "要投诉"
      - name: ComplaintEscalation
        result: "您的意见很重要，已升级至客服主管处理"

Trigger配置要点

关键词选择原则：

  • 准确性：确保关键词能准确表达用户意图
  • 覆盖性：包含同义词、近义词和常见表达
  • 排他性：避免与其他规则产生冲突
  • 多语言：根据需要支持多语言关键词

匹配策略：

  • 精确匹配：用户输入完全等于关键词
  • 包含匹配：用户输入包含关键词
  • 优先级控制：通过规则顺序控制匹配优先级

🔄 Policy与Trigger协同工作

工作机制

  1. Trigger优先：系统首先检查是否有触发规则匹配
  2. Policy补充：未匹配触发规则时，使用Policy数据进行策略推理
  3. 思维融合：Policy的思维链为所有动作提供推理参考

数据协同设计

# policy/rules.yml - 快速响应
triggers:
  - title: "快速退款"
    actions:
      - name: UserUtter
        result: ["我要退款"]
      - name: RefundProcess
        result: "启动退款"

# policy/data.yml - 详细处理流程  
policies:
  - title: "退款详细流程"
    actions:
      - name: UserUtter
        result: "退款遇到问题怎么办？"
      - name: Selector
        thought: "用户在退款过程中遇到问题，需要提供详细的解决方案和后续流程指导"
        result: BotUtter
      - name: BotUtter
        thought: "提供全面的退款问题解决方案，包括常见问题和联系方式"
        result: "退款遇到问题时，您可以：1)检查银行卡信息是否正确 2)等待3-5个工作日 3)联系客服核实状态。如需进一步帮助，我可以为您转接专人处理。"

🎨 数据标注最佳实践

1. 分层数据设计

# 第一层：基础交互（高频场景）
policies:
  - title: "基础-问候"
  - title: "基础-告别"
  - title: "基础-感谢"

# 第二层：功能操作（核心业务）
policies:
  - title: "功能-天气查询"
  - title: "功能-订单查询"
  - title: "功能-信息修改"

# 第三层：复杂处理（异常情况）
policies:
  - title: "复杂-多条件查询"
  - title: "复杂-异常处理"
  - title: "复杂-升级转接"

2. 思维链质量标准

# ✅ 高质量思维链
- name: Selector
  thought: "用户询问天气但未指定城市和时间，我需要先收集这两个必要信息才能提供准确的天气预报。优先询问城市，因为这是最基本的查询条件。"
  result: Weather

# ❌ 低质量思维链  
- name: Selector
  thought: "选择天气"  # 过于简单，缺乏推理过程
  result: Weather

3. 数据覆盖策略

# 覆盖用户表达的多样性
policies:
  - title: "问候-正式场合"
    actions:
      - name: UserUtter
        result: "您好，请问能帮我..."
        
  - title: "问候-日常对话"  
    actions:
      - name: UserUtter
        result: "嗨，我想要..."
        
  - title: "问候-简短表达"
    actions:
      - name: UserUtter
        result: "你好"

📊 数据质量评估

质量指标

  • 完整性：动作序列是否完整，覆盖完整对话流程
  • 逻辑性：思维链是否具有清晰的推理逻辑
  • 一致性：相似场景的处理方式是否一致
  • 实用性：是否贴近真实使用场景

测试验证

# 在数据中添加测试用例
test_cases:
  - input: "我要退款"
    expected_trigger: "退款申请"
    expected_actions: ["UserUtter", "RefundProcess"]
    
  - input: "天气怎么样"
    expected_policy: "天气查询"
    expected_thought_quality: "high"  # 思维链质量要求

📚 完整配置示例

客服机器人数据配置

policy/data.yml:

policies:
  - title: "智能客服问候"
    actions:
      - name: UserUtter
        result: "你好，我需要帮助"
      - name: Selector
        thought: "用户寻求帮助，我应该热情地回应并了解具体需求"
        result: BotUtter
      - name: BotUtter
        thought: "作为客服助手，我需要表现出专业和友好，同时引导用户说明问题"
        result: "您好！我是智能客服助手，很高兴为您服务。请告诉我您遇到了什么问题，我会尽力帮助您解决。"

  - title: "订单状态查询"
    actions:
      - name: UserUtter
        result: "我的订单什么时候能到？"
      - name: Selector
        thought: "用户询问订单配送时间，但没有提供订单号，我需要先获取订单信息"
        result: OrderQuery
      - name: OrderQuery
        result: "请提供您的订单号，我来帮您查询具体的配送状态"
      - name: UserUtter
        result: "202310151234"
      - name: OrderQuery
        result: "订单202310151234预计明天下午送达，当前状态：运输中"
      - name: Selector
        thought: "已获取订单信息，需要完整地告知用户配送情况和注意事项"
        result: BotUtter
      - name: BotUtter
        thought: "提供详细的配送信息，让用户了解时间安排，并提醒相关注意事项"
        result: "您的订单202310151234预计明天下午送达，目前正在运输途中。配送员会在送达前30分钟联系您，请保持手机畅通哦！"

policy/rules.yml:

triggers:
  - title: "转人工客服"
    actions:
      - name: UserUtter
        result:
          - "转人工"
          - "人工客服"  
          - "真人服务"
          - "manual service"
      - name: TransferToHuman
        result: "正在为您转接人工客服，请稍候..."

  - title: "退款快速处理"
    actions:
      - name: UserUtter
        result:
          - "我要退款"
          - "申请退款"
          - "退款"
          - "refund"
      - name: RefundProcess
        result: "已为您启动退款流程"

  - title: "紧急情况"
    actions:
      - name: UserUtter
        result:
          - "紧急"
          - "urgent"
          - "很急"
          - "马上处理"
      - name: UrgentHandler
        result: "已标记为紧急事件，将优先处理"

通过精心设计的标注数据，COTA智能体能够学习到丰富的对话策略和处理模式，为用户提供更智能、更人性化的交互体验。建议从核心业务场景开始标注，逐步扩展覆盖面和复杂度。

Channel（通信通道）

在COTA框架中，Channel是一个关键组件，负责将Agent与外部通信平台或渠道连接起来，使得用户可以通过这些平台与智能体进行交互。Channel作为Agent与用户之间的桥梁，处理消息的接收、转换和发送。

🎯 核心功能

1. 消息传递

  • 接收用户输入: 从各种客户端接收用户消息
  • 协议转换: 将不同协议的消息转换为统一的Message格式
  • 响应分发: 将Agent的响应按照对应协议发送给用户

2. 多协议支持

不同的Channel使用不同的消息传递协议：

  • SSE（Server-Sent Events）: 基于HTTP协议的单向推送
  • WebSocket: 双向实时通信协议
  • SocketIO: 增强版WebSocket，支持自动重连等特性
  • Redis: 基于Redis的消息队列通道

3. 开发测试支持

  • 命令行Channel: 为开发者提供快速测试环境
  • 直接交互: 无需复杂集成即可验证Agent功能
  • 调试友好: 便于开发阶段的功能调试和问题排查

🔧 Channel配置

Channel通过endpoints.yml进行配置，支持多种通信协议：

Redis Channel（推荐）

# endpoints.yml
channel:
  type: redis
  host: localhost        # Redis服务器地址
  port: 6379            # Redis端口
  db: 0                 # Redis数据库编号
  password: "your_password"  # Redis密码（可选）
  
  # 高级配置
  max_connections: 20   # 最大连接数
  connection_timeout: 10 # 连接超时时间
  retry_attempts: 3     # 重试次数

WebSocket Channel

channel:
  type: websocket
  host: 0.0.0.0         # 监听地址
  port: 8080            # 监听端口
  path: /ws             # WebSocket路径
  
  # CORS配置
  allow_origins: ["*"]  # 允许的来源
  allow_methods: ["GET", "POST"]
  allow_headers: ["*"]

SocketIO Channel

channel:
  type: socketio
  host: 0.0.0.0
  port: 8080
  
  # SocketIO特定配置
  namespace: /cota      # 命名空间
  room_support: true    # 启用房间支持
  binary_support: true  # 支持二进制数据

SSE Channel

channel:
  type: sse
  host: 0.0.0.0
  port: 8080
  endpoint: /events     # SSE端点路径
  
  # 推送配置
  heartbeat_interval: 30  # 心跳间隔（秒）
  retry_timeout: 5000     # 客户端重试超时

命令行Channel

channel:
  type: cmdline
  
  # 可选配置
  prompt: "用户: "      # 输入提示符
  encoding: utf-8       # 字符编码
  history_size: 100     # 历史记录条数

📋 Channel类型详解

🔴 Redis Channel

  • 描述: 基于Redis的异步消息队列通道，支持高并发和消息持久化
  • 使用场景: 生产环境推荐，支持多实例部署和负载均衡
  • 特点:
    • 高性能异步处理
    • 支持消息持久化
    • 天然支持集群部署
    • 会话状态管理

🟠 WebSocket Channel

  • 描述: 基于标准WebSocket协议的双向实时通信通道
  • 使用场景: 需要实时交互的Web应用、移动应用
  • 特点:
    • 低延迟双向通信
    • 标准协议兼容性好
    • 支持文本和二进制数据
    • 连接状态管理

🟡 SocketIO Channel

  • 描述: 基于Socket.IO库的增强版WebSocket通道
  • 使用场景: 需要高级WebSocket特性的复杂应用
  • 特点:
    • 自动重连机制
    • 房间和命名空间支持
    • 事件驱动架构
    • 更好的浏览器兼容性

🟢 SSE Channel

  • 描述: 基于Server-Sent Events的单向推送通道
  • 使用场景: 服务器向客户端推送实时数据，如通知、状态更新
  • 特点:
    • HTTP协议基础，简单可靠
    • 自动重连支持
    • 较低的资源消耗
    • 适合单向数据推送

🔵 命令行Channel

  • 描述: 基于命令行接口的交互通道
  • 使用场景: 开发测试、调试验证、脚本自动化
  • 特点:
    • 零配置快速启动
    • 开发调试友好
    • 支持交互历史
    • 适合自动化脚本

🔄 消息处理流程

1. 消息接收流程

用户输入 → Channel → 协议解析 → Message对象 → Agent处理

2. 响应发送流程

Agent响应 → Message对象 → 协议封装 → Channel → 用户接收

3. Message格式

Channel统一使用标准Message格式：

{
  "sender": "user",
  "sender_id": "user_123", 
  "receiver": "bot",
  "receiver_id": "agent_456",
  "session_id": "session_789",
  "text": "用户输入的文本",
  "metadata": {}
}

🚀 使用示例

启动Redis Channel Agent

# 确保Redis服务运行
redis-server

# 启动Agent
cota run --agent-path ./weather --debug

启动WebSocket Channel Agent

# 配置WebSocket Channel后启动
cota run --agent-path ./weather --channel websocket

命令行测试

# 使用命令行进行快速测试
cota shell --agent-path ./weather --debug

⚡ 性能优化

1. Redis Channel优化

channel:
  type: redis
  host: localhost
  port: 6379
  
  # 连接池配置
  max_connections: 50
  min_connections: 5
  
  # 性能优化
  socket_keepalive: true
  socket_keepalive_options:
    TCP_KEEPINTVL: 1
    TCP_KEEPCNT: 3
    TCP_KEEPIDLE: 1

2. WebSocket优化

channel:
  type: websocket
  
  # 并发配置
  max_connections: 1000
  
  # 缓冲区设置
  read_buffer_size: 4096
  write_buffer_size: 4096
  
  # 超时设置
  ping_interval: 30
  ping_timeout: 10

🛠️ 最佳实践

1. Channel选择指南

  • 生产环境: 推荐Redis Channel，稳定可靠，支持集群
  • 实时应用: 选择WebSocket或SocketIO Channel
  • 单向推送: 使用SSE Channel，资源消耗低
  • 开发测试: 使用命令行Channel，快速验证

2. 安全配置

# WebSocket安全配置
channel:
  type: websocket
  
  # CORS设置
  allow_origins: ["https://yourdomain.com"]
  
  # 认证配置
  require_auth: true
  auth_header: "Authorization"
  
  # 限流配置
  rate_limit: 100  # 每分钟最大消息数

3. 监控和日志

# 启用Channel调试日志
import logging
logging.getLogger('cota.channels').setLevel(logging.DEBUG)

# 监控指标
- 连接数
- 消息吞吐量
- 响应时间
- 错误率

🔍 故障排查

常见问题

  1. Redis连接失败

    • 检查Redis服务状态
    • 验证连接参数和密码
    • 确认网络连通性

  2. WebSocket连接断开

    • 检查网络稳定性
    • 调整心跳间隔
    • 配置自动重连

  3. 消息丢失

    • 启用消息确认机制
    • 检查网络质量
    • 配置消息持久化

  4. 性能问题

    • 调整连接池大小
    • 优化消息处理逻辑
    • 启用缓存机制

通过合理选择和配置Channel，可以确保Agent与用户之间的稳定、高效通信，为用户提供优质的交互体验。

Message用于处理和传递系统中的各种信息，其设计旨在简化信息的输入和输出，使得不同接口之间的通信更加流畅和一致。

Message

Message信息对象包含了发送者、接收者、会话ID、文本内容以及一些可选的元数据。通过使用这个模块，开发者可以轻松地创建和处理信息，而无需担心底层的数据结构和格式。

信息创建

Message 类提供了一个简单的方法来创建信息对象。你可以指定以下参数：

sender: 信息的发送者。 sender_id: 发送者的唯一标识。 receiver: 信息的接收者。 receiver_id: 接收者的唯一标识。 session_id: 会话的唯一标识。 text: 信息的文本内容。 metadata: 附加的元数据。

信息转换

Message 类还提供了一个 as_dict 方法，可以将信息对象转换为一个字典。这个方法在需要将信息传递给其他系统或存储时非常有用。

使用示例

以下是一个简单的使用示例，展示了如何创建一个信息对象并将其转换为字典：

from message import Message

# 创建一个信息对象
msg = Message(
    sender="user",
    sender_id="user123",
    receiver="bot",
    receiver_id="bot456",
    session_id="session789",
    text="Hello, bot!",
    metadata={"type": "greeting"}
)

# 将信息对象转换为字典
msg_dict = msg.as_dict()
print(msg_dict)
输出结果将会是一个包含所有信息参数的字典：

{
    'sender': 'user',
    'sender_id': 'user123',
    'receiver': 'bot',
    'receiver_id': 'bot456',
    'session_id': 'session789',
    'text': 'Hello, bot!',
    'metadata': {'type': 'greeting'}
}

Message 和 Channel

message和 channel 是两个紧密相关的模块，它们共同构成了消息处理的核心机制。message定义了消息对象的结构和处理逻辑，包含了消息的发送者、接收者、内容等属性。 channel负责处理不同通信渠道的消息。它使用 Message 类来创建和处理消息对象，确保消息能够正确地从外部渠道进入系统，并进行相应的处理。

在接受到客户端的消息后，Channel 类中的 handle_message 方法会将接收到的消息转换为 Message 对象。send_response 方法则负责将处理后的消息发送回客户端。 通过这种设计，message 和 channel 共同确保了消息在不同通信渠道之间的正确传递和处理，使得系统能够灵活地适应各种通信方式。

消息处理

Query 和 Response 是两个具体的动作（Action）类，分别代表用户的请求和系统的回复，message和这两个Action的生产和处理相关。

Processor 接收到 Message，并根据消息内容生成一个 Query 动作。这个 Query 动作包含了消息的所有信息，如发送者、接收者、消息内容等。

Processor 会根据 Message 对象的 session_id 获取或创建一个对话状态跟踪器（DST），并更新这个跟踪器的状态。这个过程中，Message 对象的信息会被用于更新对话状态。

Processor 会将agent生成的回复动作 （Response）通过通道发送给用户，这个过程中，Message 对象的信息会被用于执行通道相关的操作。 通过这种设计，确保了用户消息的正确处理和系统回复的生成。

Action（动作）

动作(Action)是COTA框架中用户（User）或智能体（Agent）所产生的，能够影响对话状态（Dialogue State）的具体操作，它是智能体能感知的最小单元。用户和智能体通过执行不同的动作，来影响对话状态。本章会对不同的动作(Action)进行介绍。

🎯 基本介绍

用户执行UserUtter动作通过channel影响对话状态,智能体通过观察对话状态，选择合适的Action运行。Action在整个对话系统中处于核心位置，是连接用户意图和智能体响应的桥梁。

Action的定义和配置在agent.yml中，每个Action必须包含description和prompt这两个基本属性。

description是对Action的描述，表示action的作用， agent会根据action的description结合对话状态来决定下一步执行的动作。因此不同Action的description的表述需要清晰、容易区分、 没有歧义。

prompt主要用于Action的执行，当机器人的某个动作要执行时，prompt会作为大语言模型（LLM）的输入，辅助Action的执行。

description和prompt是需要在action定义时显示的配置的，除此之外，每个Action还会有创建时间timestamp、发送人sender_id、 接收人receiver_id、执行结果result等属性用于对话过程的正常运行，以及action的序列化和反序列化。

不同类型的Action，如基本的Action和Form之间属性会有不同，Form还会有槽位slots、执行器executer属性，这些会在下面的介绍中详细说明。

🔧 动作类型

UserUtter - 用户输入动作

UserUtter是用户的动作，当用户向智能体发送消息(Message)时，从智能体的视角，相当于用户执行了UserUtter这个Action，进而影响对话状态。用户发送的消息(Message)就作为UserUtter的执行结果。

UserUtter支持两种模式：

  • 真实用户模式：用户手动输入消息
  • 代理用户模式：通过LLM自动生成用户输入，用于数据生成和自动化测试

配置示例

基础配置（默认已包含）：

actions:
  UserUtter:
    description: "用户输入 - 此Action代表用户的输入消息，仅用于记录对话历史，Selector不应选择此Action"

代理模式配置：

actions:
  UserUtter:
    description: "用户向智能体咨询"
    prompt: |
      你是一个需要帮助的用户，根据对话历史提出合理的问题或回应。
      
      **历史对话：**
      {{history_messages}}
      
      **输出格式：**
      ```json
      {
        "thought": "你的内心想法和推理过程",
        "text": "你要说的话", 
        "state": "continue/stop"
      }
      ```

重要说明：

  • UserUtter在constant.py中已有默认配置，通常无需在agent.yml中重复定义
  • 代理模式下必须配置UserUtter的prompt
  • Selector不应选择UserUtter作为下一步动作

BotUtter - 智能体回复动作

BotUtter是智能体的动作，代表智能体向用户发送消息(Message)，消息将通过通道（channel）发送给用户。通过prompt来控制BotUtter的执行过程，如引导回复的语气、扮演的角色、异常的处理等。

配置示例

示例中的{{task_description}}和{{history_actions_with_thoughts}}都是DST提供的对话状态，这些对话状态在构建action的prompt时非常重要。DST(对话状态跟踪器)提供了丰富的状态，供智能体查询和使用。建议在prompt中指明输出格式，这会减少LLM出错的概率。

基础BotUtter配置：

actions:
  BotUtter:
    description: "回复用户"
    prompt: |
      你是一个智能助手，需要根据当前对话历史生成合适的回复。

      **任务描述：**
      {{task_description}}

      **输出格式要求：**
      ```json
      {"thought": "<你的推理过程>", "text": "<你的回复内容>"}
      ```

      **学习参考资料：**
      {{policies}}

      **实际对话历史：**
      {{history_actions_with_thoughts}}

      请分析上述对话历史，参考学习资料中的思维模式，生成合适的JSON格式回复。

支持知识库的BotUtter配置：

actions:
  BotUtter:
    description: "智能客服回复"
    prompt: |
      你是专业的客服助手，需要基于知识库和对话历史提供准确回复。

      **知识库信息：**
      {{knowledge}}
      
      **对话历史：**
      {{history_actions_with_thoughts}}
      
      **输出格式：**
      ```json
      {"thought": "<分析过程>", "text": "<回复内容>"}
      ```

重要说明：

  • BotUtter支持思维链（Chain of Thought）输出，通过thought字段展示推理过程
  • 支持知识库集成，通过{{knowledge}}变量获取RAG检索结果
  • 输出必须为标准JSON格式，确保系统能正确解析

Selector - 动作选择器

Selector是智能体的动作，用于判断智能体下一步应该执行哪个动作，Selector是让整个对话正常运转的关键。Selector根据智能体可选的Action列表，并依据历史的Action序列，从候选的Action列表中选择合适Action执行。

在一轮对话中，当用户执行UserUtter动作后，agent执行Selector选择候选的Action，执行Action，再通过Selector选择Action，继续执行，重复这个过程，直到达到对话结束条件。

工作机制

  • 思维链驱动：通过DPL（对话策略学习）生成思考过程
  • 上下文感知：基于完整对话历史进行决策
  • 规则避免：自动排除不合适的Action（如UserUtter）

配置示例

{{action_descriptions}}和{{history_actions_with_thoughts}}等为DST提供的对话状态，这些对话状态在构建action的prompt时非常重要。DST会自动处理Action过滤逻辑，比如{{action_descriptions}}中会排除Selector自身，防止陷入死循环。

actions:
  Selector:
    description: "选择合适的Actions"
    prompt: |
      你是一个智能对话助手，需要根据当前对话状态选择下一个最合适的Action。

      **输出格式要求：**
      ```json
      {"thought": "<你的推理过程>", "action": "<工具名称>"}
      ```

      **可用的Action工具：**
      {{action_descriptions}}

      **决策参考模式：**
      {{policies}}

      **当前对话状态：**
      {{history_actions_with_thoughts}}

      请分析当前对话状态，参考决策模式，选择最合适的下一个Action并输出JSON格式结果。

Form - 表单动作

Form(表单)是对话领域的一个基本概念，是一种结构化的数据收集工具，用于在对话系统中收集用户输入的信息并执行相应的业务逻辑。

在COTA中，Form是智能体的特殊动作类型，用于收集信息并执行特定的操作，Form在定制的业务场景中非常重要和实用。例如在查询天气的场景：收集城市→收集日期→调用天气接口→返回天气信息，这个完整的流程构成一个Form。

核心组件

Form的定义由description、prompt、slots、executer等构成：

  • description: 描述Form的作用和功能
  • prompt: 统一处理槽位更新和结果返回的主要提示词
  • slots: 定义需要收集的信息槽位
  • executer: 外部服务执行器，用于调用API或执行业务逻辑

工作流程

  1. 槽位收集: 依次询问用户填充slots中定义的信息
  2. 状态更新: 通过主prompt智能解析用户输入并更新槽位状态
  3. 完整性检查: 当所有必需槽位填充完成后，进入执行阶段
  4. 外部调用: 通过executer调用外部API获取结果
  5. 结果返回: 将执行结果返回给用户

优化说明: 最新版本中，updater和breaker已被整合到主prompt中，简化了配置结构。

配置示例

Form通过slots和executer属性被系统自动识别为Form类型的Action。最新版本简化了配置结构，不再需要单独的updater和breaker配置。

完整的天气查询Form示例：

actions:
  Weather:
    description: "查询天气"
    prompt: |
      当前正在执行{{current_form_name}}，其描述为{{current_form_description}}。
      根据对话内容及Action序列，结合当前slot的状态，填充或重置slot的值。
      
      历史Action序列为:
      {{history_actions_with_thoughts}}
      
      Action的描述为:
      {{action_descriptions}}
      
      当前slots为:
      {{current_form_slot_states}}
      
      slots的含义为:
      {{current_form_slot_descriptions}}
      
      填充或重置slot的值，保持slots格式输出json字符串。

    slots:
      city:
        description: "城市，注意：接口只支持输入单个城市"
        prompt: |
          当前正在执行Action {{current_form_name}}, 其描述为 {{current_form_description}}。
          接下来需要询问用户，需要查询哪个城市的天气。
          
          你必须严格按照以下JSON格式响应：
          {"text": "<你的回复内容>"}

      time:
        description: "时间"
        prompt: |
          当前正在执行Action {{current_form_name}}, 其描述为 {{current_form_description}}。
          接下来需要询问用户，需要查询哪天的天气。

          你必须严格按照以下JSON格式响应：
          {"text": "<你的回复内容>"}

    executer:
      url: http://rap2api.taobao.org/app/mock/319677/Weather
      method: GET
      output: ["<text>", "接口异常"]
      mock: false

关键特性：

  • 统一提示词: 主prompt处理所有槽位更新逻辑
  • JSON格式: 槽位询问和结果返回都使用标准JSON格式
  • 灵活配置: 支持HTTP方法、输出格式和模拟模式配置 注意：Cota提供了丰富的mock api供开发者快速测试新建的对话，同时开发者也可以在CotaAI的cota-api仓库中提交自己mock的api。

CustomAction - 自定义动作

在业务场景中，我们经常需要自定义Action，如计算器功能、查天气、转人工等。自定义Action非常简单，只需要在agent.yml中配置，这些自定义的Action会自动注册到智能体中。

自定义基础类型的Action

如果你想自定义一个专门的回复Action，可以通过配置实现。不过鉴于BotUtter的灵活性，通常情况下直接使用BotUtter并通过不同的prompt来实现不同的回复风格更为合适。

配置示例
actions:
  CustomerService:
    description: "专业客服回复"
    prompt: |
      你是专业的客服代表，需要提供友好、准确的服务。

      **任务描述：**
      {{task_description}}

      **对话历史：**
      {{history_actions_with_thoughts}}

      **输出格式：**
      ```json
      {"thought": "<分析过程>", "text": "<客服回复>"}
      ```

      请以专业、友好的语气回复用户。

自定义Form类型的Action

更常见的是自定义Form类型的Action，如查询天气、订餐或者定机票。Form类型的Action通过slots和executer属性被系统识别。

转人工服务示例
actions:
  RenGong:
    description: "转人工"
    executer:
      url: http://rap2api.taobao.org/app/mock/319677/Rengong
      method: GET
      output: ["成功", "失败"]
      mock: true
复杂业务Form示例 - 订票服务
actions:
  BookTicket:
    description: "预订机票"
    prompt: |
      当前正在执行{{current_form_name}}，需要收集订票信息。
      
      历史Action序列：{{history_actions_with_thoughts}}
      当前slots状态：{{current_form_slot_states}}
      槽位含义：{{current_form_slot_descriptions}}
      
      请根据用户输入更新槽位信息，输出JSON格式的slots状态。

    slots:
      departure:
        description: "出发城市"
        prompt: |
          请问您要从哪个城市出发？
          输出格式：{"text": "<询问出发城市的话>"}
          
      destination:
        description: "目的地城市"  
        prompt: |
          请问您要到哪个城市？
          输出格式：{"text": "<询问目的地的话>"}
          
      date:
        description: "出行日期"
        prompt: |
          请问您计划什么时候出行？
          输出格式：{"text": "<询问日期的话>"}

    executer:
      url: https://api.example.com/bookticket
      method: POST
      output: ["订票成功，订单号：{order_id}", "订票失败"]
      mock: false

📚 总结

Action是COTA框架的核心概念，通过不同类型的Action组合，可以构建功能强大的对话系统：

🎯 核心Action类型

  • UserUtter: 用户输入，支持真实用户和代理模式
  • BotUtter: 智能体回复，支持思维链和知识库集成
  • Selector: 动作选择器，决定对话流程
  • Form: 表单动作，用于结构化数据收集和业务逻辑执行

🔧 配置要点

  • 所有模板变量使用{{variable}}格式
  • 输出格式统一为JSON，确保系统解析稳定
  • Form配置已简化，主prompt统一处理槽位更新
  • 支持思维链（Chain of Thought）提升对话可解释性

🚀 最佳实践

  • 合理设计Action的description，确保Selector能准确选择
  • 充分利用DST提供的丰富状态变量
  • 在prompt中明确输出格式要求
  • 对于复杂业务场景，优先使用Form类型Action
  • 利用代理模式进行自动化测试和数据生成

通过灵活配置和组合这些Action，可以实现从简单问答到复杂业务流程的各种对话场景。

DST (对话状态跟踪器)

Dialogue State Tracker (DST) 是COTA框架中的关键组件，负责跟踪和更新对话状态。DST在多轮对话中扮演着“记忆“的角色，记录对话历史信息，帮助系统理解当前对话的上下文，并为Action提供丰富的状态变量。

🎯 核心功能

1. 状态维护

  • Action序列: 维护完整的Action执行顺序和结构
  • 对话历史: 记录用户和智能体的完整交互历史
  • 槽位状态: 跟踪Form动作中的槽位填充状态
  • 会话持久化: 支持跨会话的状态保存和恢复

2. 状态提供

DST为Action的prompt提供丰富的状态变量，通过{{}}模板语法使用：

  • 任务信息: {{task_description}}等任务相关状态
  • 对话历史: {{history_actions_with_thoughts}}等历史信息
  • 当前状态: {{current_form_name}}等当前执行状态
  • 知识信息: {{knowledge}}等外部知识状态

3. 状态恢复

通过序列化机制，DST可以：

  • 将对话状态保存到数据库（MySQL、Redis等）
  • 在新会话中从数据库恢复历史状态
  • 支持跨会话的连续对话体验

🔧 基本结构

DST的核心是Action列表，维护着整个对话的执行轨迹。通过DST中的Action序列和agent.yml配置，可以完整复现一个对话过程。

配置示例

在agent.yml中使用DST状态变量的示例：

actions:
  BotUtter:
    description: "回复用户的提问"
    prompt: |
      根据任务描述和历史对话，生成回答。

      **任务描述：**
      {{task_description}}

      **对话历史：**
      {{history_actions_with_thoughts}}

      **学习参考资料：**
      {{policies}}

      **输出格式：**
      ```json
      {"thought": "<推理过程>", "text": "<回复内容>"}
      ```

  Selector:
    description: "选择合适的Actions"
    prompt: |
      根据当前对话状态选择下一个Action。

      **可用Actions：**
      {{action_descriptions}}

      **对话状态：**
      {{history_actions_with_thoughts}}

      **输出格式：**
      ```json
      {"thought": "<分析过程>", "action": "<动作名称>"}
      ```

📋 State变量列表

DST提供丰富的状态变量，覆盖任务、用户、动作、历史等多个维度。所有变量使用{{variable_name}}模板语法。

🎯 任务相关状态

task_description

  • 描述: Agent的任务描述，来自agent.yml中的system.description
  • 使用场景: 为Action提供角色和任务上下文
  • 返回示例: "你是一名专业的宠物医生，需要认真负责地回答用户问题"

👤 用户相关状态

history_messages

  • 描述: 原始消息历史，包含用户和机器人的对话内容
  • 使用场景: 主要用于UserUtter的代理模式
  • 返回示例: 
    用户: 你好
机器人: 您好，请问有什么可以帮您的？
用户: 我家猫咪不吃饭

latest_user_query

  • 描述: 用户最近一次的输入内容
  • 使用场景: 用于Form动作的跳出判断等
  • 返回示例: "我家猫咪不吃饭，怎么办？"

🔧 动作相关状态

action_descriptions

  • 描述: 所有可用Action的描述信息（通常排除UserUtter）
  • 使用场景: 主要用于Selector选择动作
  • 返回示例: 
    BotUtter: 回复用户
Weather: 查询天气
RenGong: 转人工

current_action_name

  • 描述: 当前正在执行的Action名称
  • 使用场景: Form动作中使用
  • 返回示例: "Weather"

current_action_description

  • 描述: 当前正在执行的Action描述
  • 使用场景: Form动作中提供上下文
  • 返回示例: "查询天气"

latest_action_name

  • 描述: 最近一次执行的Action名称
  • 使用场景: 状态跟踪和条件判断
  • 返回示例: "Selector"

latest_action_result

  • 描述: 最近一次Action的执行结果
  • 使用场景: 获取上一步的执行输出
  • 返回示例: "Weather"（如果上一步是Selector选择了Weather）

📚 历史序列相关状态

history_actions_with_thoughts

  • 描述: 带思维链的完整Action执行历史，是最重要的状态变量
  • 使用场景: BotUtter和Selector的主要输入，提供完整对话上下文
  • 返回示例: 
    [
  {
    "name": "UserUtter", 
    "result": "你好",
    "timestamp": 1760880555.173912
  },
  {
    "name": "Selector",
    "thought": "用户已打招呼，我应该回复用户以继续对话",
    "result": "BotUtter",
    "timestamp": 1760880555.174119
  },
  {
    "name": "BotUtter",
    "thought": "用户打招呼，我需要友好回应",
    "result": "你好，请问有什么可以帮您？",
    "timestamp": 1760880557.379215
  }
]

policies

  • 描述: 策略思维链参考数据，来自policy/data.yml
  • 使用场景: 为BotUtter和Selector提供学习参考模式
  • 返回示例: 包含历史标注数据的思维模式，用于指导当前决策

📋 Form相关状态

current_form_name

  • 描述: 当前执行的Form动作名称
  • 使用场景: Form动作的提示词中使用
  • 返回示例: "Weather"

current_form_description

  • 描述: 当前Form的描述信息
  • 使用场景: 为用户说明当前正在执行的业务
  • 返回示例: "查询天气"

current_form_slot_states

  • 描述: 当前Form的槽位状态（JSON格式）
  • 使用场景: Form的updater逻辑中使用
  • 返回示例: 
    {
  "city": "杭州",
  "time": null
}

current_form_slot_descriptions

  • 描述: Form中各槽位的描述信息
  • 使用场景: 帮助LLM理解槽位含义
  • 返回示例: 
    city: 城市，注意：接口只支持输入单个城市
time: 时间

current_form_execute_result

  • 描述: Form执行器的返回结果
  • 使用场景: Form执行完成后，向用户展示结果
  • 返回示例: "sunny" (天气查询的结果)

🧠 知识相关状态

knowledge

  • 描述: 知识库检索结果（当配置了knowledge时可用）
  • 使用场景: BotUtter中集成外部知识
  • 返回示例: 
    根据您的问题，猫咪不吃饭可能的原因包括：
1. 食物问题：食物变质或不新鲜
2. 环境因素：换了新环境或有压力
3. 健康问题：可能存在口腔疾病或消化问题
建议先检查食物质量，观察猫咪其他行为...

🔄 状态生命周期

DST状态变量在对话过程中动态更新：

  1. 会话开始: 初始化基本状态，加载历史（如果有）
  2. 用户输入: 更新latest_user_query、history_messages等
  3. Action执行: 更新current_action_name、action历史等
  4. Form处理: 更新Form相关的所有状态变量
  5. 会话结束: 序列化状态到存储系统

📊 最佳实践

状态变量使用建议

  1. BotUtter动作:

    • 必用: {{history_actions_with_thoughts}}、{{task_description}}
    • 推荐: {{policies}}（思维链学习）、{{knowledge}}（知识库）

  2. Selector动作:

    • 必用: {{action_descriptions}}、{{history_actions_with_thoughts}}
    • 推荐: {{policies}}（决策参考）

  3. Form动作:

    • 必用: {{current_form_slot_states}}、{{current_form_slot_descriptions}}
    • 推荐: {{history_actions_with_thoughts}}、{{current_form_name}}

  4. UserUtter动作（代理模式）:

    • 必用: {{history_messages}}
    • 推荐: {{task_description}}（角色扮演）

性能优化

  • 合理使用状态变量，避免不必要的大量历史数据
  • 对于长对话，考虑历史截断策略
  • 利用缓存机制提升状态变量生成效率

通过合理使用这些状态变量，可以构建出上下文丰富、逻辑清晰的对话系统。

Agent（智能体）

Agent是COTA框架中的核心组件，负责管理和执行对话流程。它通过与用户交互，理解用户意图，并根据预定义的规则和策略生成相应的响应。Agent的设计旨在确保对话的流畅性、准确性和智能化，从而提供良好的用户体验。

🎯 Agent的核心功能

Agent提供以下核心功能：

1. 对话管理

  • 状态跟踪: 通过DST（对话状态跟踪器）维护对话上下文
  • 流程控制: 管理对话的开始、进行和结束
  • 多轮支持: 支持复杂的多轮对话场景

2. 智能决策

  • 动作选择: 通过Selector智能选择下一步执行的动作
  • 策略学习: 基于DPL（对话策略学习）进行决策优化
  • 思维链: 支持Chain of Thought推理，提供可解释的决策过程

3. 知识集成

  • RAG支持: 集成知识库进行检索增强生成
  • 多模态: 支持文本、图像等多种模态的处理
  • 动态学习: 在对话过程中动态学习和适应

🔧 Agent配置

Agent的配置主要包括以下几个方面：

  • 系统描述: 定义Agent的角色、性格和基本行为模式
  • 对话配置: 控制对话模式、参数限制和代理功能
  • 策略配置: 定义思维模式和决策策略（trigger、match、llm）
  • 知识配置: 配置知识来源和检索策略（可选）
  • 动作配置: 定义Agent可执行的具体动作和行为

配置文件结构如下：agent.yml（主要配置）+ endpoints.yml（服务连接配置）

agent.yml配置示例：

system:
  description: "你是一名专业的宠物医生，需要认真负责地回答用户问题，要求回答的尽量精准和谨慎"

dialogue:
  use_proxy_user: false  # 是否启用代理用户模式
  max_proxy_step: 20     # 代理模式下的最大步骤数
  max_tokens: 500        # LLM生成的最大令牌数

policies:
  - type: trigger        # 基于规则的触发策略
  - type: match         # 基于标注数据的思维链学习

actions:
  BotUtter:
    description: "回复用户的提问"
    prompt: |
      你是一名专业的宠物医生，需要根据当前对话历史生成合适的回复。

      **任务描述：**
      {{task_description}}

      **输出格式要求：**
      ```json
      {"thought": "<你的推理过程>", "text": "<你的回复内容>"}
      ```

      **学习参考资料：**
      {{policies}}

      **实际对话历史：**
      {{history_actions_with_thoughts}}

      请分析上述对话历史，参考学习资料中的思维模式，生成专业的医疗建议。

  Selector:
    description: "选择合适的Actions"
    prompt: |
      你需要根据当前对话状态选择下一个最合适的Action。

      **可用的Action工具：**
      {{action_descriptions}}

      **当前对话状态：**
      {{history_actions_with_thoughts}}

      **输出格式：**
      ```json
      {"thought": "<你的分析过程>", "action": "<动作名称>"}
      ```

endpoints.yml配置示例：

llms:
  deepseek:
    type: openai
    model: deepseek-chat
    key: your_api_key_here
    apibase: https://api.deepseek.com/v1

channel:
  type: redis
  host: localhost
  port: 6379
  db: 1

base_store:
  type: Memory
  # 或者使用SQL数据库
  # type: SQL
  # dialect: mysql+pymysql
  # host: localhost
  # port: 3306
  # db: cota_agent
  # username: your_username
  # password: your_password

🔄 Agent与其它模块的关系

Agent作为COTA框架的核心协调者，与各个模块密切协作：

核心模块交互

  • Processor: Agent的核心处理引擎，负责对话逻辑和状态更新，是Agent与其他模块交互的中枢
  • DST（对话状态跟踪器）: 维护对话状态，为Agent提供丰富的上下文信息和模板变量
  • DPL（对话策略学习）: 为Agent提供智能决策能力，生成思维链和动作预测
  • Action系统: Agent通过Action执行具体的对话行为，包括UserUtter、BotUtter、Selector等

外部服务集成

  • LLM: 语言模型服务，为Agent提供自然语言理解和生成能力
  • Store: 数据存储服务，持久化对话状态和用户数据
  • Channel: 通信通道，连接Agent与外部用户或系统
  • Knowledge: 知识库服务，为Agent提供外部知识支持（RAG）

架构关系图

User Input
    ↓
[Channel] ←→ [Agent] ←→ [Processor]
                ↓           ↓
            [Actions] ←→ [DST] ←→ [DPL]
                ↓           ↓      ↓
            [LLM] ←←←← [Store] → [Knowledge]

🚀 Agent运行流程

1. 初始化阶段

  1. 配置加载: 从agent.yml和endpoints.yml加载配置
  2. 模块初始化: 创建LLM、Store、Knowledge等服务实例
  3. Action注册: 根据配置注册可用的Action
  4. 策略加载: 初始化DPL策略（trigger、match、llm）

2. 对话处理阶段

  1. 消息接收: 通过Channel接收用户消息
  2. 状态跟踪: DST更新对话状态，生成上下文变量
  3. 策略决策: DPL生成思维链，Selector选择下一个Action
  4. Action执行: 执行选定的Action（BotUtter、Form等）
  5. 响应生成: 通过LLM生成响应内容
  6. 状态保存: Store持久化更新后的对话状态
  7. 消息发送: 通过Channel将响应发送给用户

3. 特殊功能

  • 代理模式: 启用use_proxy_user后，Agent可自动模拟用户输入
  • 知识检索: 配置Knowledge后，Agent可集成外部知识库
  • 思维链: 支持Chain of Thought，提供可解释的推理过程
  • 多策略: 同时支持规则、匹配和LLM多种决策策略

通过这种模块化设计，Agent能够灵活应对各种对话场景，从简单问答到复杂的多轮业务对话。

LLM (大语言模型)

在COTA框架中，LLM（Large Language Model）扮演着核心角色，为智能体提供自然语言理解、生成和推理能力。LLM是Agent智能化的关键驱动力，负责处理复杂的对话理解、决策推理和内容生成任务。

🎯 核心功能

1. 自然语言理解

  • 意图识别: 理解用户输入的真实意图和需求
  • 上下文理解: 基于多轮对话历史理解当前语境
  • 语义解析: 提取关键信息和实体，支持槽位填充

2. 智能决策推理

  • 动作选择: 通过Selector动作，智能选择下一步执行的Action
  • 思维链生成: 产生可解释的推理过程（Chain of Thought）
  • 策略学习: 基于历史数据和标注示例进行策略优化

3. 内容生成

  • 对话回复: 生成自然、连贯、符合角色设定的回复内容
  • 多模态输出: 支持文本、JSON等多种格式的结构化输出
  • 个性化表达: 根据Agent角色定制语言风格和表达方式

🔧 LLM配置

LLM在COTA中通过endpoints.yml进行配置，支持多种模型类型和灵活的参数设置。

基础配置结构

# endpoints.yml
llms:
  model_name:            # 自定义模型名称，在agent.yml中引用
    type: openai         # LLM类型
    model: gpt-4         # 具体模型名称
    key: your_api_key    # API密钥
    apibase: https://api.openai.com/v1  # API基础URL
    max_tokens: 1000     # 最大生成长度（可选）
    temperature: 0.7     # 生成温度（可选）

支持的LLM类型

1. OpenAI兼容接口

llms:
  gpt4:
    type: openai
    model: gpt-4
    key: sk-xxx
    apibase: https://api.openai.com/v1
    
  deepseek:
    type: openai
    model: deepseek-chat
    key: sk-xxx
    apibase: https://api.deepseek.com/v1
    
  qwen:
    type: openai  
    model: qwen-max
    key: sk-xxx
    apibase: https://dashscope.aliyuncs.com/compatible-mode/v1

2. RAG增强模型

llms:
  rag-glm4:
    type: openai-rag
    model: glm-4
    key: your_api_key
    apibase: https://open.bigmodel.cn/api/paas/v4/
    knowledge_id: your_knowledge_id
    rag_prompt: |
      基于知识库内容回答问题。如果知识库中没有相关信息，请明确告知用户。

3. 自定义LLM

llms:
  custom_model:
    type: custom
    model: your-custom-model
    endpoint: https://your-api.com/v1/chat
    headers:
      Authorization: Bearer your_token
      Content-Type: application/json

高级配置选项

llms:
  advanced_model:
    type: openai
    model: gpt-4
    key: sk-xxx
    apibase: https://api.openai.com/v1
    
    # 生成参数
    max_tokens: 1500
    temperature: 0.7
    top_p: 0.9
    frequency_penalty: 0.1
    presence_penalty: 0.1
    
    # 重试配置
    retry_attempts: 3
    retry_delay: 1.0
    timeout: 30
    
    # 并发配置
    max_concurrent: 10

🔄 LLM与其他组件的关系

与Agent的关系

  • 核心驱动: LLM为Agent提供语言理解和生成的核心能力
  • 多实例管理: Agent可以管理多个LLM实例，针对不同场景使用不同模型
  • 动态选择: 根据Action类型和业务需求，动态选择最合适的LLM

与Action的关系

BotUtter动作

  • 内容生成: LLM根据prompt模板和上下文信息生成回复
  • 思维链: 生成包含推理过程的structured输出
  • 知识集成: 结合RAG模式，集成外部知识库内容

Selector动作

  • 决策推理: LLM分析对话状态，选择下一个最合适的Action
  • 策略学习: 基于历史策略数据，学习最佳决策模式
  • 上下文感知: 充分利用对话历史进行智能决策

Form动作

  • 槽位更新: 智能解析用户输入，更新槽位状态
  • 信息提取: 从自然语言中提取结构化信息
  • 用户引导: 生成合适的询问，引导用户提供必要信息

UserUtter动作（代理模式）

  • 用户模拟: 在代理模式下，LLM模拟真实用户的对话行为
  • 角色扮演: 根据设定的用户角色，生成符合特征的输入
  • 对话推进: 自动推进对话进程，用于测试和数据生成

与DPL的关系

  • 策略执行: DPL调用LLM执行具体的推理和生成任务
  • 思维链生成: LLM为DPL提供可解释的推理过程
  • 策略优化: 基于LLM的输出质量，不断优化DPL策略

⚡ 性能优化

1. 模型选择策略

# 根据任务复杂度选择不同模型
llms:
  fast_model:      # 简单任务使用快速模型
    type: openai
    model: gpt-3.5-turbo
    
  smart_model:     # 复杂推理使用强力模型
    type: openai  
    model: gpt-4
    
  local_model:     # 高频任务使用本地模型
    type: custom
    endpoint: http://localhost:8000/v1/chat

2. 并发控制

llms:
  production_model:
    type: openai
    model: gpt-4
    key: sk-xxx
    max_concurrent: 20    # 最大并发请求数
    rate_limit: 100       # 每分钟最大请求数
    batch_size: 10        # 批处理大小

3. 缓存机制

  • 请求缓存: 相同输入的LLM请求结果缓存
  • 模板缓存: 编译后的prompt模板缓存
  • 会话缓存: 会话级别的上下文缓存

4. 错误处理

# 自动重试和降级策略
llms:
  primary_model:
    type: openai
    model: gpt-4
    retry_attempts: 3
    fallback_model: gpt-3.5-turbo
    
  backup_model:
    type: openai  
    model: gpt-3.5-turbo

🚀 最佳实践

1. 模型配置建议

  • 开发环境: 使用成本较低的模型（如GPT-3.5）进行开发调试
  • 生产环境: 根据业务需求选择合适的模型，平衡性能和成本
  • 专用场景: 为特定任务配置专门优化的模型

2. Prompt工程

  • 明确指令: 在Action的prompt中给出明确、具体的指令
  • 格式约束: 严格定义输出格式，确保系统能正确解析
  • 上下文控制: 合理利用DST提供的状态变量，避免冗余信息

3. 安全性考虑

  • 密钥管理: 使用环境变量或密钥管理系统存储API密钥
  • 访问控制: 限制LLM的访问权限，避免滥用
  • 内容过滤: 实施输入输出内容过滤，确保合规性

4. 监控和调试

# 启用LLM调试日志
import logging
logging.getLogger('cota.llm').setLevel(logging.DEBUG)

# 监控LLM性能指标
- 响应时间
- 成功率  
- Token消耗
- 错误分布

🔍 故障排查

常见问题

  1. API密钥错误

    • 检查密钥格式和有效性
    • 确认密钥权限和额度

  2. 网络连接超时

    • 调整timeout参数
    • 检查网络连接和代理设置

  3. 模型输出格式错误

    • 优化prompt模板
    • 增加格式校验和重试机制

  4. 性能问题

    • 调整并发参数
    • 启用缓存机制
    • 考虑使用更快的模型

通过合理配置和使用LLM，可以构建出智能、高效、稳定的对话系统，为用户提供优质的交互体验。

DPL (Dialogue Policy Learning)

DPL（对话策略学习）是COTA框架中负责智能体决策和思维链生成的核心模块。它根据对话历史和当前状态，智能地决定下一步执行的动作并生成相应的思考过程。

🎯 核心功能

DPL模块提供两个主要功能：

1. 思维链生成 (Thought Generation)

  • 功能: 为即将执行的动作生成思考过程
  • 方法: generate_thoughts(dst: DST, action: Action) -> Optional[Text]
  • 作用: 帮助智能体产生逻辑推理过程，提升对话的连贯性和解释性

2. 动作预测 (Action Prediction)

  • 功能: 基于对话历史预测下一步应该执行的动作
  • 方法: generate_actions(dst: DST) -> Optional[List[Text]]
  • 作用: 实现智能体的自主决策能力

🔧 DPL类型

COTA支持三种不同类型的DPL策略：

1. TriggerDPL - 触发式策略

特点:

  • 基于动作序列模式匹配
  • 通过历史对话路径预测下一个动作
  • 适用于有明确动作流程的场景

工作原理:

# 配置示例
policies:
  - type: trigger

应用场景:

  • 任务导向型对话
  • 表单填写流程
  • 标准化服务流程

2. MatchDPL - 匹配式策略

特点:

  • 基于动作序列匹配生成思考内容
  • 从历史策略中检索相似的对话片段
  • 提供丰富的思维链支持

工作原理:

# 配置示例  
policies:
  - type: match

应用场景:

  • 需要详细推理过程的对话
  • 复杂决策场景
  • 教学和解释性对话

3. LLMDPL - 基于LLM推理策略

特点:

  • 基于大语言模型进行动态推理
  • 支持按动作类型配置不同的LLM
  • 提供灵活的思维链生成能力

工作原理:

# 配置示例
policies:
  - type: llm
    config:
      llms:
        - name: deepseek-chat    # 默认LLM
        - name: qwen-max         # BotUtter专用LLM
          action: BotUtter
        - name: glm-4           # Selector专用LLM
          action: Selector

应用场景:

  • 开放域对话
  • 需要创造性思维的场景
  • 个性化对话体验

📁 数据组织

策略数据结构

DPL从策略配置文件中读取数据，支持以下结构：

# 策略文件示例 (data.yml)
policies:
  - title: "客户咨询处理流程"
    actions:
      - name: UserUtter
        result: "我想了解产品信息"
      - name: BotUtter  
        thought: "用户询问产品信息，我需要提供详细的产品介绍"
        result: "让我为您介绍我们的产品特性..."
      
triggers:
  - title: "常见问题处理"
    actions:
      - name: UserUtter
        result: "有什么优惠活动吗"
      - name: QueryPromotion
        # 触发查询促销信息的动作

文件组织方式

bot_policy/
├── data.yml          # 主要策略数据
├── rules.yml         # 规则配置
└── llm_dpl_*.md     # LLM自动生成的知识库文件

⚙️ 配置方式

1. 基本配置

在智能体配置文件中启用DPL：

# agent.yml
policies:
  - type: trigger        # 启用触发式策略
  - type: match         # 启用匹配式策略  
  - type: llm           # 启用LLM推理策略
    config:
      llms:
        - name: deepseek-chat

2. 多策略组合

可以同时启用多种DPL策略，系统会按顺序尝试：

policies:
  - type: trigger       # 首先尝试触发式匹配
  - type: match        # 其次尝试模式匹配
  - type: llm          # 最后使用LLM推理
    config:
      llms:
        - name: qwen-max         # BotUtter专用LLM
          action: BotUtter
        - name: glm-4           # Selector专用LLM
          action: Selector  
        - name: deepseek-chat    # 默认LLM

3. 动作特定配置

对不同类型的动作使用不同的LLM：

policies:
  - type: llm
    config:
      llms:
        - name: qwen-max         # 回复类动作使用通义千问
          action: BotUtter
        - name: deepseek-chat    # 表单类动作使用DeepSeek
          action: FormAction
        - name: glm-4           # 默认使用ChatGLM

🔄 工作流程

DPL处理流程

  1. 接收请求: 从DST获取对话状态和待执行动作
  2. 策略选择: 根据配置选择合适的DPL策略
  3. 模式匹配: 分析对话历史，寻找匹配的模式
  4. 内容生成: 生成思考内容或预测下一步动作
  5. 结果返回: 将生成的内容返回给智能体

动作序列分析

DPL通过分析用户话语（UserUtter）之间的动作序列来进行决策：

UserUtter -> BotUtter -> FormAction -> UserUtter -> [预测下一个动作]
    ↑                                      ↑
   起点                                   当前位置

📊 性能优化

1. 缓存机制

  • 特征缓存: 预处理后的策略特征会被缓存
  • 结果缓存: 相同输入的生成结果会被缓存

2. 流式处理

  • 内存优化: LLMDPL支持流式处理大量策略数据
  • 分类存储: 按动作类型自动分类存储知识库文件

3. 哈希去重

  • 使用哈希算法避免重复处理相同的动作序列
  • 提升检索效率和存储空间利用率

🚀 最佳实践

1. 策略设计原则

  • 明确目标: 为每个对话场景设计清晰的策略目标
  • 模式复用: 提取可复用的对话模式，提升策略覆盖率
  • 逐步优化: 根据实际对话效果持续优化策略内容

2. 数据质量保证

  • 完整性: 确保动作序列的完整性和逻辑性
  • 一致性: 保持思考内容与动作结果的一致性
  • 多样性: 提供多样化的对话路径和响应方式

3. 调试和监控

  • 日志记录: 启用详细的DPL执行日志
  • 效果评估: 定期评估不同策略的匹配效果
  • A/B测试: 对比不同DPL配置的对话质量

🔍 调试指南

常见问题排查

  1. 无法生成思考内容

    • 检查策略文件格式是否正确
    • 确认动作序列是否匹配
    • 验证LLM配置是否有效

  2. 动作预测不准确

    • 增加更多的训练策略数据
    • 调整动作序列匹配规则
    • 检查触发条件是否合理

  3. 性能问题

    • 启用缓存机制
    • 优化策略文件大小
    • 调整并发处理参数

日志分析

启用DEBUG级别日志查看DPL详细执行过程：

import logging
logging.getLogger('cota.dpl').setLevel(logging.DEBUG)

📚 扩展开发

自定义DPL策略

可以继承基类DPL实现自定义策略：

from cota.dpl.dpl import DPL

class CustomDPL(DPL):
    async def generate_thoughts(self, dst, action):
        # 自定义思考生成逻辑
        return "Custom thought process"
    
    async def generate_actions(self, dst):
        # 自定义动作预测逻辑  
        return ["CustomAction"]

插件集成

DPL支持与其他COTA组件的无缝集成：

  • Action: 为动作执行提供思考支持
  • DST: 从对话状态获取上下文信息
  • LLM: 调用大语言模型进行内容生成
  • Agent: 与智能体框架深度集成

DPL作为COTA的智慧大脑，为智能体提供了强大的决策和推理能力，是构建高质量对话系统的关键组件。