AI Agent / 系统课时

实现订单查询工具

实现订单查询工具

订单查询工具是 Agent 与订单系统之间的安全边界:它既要正确调用上游接口,也要防止模型传入越权身份或把敏感字段带回上下文。本课实现一个 Python 只读查询工具,验证身份范围、参数和最小数据返回。

学习目标

  • 实现带连接等待上限、服务端身份范围和参数校验的查询函数
  • 使用可信用户身份完成订单归属校验,阻断越权读取
  • 在查询时只选择业务需要的字段,避免读取手机号和地址

先约定订单服务契约

把代码保存为 order_tool.py。使用 Python 3.11 标准库和本地合成数据,无需真实 API。服务端认证后构造 Principal,再把它与候选订单号传给工具。调用者不能用模型参数覆盖租户或用户。

python
import re
import sqlite3
from contextlib import closing
from dataclasses import dataclass
from pathlib import Path
from tempfile import TemporaryDirectory

ORDER_ID = "ORD-20260904-001"
ORDER_PATTERN = re.compile(r"ORD-[0-9]{8}-[0-9]{3,12}")
STATUSES = {"PROCESSING", "SHIPPED", "DELIVERED"}


@dataclass(frozen=True)
class Principal:
    tenant_id: str
    user_id: str


@dataclass(frozen=True)
class Order:
    order_id: str
    status: str
    updated_at: str
    estimated_delivery: str | None


class OrderServiceError(RuntimeError):
    pass


def seed_demo(path):
    with closing(sqlite3.connect(path)) as db, db:
        db.execute("""
            CREATE TABLE orders (
                tenant_id TEXT NOT NULL, user_id TEXT NOT NULL, order_id TEXT NOT NULL,
                status TEXT NOT NULL, updated_at TEXT NOT NULL, estimated_delivery TEXT,
                private_address TEXT NOT NULL, PRIMARY KEY (tenant_id, order_id)
            )
        """)
        db.executemany("INSERT INTO orders VALUES (?, ?, ?, ?, ?, ?, ?)", [
            ("team-a", "USER-001", ORDER_ID, "SHIPPED",
             "2026-09-04T09:00:00Z", None, "synthetic address A"),
            ("team-b", "USER-001", ORDER_ID, "PROCESSING",
             "2026-09-04T08:00:00Z", None, "synthetic address B"),
        ])


class SQLiteOrders:
    def __init__(self, path):
        self.uri = Path(path).resolve().as_uri() + "?mode=ro"

    def read(self, statement, params=()):
        try:
            with closing(sqlite3.connect(self.uri, uri=True, timeout=0.25)) as db:
                return db.execute(statement, params).fetchone()
        except sqlite3.Error:
            raise OrderServiceError("order store unavailable") from None

    def ready(self):
        self.read("SELECT 1 FROM orders LIMIT 1")

    def query(self, order_id, principal):
        if not isinstance(order_id, str) or not ORDER_PATTERN.fullmatch(order_id):
            raise ValueError("invalid order ID")
        row = self.read(
            """SELECT order_id, status, updated_at, estimated_delivery
               FROM orders WHERE tenant_id = ? AND user_id = ? AND order_id = ?""",
            (principal.tenant_id, principal.user_id, order_id),
        )
        if row is None:
            return None
        if row[1] not in STATUSES:
            raise OrderServiceError("invalid order status")
        return Order(*row)


if __name__ == "__main__":
    with TemporaryDirectory() as temp:
        path = Path(temp) / "orders.sqlite3"
        seed_demo(path)
        orders = SQLiteOrders(path)
        print(orders.query(ORDER_ID, Principal("team-a", "USER-001")))
        print(orders.query(ORDER_ID, Principal("team-a", "USER-999")))

预期输出

text
Order(order_id='ORD-20260904-001', status='SHIPPED', updated_at='2026-09-04T09:00:00Z', estimated_delivery=None)
None

timeout=0.25 是 SQLite 等待数据库锁的秒数,完整请求的截止时间需在服务层单独控制。接真实 HTTP 上游时还需配置连接和读取预算,校验返回对象、订单标识、权限与时间字段。身份不匹配和无记录沿同一对外路径,后续编排不会用缓存或模型猜测补上状态。

订单查询工具安全链路

下一课从相同模块导入 SQLiteOrders 和 Principal。若改接订单 API,仍保持相同工具签名及失败契约。服务凭证只在可信适配层加载,API 返回的原始对象、个人字段和内部异常都不进入模型上下文。

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

目录与阅读设置

阅读设置

17

记录一个想法

实现订单查询工具

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

登录哪都通