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

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