Parlant 项目精讲：如何让Agent更听话

项目原地址： github.com/emcie-co/pa…

项目定位与核心价值

Parlant 是一个开源的 Agentic Behavior Modeling (ABM) 引擎，专门用于构建面向客户的对话式 AI 代理。与传统的基于提示工程的框架不同，Parlant 通过结构化的行为建模方法，确保 AI 代理能够可靠地遵循业务规则和预期行为。

核心价值主张

解决的核心问题：

• LLM 不遵循指令：传统方法依赖系统提示词，但 LLM 经常忽略或误解这些指令
• 行为不一致：相同输入可能产生不同输出，难以保证生产环境下的可靠性
• 难以控制：缺乏有效机制确保代理在关键时刻遵循业务规则
• 调试困难：无法理解代理为何做出特定决策

Parlant 的解决方案：

• ✅ 确保规则遵循：通过动态指南匹配和上下文应用，确保代理遵循业务规则
• ✅ 行为可预测：结构化的行为建模方法提供一致、可预测的行为
• ✅ 生产就绪：从第一天起就具备企业级功能，支持大规模部署
• ✅ 完全可解释：提供详细的决策过程追踪和可解释性

---

第一章：Guidelines（行为准则）

1.1 什么是 Guidelines？

Guideline：用自然语言定义的上下文规则，指导代理在特定情况下的行为。

每个 Guideline 由两部分组成：

• Condition（条件）：指定何时应该应用该指南
• Action（动作）：描述应该做什么

基本结构：

await agent.create_guideline(
    condition="客户询问产品库存",
    action="先检查库存状态，然后提供准确信息"
)

1.2 Guidelines 的核心特性

1.2.1 条件-动作结构

每个 Guideline 都遵循清晰的条件-动作模式。观察性指南只有条件，没有动作，仅用于上下文理解。

1.2.2 动态匹配

系统自动评估对话上下文，只加载相关的 Guidelines，确保最大化 LLM 注意力、降低认知负担、提高准确性。

1.2.3 工具关联

Guidelines 可以与工具（函数）关联，确保工具在正确时机被调用。

1.2.4 应用追踪

系统跟踪 Guideline 是否已被应用，避免重复。持续型指南可以重复应用。

1.3 Guidelines 的类型

类型	特点	确定方式
Observational	只有条件，没有动作	action=None
Actionable	有条件和动作	提供 action 参数
Continuous	可以重复应用	metadata={"continuous": True}
Customer-Dependent	动作需要客户提供信息	metadata={"customer_dependent_action_data": {...}}

类型确定方式：

• 手动指定（推荐）：创建时明确指定类型
• 自动检测（可选）：系统可以使用 LLM 自动检测某些类型（主要用于评估和索引阶段）

1.4 Guidelines 的作用域

• Agent-Scoped：代理级别的指南，适用于该代理的所有对话
• Journey-Scoped：只在特定 Journey 激活时才生效的指南
• Global：没有特定作用域的指南，适用于所有代理

1.5 Guidelines 的优先级和关系

Guidelines 可以建立优先级和依赖关系：

• 优先级关系：确保重要规则优先执行
• 依赖关系：Guideline 可以依赖其他 Guideline 或 Journey

注意：Guidelines 还可以与 Journeys 建立关系，这部分内容将在第二章详细介绍。

---

第二章：Journeys（对话流程）

2.1 什么是 Journeys？

Journey：结构化的多步骤对话流程，引导客户完成特定目标。Journeys 是一组 Guidelines 的逻辑组合，通过一个状态图维护进度。

核心组成部分：

1. Title（标题）：简短、描述性的名称
2. Conditions（条件）：上下文查询，确定何时应该激活 Journey
3. Description（描述）：描述 Journey 的性质
4. States & Transitions（状态和转换）：状态图，传达理想的流程

核心特性：

• 状态图模型：基于状态图定义对话流程
• 灵活导航：代理可以跳过状态、回溯或提前跳转
• 条件激活：通过上下文查询确定何时激活 Journey
• 平衡灵活性与控制：在灵活性和协议遵循之间取得平衡

2.2 Journey 的状态类型

2.2.1 Chat States（对话状态）

代理与客户交流的状态，用于收集信息或提供指导。

2.2.2 Tool States（工具状态）

调用外部工具执行操作的状态，如查询数据库、调用 API 等。

2.2.3 Fork States（分支状态）

根据条件分支对话流程的状态，用于处理不同的场景。

2.3 Journey 的激活机制

2.3.1 激活条件

Journey 的激活条件实际上是观察性 Guidelines。当 Journey 的激活条件 Guideline 匹配成功时，Journey 被激活。

激活过程：

1. 系统评估所有 Guidelines（包括 Journey 的激活条件）
2. 如果 Journey 的激活条件 Guideline 匹配成功，Journey 被激活
3. 重要：所有匹配条件的 Journey 都会被激活，不限制数量
4. 多个 Journey 可以同时激活，每个激活的 Journey 都会独立处理其状态选择

2.3.2 Journey 状态投影为 Guidelines

Journey 的每个节点（Node）和转换（Edge）会被自动投影成 Guidelines：

• 节点动作 → Guideline 的动作
• 边条件 → Guideline 的条件

状态图投影生成的 Guidelines 是有逻辑关系的，这些关系通过 follow_ups 字段保存在 Guideline 的 metadata 中，反映了状态图的结构。

2.3.3 Journey 状态选择机制

重要：每个 Journey 在每次交互中只会选择一个状态转化为 Guidelines 给 agent。

执行时机：Journey 状态选择是在 Guideline 匹配过程中进行的，作为 Guideline 匹配批次的一部分。

状态选择过程：

1. 评估当前状态完成度：调用 LLM 评估当前状态是否完成
2. 评估转换条件：如果当前状态已完成，评估所有可能的转换条件
3. 选择下一个状态：
   • 当前状态未完成 → 保持当前状态
   • Journey 应该结束 → 选择根节点（退出 Journey）
   • 当前状态已完成 → 选择匹配度最高的转换条件对应的目标状态
4. 更新 Journey 路径状态：将选中的状态添加到 journey_paths[JourneyId] 中
5. 生成状态 Guidelines：将选中的状态投影为 Guidelines

关键理解：

• ✅ 每个 Journey 每次交互只选择一个状态
• ✅ 状态选择是互斥的
• ✅ 多个 Journey 可以并行，每个 Journey 独立选择自己的状态

2.4 Guidelines 与 Journey 的关系

关系类型	说明
激活条件	Journey 的条件是观察性 Guideline
状态投影	Journey 状态自动转换为 Guidelines
作用域绑定	Guideline 绑定到特定 Journey
优先级	Guideline 可以优先于 Journey 状态
依赖关系	Guideline 可以依赖 Journey

使用场景对比：

• 使用 Guideline：简单的条件-动作规则、处理特殊情况、工具调用触发
• 使用 Journey：多步骤流程、结构化对话流程、需要状态管理

---

第三章：Recall and Matching Logic（召回与匹配逻辑）

3.1 概述

当用户发送消息时，Parlant 需要确定使用哪些 Guidelines 和 Journeys。这个过程涉及多个阶段的过滤和匹配，以确保只评估相关的规则，同时优化性能和成本。

3.1.1 核心原则

重要澄清：不是"先匹配 Journey 再匹配 Guideline"，而是：

1. 预测高概率 Journey（用于过滤 Guidelines，不是匹配）
2. 匹配 Guidelines（LLM 评估）
3. 激活 Journey（基于匹配结果）

关键区别：

• 预测 Journey：使用向量搜索或已有路径，快速找到可能相关的 Journey（用于优化）
• 匹配 Guidelines：使用 LLM 评估 Guideline 条件是否匹配（核心步骤）
• 激活 Journey：检查匹配的 Guideline ID 中是否有 Journey 的激活条件 ID

向量搜索不会导致不准确：

• 向量搜索只是用于性能优化，不会影响最终结果的准确性
• 向量搜索只用于预测"可能相关"的 Journey，用于减少需要评估的 Guidelines 数量
• 真正的匹配判断还是通过 LLM 评估 Guidelines 来完成的
• 如果向量搜索预测错误，系统会在补充匹配阶段自动处理，确保准确性

3.2 完整处理流程

当用户发送消息时，系统按照以下步骤处理：

用户消息
  ↓
[阶段 1] 加载上下文
  - 加载代理、会话、客户信息
  - 检查是否有激活的 Journey 路径
  ↓
[阶段 2] 获取可用 Journey
  - 查询该代理的所有可用 Journey
  ↓
[阶段 3] 标签过滤 - 加载相关 Guidelines
  - 代理特定 Guidelines
  - 全局 Guidelines
  - Journey 关联的 Guidelines
  ↓
[阶段 4] 概率过滤 - 确定高概率 Journey
  ├─ 情况A：有激活的 Journey 路径 → 使用这些 Journey
  └─ 情况B：无激活路径 → 向量搜索找到最相关的 Journey（top_k=1）
  ↓
[阶段 5] 过滤 Guidelines
  - 保留：高概率 Journey 相关的 Guidelines + 全局 Guidelines
  - 过滤掉：低概率 Journey 相关的 Guidelines
  ↓
[阶段 6] LLM 语义匹配 - 评估 Guidelines
  - 对过滤后的 Guidelines 进行分类和批次处理
  - 使用 LLM 评估每个 Guideline 的条件是否匹配
  - 生成匹配结果（分数、理由）
  ↓
[阶段 7] 激活 Journey
  - 检查匹配的 Guidelines 中是否有 Journey 的激活条件
  - 如果有，激活对应 Journey
  ↓
[阶段 8] 补充匹配（如果需要）
  - 如果低概率 Journey 被激活，加载其 Guidelines 并重新匹配
  ↓
[阶段 9] 关系解析
  - 加载依赖和优先级相关的 Guidelines
  ↓
[阶段 10] Journey 状态选择（在 Guideline 匹配过程中进行）
  - 对于每个激活的 Journey，调用 LLM 评估当前状态完成度并选择下一个状态
  - 更新 Journey 路径状态
  - 将选中的状态投影为 Guidelines
  ↓
[阶段 11] 工具调用（如果有工具关联的 Guidelines）
  - 提取参数 → 调用工具 → 获取结果
  - 如果需要，返回阶段 6 重新评估
  ↓
[阶段 12] 生成响应
  - 使用所有匹配的 Guidelines 和 Journey 状态
  - 生成最终响应

3.3 多阶段过滤机制

3.3.1 阶段 1：标签过滤（Tag-based Filtering）

目的：只加载与当前上下文相关的 Guidelines

加载的 Guidelines：

• 代理特定的 Guidelines
• 全局 Guidelines
• Journey 关联的 Guidelines

效果：从所有 Guidelines 减少到代理相关的 Guidelines（例如：从 1000 个减少到 200 个）

3.3.2 阶段 2：概率过滤（Probability-based Pruning）

目的：基于 Journey 激活概率进一步过滤 Guidelines

判断高概率 Journey：

• 情况 A：已有激活的 Journey 路径 → 使用这些 Journey
• 情况 B：无激活路径 → 向量搜索找到最相关的 Journey（默认 top_k=1）

过滤 Guidelines：

• 保留：高概率 Journey 相关的 Guidelines + 全局 Guidelines
• 过滤掉：低概率 Journey 相关的 Guidelines

关键理解：

1. 通过向量选择 Journey，就默认选择了挂载在 Journey 上的 Guidelines
2. 不挂在 Journey 上的 Guidelines 会全量通过 LLM 匹配（全局 Guidelines）
3. 挂载在低概率 Journey 上的 Guidelines 会被过滤掉（如果低概率 Journey 后来被激活，会在补充匹配阶段重新加载）

为什么 Journey 使用向量搜索，而 Guidelines 不使用？

核心原因：

1. 数量差异：Journey 数量少（几十到几百个），Guidelines 数量多（成千上万个）
2. 用途不同：
   • Journey 向量搜索 = 粗筛选（性能优化），不需要精确匹配
   • Guidelines LLM 匹配 = 精筛选（准确性保障），需要精确的语义理解
3. 成本优化：向量搜索成本低，LLM 评估成本高。策略是先用便宜的向量搜索过滤 Journey，再用 LLM 评估少量过滤后的 Guidelines
4. 准确性保障：即使向量搜索预测错误，补充匹配机制也会自动纠正，确保最终结果的准确性

3.3.3 阶段 3：初始匹配（Initial Matching）

目的：对过滤后的 Guidelines 进行匹配评估

过程：

1. Guidelines 分类：观察性、可操作、已应用、客户依赖型等批次
2. 批次处理：使用批次处理优化 LLM 调用
3. LLM 评估：对每个 Guideline 的条件进行评估，判断是否匹配当前上下文
4. 生成匹配结果：返回匹配成功的 Guidelines，包括匹配分数和理由

3.3.4 阶段 4：补充匹配（Supplemental Matching）

目的：如果低概率 Journey 被激活，进行额外的匹配

触发条件：低概率 Journey 的激活条件 Guideline 匹配成功

过程：

• 加载新激活 Journey 相关的 Guidelines
• 进行额外的 LLM 匹配
• 确保不遗漏相关行为
• 合并到主匹配结果中

3.4 优化策略与效果

核心策略：先过滤，后匹配

优化效果：

• 标签过滤：从 1000 个减少到 200 个
• 概率过滤：从 200 个减少到 80 个
• 补充匹配：如果需要，额外评估 20 个
• 总计：只评估了 70/1000 = 7% 的 Guidelines

优化效果总结：

• ✅ 减少 LLM 调用：大幅减少成本（从 1000 个减少到 70 个）
• ✅ 降低延迟：减少需要处理的 Guidelines 数量，提高响应速度
• ✅ 提高准确性：专注于最相关的 Guidelines，减少噪音
• ✅ 智能回退：如果低概率 Journey 被激活，自动补充匹配，确保完整性

3.5 核心原则总结

原则 1：先过滤，后匹配

不是评估所有 Guidelines，而是先过滤出相关的 Guidelines。

原则 2：先预测 Journey，再匹配 Guidelines，最后激活 Journey

实际流程是：预测高概率 Journey → 过滤 Guidelines → 匹配 Guidelines → 激活 Journey。

原则 3：匹配决定激活

Journey 的激活由其条件 Guidelines 的匹配结果决定。

原则 4：Guidelines 优先于 Journey 状态

Guidelines 被视为更具体的行为覆盖，如果 Guideline 匹配，通常会优先于 Journey 状态。

原则 5：迭代优化

工具调用后可能触发重新评估，确保基于最新信息做出决策。

---

总结

本文档详细介绍了 Parlant 的三个核心概念：

1. Guidelines（行为准则）：用自然语言定义的上下文规则，指导代理在特定情况下的行为
2. Journeys（对话流程）：结构化的多步骤对话流程，引导客户完成特定目标
3. Recall and Matching Logic（召回与匹配逻辑）：确定使用哪些 Guidelines 和 Journeys 的完整流程

这三个概念共同构成了 Parlant 的行为建模框架，确保了 AI 代理能够可靠地遵循业务规则和预期行为。