AI Agent / 系统课时

编排查询与解释流程

编排查询与解释流程

本节把一次用户查询编排成可运行的 Agent 流程:先识别意图,再选择并调用工具,把关键结果写入状态,最后由解释层组织自然语言回复。完成后你会得到一个可执行的最小编排器,并能看清每一步的输入、输出与失败边界。

学习目标

  • 把意图识别、工具调用、状态更新和解释层串成单一查询流程
  • 用显式状态记录中间结果,避免工具输出在链路中丢失或被重复解释
  • 为未知意图、工具失败和空结果设计可控的降级路径

把查询拆成四个阶段

一个稳定的查询 Agent 不应让模型同时完成“理解问题、执行动作、记忆结果、组织答案”。更容易调试的做法是把职责拆开:意图层决定要做什么,工具层只负责取数据,状态层保存事实,解释层只读取状态并生成回复。

查询编排从意图到解释的四阶段流程

这里的关键不是阶段数量,而是每个阶段都有稳定契约。意图识别输出有限枚举;工具返回结构化事实;状态保存本轮可审计信息;解释层不能自行编造工具没有返回的数据。

实现最小编排器

把代码保存为 order_flow.py,与 order_tool.py 放在同一目录。本章接收结构化意图。以后可在入口前增加自然语言分类,但模型只能建议意图和订单号,所有输出仍走同一校验。编排器使用当前身份查询订单并记录当次结果。

python
from dataclasses import dataclass
from pathlib import Path
from tempfile import TemporaryDirectory

from order_tool import (
    ORDER_ID, ORDER_PATTERN, Order, OrderServiceError, Principal, SQLiteOrders, seed_demo,
)

STATUS_TEXT = {"PROCESSING": "处理中", "SHIPPED": "已发货", "DELIVERED": "已送达"}


@dataclass(frozen=True)
class State:
    status: str
    message: str
    order: Order | None = None


def handle(data, principal, orders):
    if principal is None:
        return State("unauthenticated", "请登录后再查询。")
    if not isinstance(data, dict) or data.keys() != {"intent", "order_id"}:
        return State("invalid_request", "请求字段无效。")
    if data["intent"] != "order_status":
        return State("unsupported_intent", "本助手仅查询订单状态。")
    order_id = data["order_id"]
    if not isinstance(order_id, str) or not ORDER_PATTERN.fullmatch(order_id):
        return State("invalid_request", "请提供有效订单号。")

    try:
        order = orders.query(order_id, principal)
    except TimeoutError:
        return State("lookup_timeout", "查询超时,请稍后再试。")
    except OrderServiceError:
        return State("lookup_unavailable", "暂时无法查询,请稍后再试。")
    if order is None:
        return State("order_unavailable", "无法查看该订单,请确认订单号和登录账号。")

    estimate = (
        f"预计送达时间:{order.estimated_delivery}。"
        if order.estimated_delivery else "暂未提供预计送达时间。"
    )
    return State("ok", f"订单 {order.order_id} 当前状态:{STATUS_TEXT[order.status]}。{estimate}", order)


if __name__ == "__main__":
    with TemporaryDirectory() as temp:
        db = Path(temp) / "orders.sqlite3"
        seed_demo(db)
        data = {"intent": "order_status", "order_id": ORDER_ID}
        print(handle(data, Principal("team-a", "USER-001"), SQLiteOrders(db)).message)
        print(handle({**data, "intent": "cancel_order"}, Principal("team-a", "USER-001"), SQLiteOrders(db)).status)

预期输出

text
订单 ORD-20260904-001 当前状态:已发货。暂未提供预计送达时间。
unsupported_intent

State 只记录当次请求的状态和可返回事实。不存在与无权访问统一为 order_unavailable。工具超时和数据库不可用分别标记。读不到状态时,不用上一轮结果填补。若之后要跨请求恢复,需另行设计租户与用户隔离的持久状态,按版本处理并发写入。

真实模型可选用于意图分类或组织说明。对固定状态,模板足以保证输出与工具事实一致。下一课从 handle() 入口验证项目契约。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

编排查询与解释流程

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通