如何让 Parlant 选中正确的 canned response模板字段与 signals 的用法【免费下载链接】parlantBuild reliable customer-facing AI agents with Parlant: an interaction control harness optimized for controlled, consistent, and predictable LLM interactions.项目地址: https://gitcode.com/GitHub_Trending/pa/parlant你给 Parlant agent 配置了一组 canned response 模板但实际对话中它总是选中不相关的那一条或者期望的那条模板根本没出现在候选列表里。本文以 Canned Responses 文档 为主线讲清 Parlant 选择 canned response 的机制并用两个手段修正选择结果用模板字段template fields让候选池自动收窄、用signals让期望的模板在检索阶段被召回。适用环境Python 3.10已按 安装文档 完成pip install parlant并设置了OPENAI_API_KEY。先理解选择流程错误发生在哪一步Canned response 的选择分 4 个阶段agent 基于当前情境交互、guidelines、工具结果等先起草一条 fluid 草稿消息draft message引擎根据草稿消息检索最相关的 canned response 模板作为候选引擎渲染候选模板用工具提供的字段值做替换agent 基于草稿消息在候选中挑出最贴合的一条。也就是说选错只有两个可能位置候选检索阶段召回错了第 2 步或者草稿消息本身就偏了第 1 步。模板字段主要解决第 2、3 步signals 解决第 2 步草稿质量靠 guidelines、journeys、tools、glossary 和 agent description 等常规控制机制解决。准备一个最小可运行的起点# main.py import asyncio import parlant.sdk as p async def main(): async with p.Server() as server: agent await server.create_agent( nameMy Agent, descriptionAn agent that uses canned responses, composition_modep.CompositionMode.STRICT, # or FLUID or COMPOSITED ) asyncio.run(main())export OPENAI_API_KEYYOUR_API_KEY python main.pycomposition_mode决定模板用法的严格程度模式行为文档给出的适用场景Fluid优先从 canned response 中选找不到合适匹配时回退到自由生成保持流畅的同时控制特定场景边做边用 fluid 生成补充 utterance 的建议Composited只用候选模板改写草稿的风格语气敏感的场合Strict只能输出模板中的内容无匹配时发送可自定义的 no-match 消息高风险、不能容忍任何幻觉的场景文档建议高风险场景从 strict 开始后续可平滑切换到更 fluid 的模式。本文的选择控制手段在三种模式下都适用。用模板字段收窄候选池模板是静态文本加动态字段的字符串字段按来源分三类。标准字段std.前缀展示对话上下文中的动态信息文档列出的可用值std.customer.name客户名未注册客户显示Gueststd.agent.nameagent 名std.variables.NAME名为NAME的变量内容std.missing_params字符串列表基于 Tool Insights 列出缺失的工具参数名await agent.create_canned_response( templateHi {{std.customer.name}}, Yes, this product is available in stock. )工具/检索器字段保证选中项与数据状态一致工具或 retriever 的结果可以通过ToolResult的canned_response_fields属性向模板提供动态值。这是文档强调的关键机制引用了上下文中不存在的字段的响应永远不会被选中即使它与草稿消息语义相似。p.tool def get_account_balance(context: p.ToolContext) - p.ToolResult: balance 1234.5 return p.ToolResult( # Note that you must still provide the result in the data field, # as this is what will inform the agent when evaluating guidelines, # calling tools, as well as when generating the draft message. data{fAccount balance is {balance}}, # Here you provide dynamic values specifically for template field substitution canned_response_fields{account_balance: balance}, )模板中按字段名引用await agent.create_canned_response(templateYour current balance is {{account_balance}})注意data仍然必须提供——它是 agent 评估 guidelines、调用工具和生成草稿消息的依据canned_response_fields只是专门给模板替换用的。ToolResult完整属性说明见 Tool Result 文档。由此得到文档给出的保证性结论在 strict 模式下只要successful_transaction字段没有被一次成功运行的工具调用提供agent 就绝不可能输出引用{{successful_transaction.id}}的消息。换句话说把响应模板和工具的字段协调好就能避免 agent 编造关于数据或状态的说法。工具直接返回完整候选响应如果目标是基于工具输出生成完整响应而不只是填字段文档指出这在复杂问答检索场景中常见用canned_responses属性直接返回整条候选p.tool def get_answer(context: p.ToolContext, question: str) - p.ToolResult: answer The answer to your question is.... return p.ToolResult( dataanswer, # Make the answer available as a complete canned response candidate canned_responses[answer], )可选进阶Jinja2 语法处理列表字段模板由 Jinja2 引擎渲染可以写循环等语法。文档示例工具返回canned_response_fields{toppings: toppings}toppings是列表模板写成await agent.create_canned_response( templateWe have the following toppings {% for t in toppings %}\n- {{t}}{% endfor %} )另外generative.前缀的字段如{{generative.item_name}}由 LLM 根据字段名和上下文自动推断值适合在 strict 模板里引入受控的局部生成。用 signals 解决模板召回不到的问题有时模板本身与草稿消息足够接近能进入候选列表但如果模板里含有字段替换如Your current balance is {{account_balance}}语义相似度比较会更困难期望的那条模板可能检索不到。signals 就是为此设计的每个 signal 本质上是一条草稿消息示例告诉引擎这条响应适合匹配这些草稿。检索候选时引擎会同时看 signals只要某条响应有与草稿消息非常接近的 signal即使响应本身形式差异很大也会被召回为候选。创建 canned response 时通过signals参数传入await agent.create_canned_response( templateYes, weve got this item in stock! Let me know if you need any help finding it., signals[We do have it in stock, We do! Do you need help finding it?], )SDK 中create_canned_response的完整参数为template、tags、signals、metadata、field_dependencies见 sdk.py。REST API 对 signals 的字段描述是 A sequence of signals associated with the canned response, to help with filtering and matching见 API 定义。写 signals 的原则来自文档的表述signal 是草稿消息的示例所以应写成 agent 起草消息时的口吻如 We do have it in stock而不是写成客户问句或功能说明。可选用 journey 作用域进一步缩小候选集如果模板总量很大可以把 canned response 挂到具体 journey 上使其只在对应 journey 激活时可用——文档明确说这能收窄可选响应集、提高选中期望响应的概率await journey.create_canned_response(templateTEXT)还可以把响应关联到 journey 内的具体状态两种模式见 Journeys 文档Explicit Consideration在该状态下关联的响应总是被纳入选择考虑——在journey或agent对象下创建并通过state.transition_to(..., canned_responses[...])关联Exclusive Consideration仅在该状态下考虑关联的响应其他时间一律不用——在server对象下创建并同样关联到状态await state.transition_to( chat_stateAsk if they have a destination in mind, canned_responses[ await server.create_canned_response( templateWhat destination are you interested in?, ), ], )验证看草稿消息看 no-match 行为文档给出的检查方法是回到选择流程的第 1 步在集成 UIhttp://localhost:8800中检查生成的草稿消息看 agent 在选择前想说什么。这是判断问题出在哪一步的依据草稿消息就偏离预期去调整 guidelines、journeys、tools、glossary 或 agent description 等控制草稿生成的机制草稿消息合理但期望模板不在候选中给该模板补 signals或检查模板引用的字段是否已由本次会话中的工具调用通过canned_response_fields提供——字段不在上下文中时该模板永远不可能被选中这不是故障而是设计行为。在 strict 模式下还有一个内置信号找不到合适模板时 agent 会发送 no-match 消息。频繁出现 no-match 说明候选池覆盖不足或检索未召回。no-match 消息有两种自定义方式async def initialize_func(c: p.Container) - None: no_match_provider c[p.BasicNoMatchResponseProvider] no_match_provider.template My custom no-match response. async with p.Server( initialize_containerinitialize_func, ) as server: ...需要按上下文动态生成 no-match 响应时继承p.NoMatchResponseProvider并实现get_template(self, context: p.LoadedContext, draft: str | None)再通过configure_container注入。文档提醒p.LoadedContext访问引擎内部状态的接口在未来版本可能变化自定义实现后续可能需要同步调整。限制与边界字段缺失即永不选中这是避免幻觉的设计但也意味着依赖工具字段的模板只在对应工具成功运行过的会话中可见signals 改善的是检索召回不改变第 4 步 agent 在候选中的最终裁决——候选召回正确后仍选错时问题应回到草稿消息质量本文所有手段模板字段、signals、journey 作用域与 composition mode 无关从 strict 切换到 fluid/composited 时这些配置继续生效。更多字段类型与 no-match provider 细节见 Canned Responses 文档ToolResult属性data、metadata、control、canned_responses、canned_response_fields的完整说明见 Tools 文档。【免费下载链接】parlantBuild reliable customer-facing AI agents with Parlant: an interaction control harness optimized for controlled, consistent, and predictable LLM interactions.项目地址: https://gitcode.com/GitHub_Trending/pa/parlant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考