3.3 外部工具集成与扩展

3.3 外部工具集成与扩展

本节摘要：只会说话的系统停在玩具侧。Parlant 把外部工具嵌进规则激活与推理，而不是只提供一个函数钩子。对照通用 Agent 的自由 function calling、规则引擎的死接口编排，这里用装饰器注册、上下文入参、结果回写状态，让「先验证订单再退款」成为规则网络上的事实，而不是模型记忆。

本节目标

阅读完本节，你应当能够：

1. 读懂 @p.tool 概念示例里语义接口、上下文、结果封装三层信息
2. 画出规则匹配→条件验证→调度→回写的四段循环
3. 对照「只说不做」和「模型想调就调」两种失败
4. 说明工具粒度过粗过细如何把指南扭曲

闭环：感知之后必须能行动

天气、订单库、工单、法规检索——行动依赖外部能力。原文强调工具调用嵌在规则网络里：工具是执行者，也是状态更新的参与者，影响后续匹配。退换货：先验订单；已发货则查运单；未发货则退款。这不是提示词里的步骤列表，是激活条件依赖工具结果。

通用 Agent 也能多步调用，差别是谁写步骤。那边常由模型逐步规划，路径每次不同。这边步骤在指南与关系里，工具结果变成事实后再评估网络。规则引擎也能编排，但用户说「这东西我不要了」未必进得了「退货」节点——口语仍要 LLM，行动仍要工具。

import parlant.sdk as p

@p.tool
async def get_weather(context: p.ToolContext, city: str) -> p.ToolResult:
    # 真实项目里此处走异步 HTTP 客户端；不要用同步阻塞库
    summary = "晴，指定城市的温度摘要"
    return p.ToolResult(summary)
​

三层信息：参数定义槽位，可由规则或话语填充；ToolContext 带对话状态、用户、历史；ToolResult 可附带供后续条件判断的信息。注册后指南可写：「问某城市天气则调用该工具并传入城市名。」自然语言与代码映射，降低非程序员编排门槛——前提是工具已经由开发写好。

四段协同，以及异步契约

1. 意图识别与规则匹配，得到候选指南
2. 前置条件：可能依赖某次工具结果（仅已支付才允许退）
3. 调度执行并等待
4. 回写事实（订单状态=已发货），再评估网络

原文环境章强调工具必须是异步函数，主程序跑在事件循环。误用同步阻塞客户端会卡住循环。这不是风格问题，是部署事故。上下文里的会话与用户标识，在分布式下还涉及状态后端——第 4 章展开，这里先记住：工具里不要假装自己是全局唯一数据源。

⚠️ 常见坑：工具粒度过粗（一个「处理订单」包揽查、改、退）或过细（十个几乎相同的查询）。过粗则指南无法约束内部副作用；过细则指南组合爆炸。粒度应对齐业务可说清的一步。
💡 关键直觉：工具是乐谱上的音符，指南是乐句。音符太大，指挥没法微调；音符太碎，乐谱比曲子还长。

权限与沙箱仍适用第 2 章契约：写工具时声明副作用。查询天气与退款不能同等暴露。扩展新工具=实现函数+注册+补指南；缺指南的工具等于给模型（或误匹配）留暗门，生产上宁可未注册。

问题 能否把另一个大模型也封装成工具？

原文把「另一个推理端点」列为可能的工具形态。它仍应走契约与授权：当作生成类工具时，输出要再进风格校验与指南，不能因为「也是模型」就绕过网关。否则控制环在内部被短路。

问题 工具失败了，指南怎么办？

四段循环等待的是结果。超时与错误应写成上下文事实（查询失败），由指南决定道歉、重试还是转人工——不要让模型即兴编造物流状态。第 5 章性能节会回到超时与并发。

工具接入的发布检查单

新工具发布前：异步、契约、副作用级别、对应指南、失败口径、超时预算、权限角色、沙箱数据。缺一项就停。对照通用 Agent 「先能调通再补说明」，这里说明是上线门禁。调通只证明网络通，不证明许可图谱通。

粒度工作坊用业务语言切：把「处理订单」拆到客服能单独讲解的步骤。每一步一个工具。若讲解时必须说「这个按钮其实还会顺便……」，粒度就过粗。过细的症状是指南作者开始复制粘贴参数组合，那是该合并的信号。

结果回写要当事实，不当散文。订单状态、余额、是否已发货，用结构化字段进入上下文，供后续条件求值。若只把一段自然语言摘要写回，下一跳条件会再次依赖模型理解，控制环漏风。

把另一个模型当工具时，输出必须再进校验。翻译、摘要可以，直接当政策解释不行。短路验证层是集成里最隐蔽的回退到主角模型。代码评审专门找「内部又调了一次不受指南约束的生成」。

发布门禁
异步？契约完整？副作用分级？
至少一条指南引用？失败事实化？
超时有预算？角色可见性对？
预发用沙箱数据？审计事件有？
​

副作用分级演练

把现有工具分成只读、写状态、动资金或隐私三类，用不同网关策略。只读可较宽，写状态要身份依赖，动资金要人审或二次确认。演练时故意把写状态工具的指南写宽，看网关是否仍要身份。若指南一宽网关就放行，说明网关没独立策略，哲学上的守门人是假的。工具集成不是函数列表，是分级制度。没有分级，扩展越快，爆炸越近。

对照作业：工具发布门禁与分级

围绕「工具发布门禁与分级」，把四条路径再过一遍。表里每格都是可执行判断，不是形容词。读完请把你的项目钉进一格，不要钉在两格之间假装都占了。

把工具分成只读、写状态、动资金隐私三类，策略不同。指南写宽时网关仍要身份，守门人才是真的。

结果回写用结构化字段。只回散文，下一跳又把理解权交给模型，环就漏风。

钉列纪律：工具发布门禁

在「工具发布门禁」上，纯 prompt 把判断写进一段话，改的人必须会改提示，复盘只能翻聊天，口语进得来但口径会漂。通用 Agent 把判断交给循环，灵活的代价是越权与路径不可复现。规则引擎把判断写进分支，确定的代价是口语进不来、改口径要排期。Parlant 把判断写成指南与契约：业务改口径，未授权则无行动，复盘指轨迹。把这四句贴到工位上，比再记一组术语有用。

针对工具发布门禁，本周只做一件可验收的事：找出一条真实对话或工单，标注它今天落在哪一列；若要迁到第四列，缺的是指南、工具还是关系边。缺指南就写草稿，缺工具就列契约，缺关系就补消歧或依赖。不要同时开十条战线。最常见的伪装是文件名叫指南、真源仍是提示词，或者架构图上有网关、运行时模型仍直接调函数。用「改文本能否改行为」和「低权限点名是否被拒」两张试纸识破。识破了再谈优化与案例。优化在伪装上加速，只会让错误承诺更多；案例在伪装上复制，只会把新闻变成事故。

工具发布门禁的纪律是先钉列，再谈快。钉列需要抽检，抽检需要轨迹，轨迹需要审计真的在记抑制原因，而不只记最终回复。若没有抑制原因，排错会以为没写规则，其实是优先级压了。看得见「为什么没走另一条路」，才叫对照，才叫可控。把这句话写进值班手册，工具发布门禁才从概念变成岗位。对照驱动不是文风，是岗位制：模型是引擎和笔杆子，方向盘在指南与工具契约上。谁把方向盘又塞回提示词，谁就在工具发布门禁上退回第一列。

重点提炼

• 嵌在规则网：工具改状态，从而改下一跳
• 装饰器三层：槽位、上下文、结果封装
• 四段循环：匹配、验条件、执行、回写
• 必须异步：阻塞调用会拖垮事件循环
• 粒度对齐业务一步：过粗过细都扭曲指南
• 未写指南的工具不要进生产候选集

下一章把定制结果装进可运行系统：环境、Journey 蓝图、组件注册表。