工具契约：参数能进来，结果也要查

从已有记录继续深入

9 月 17 日的学习摘要已经出现输入模型、输出模型与统一结果结构。这篇补一套可复现的配套练习，帮助检查这些概念怎样配合；它独立于第 53 课历史代码，不表示原有 Agent 已完成相同改造。

练习只执行离线整数乘法，不连接模型、数据库或天气 API。三个可靠性专题使用同一份程序，避免每篇换一套命名和错误规则。

一次调用经过哪些边界

工具名称与参数字典
→ 在注册表查找已允许的工具
→ 校验输入类型、字段和范围
→ 执行函数
→ 校验输出结构
→ 返回明确的成功或失败对象

Schema 是提供给调用方的说明，输入校验是执行前的实际检查。工具名称也要查注册表，不根据外部字符串动态执行代码。权限判断还需要独立实现；有注册表不代表已经有用户鉴权。

为输入与输出各写一个模型

from pydantic import BaseModel, ConfigDict, Field

class MultiplyInput(BaseModel):
    model_config = ConfigDict(strict=True, extra="forbid")
    a: int = Field(ge=-10000, le=10000)
    b: int = Field(ge=-10000, le=10000)

class MultiplyOutput(BaseModel):
    model_config = ConfigDict(strict=True, extra="forbid")
    value: int

args = MultiplyInput.model_validate({"a": 6, "b": 7})
data = MultiplyOutput.model_validate({"value": args.a * args.b})
print(data.model_dump())

本例用 model_validate 校验 Python 字典。严格整数输入会拒绝数字字符串与布尔值；extra="forbid" 拒绝未声明的字段。限制乘数范围是本练习的设计选择，并非乘法或 Pydantic 的默认要求。

严格模式文档和配置文档分别解释转换与额外字段行为。不同类型及 JSON 输入可能有不同规则，不要把一个整数示例推广为所有类型。

失败要说明发生在哪一层

统一结果也应限制内部矛盾。练习分别定义 Success 和 Failure：成功必须携带 MultiplyOutput，error 只能为 None；失败 data 只能为 None，并提供固定错误类别。测试会检查“成功却带错误”“失败却带数据”是否被拒绝。

输出结构合格仍不代表计算一定正确。返回整数 41 也符合 value 的类型，但不符合 6×7 的预期，因此还需要结果断言。契约检查与业务测试解决不同问题。

获取文件并运行

把三个文件保存到同一个练习文件夹：

• 主程序 agent_reliability_demo.py
• 测试 test_agent_reliability.py
• 依赖 requirements.txt

本轮使用 Python 3.12.14、Pydantic 2.13.5 验证。建议创建独立虚拟环境，不改已有项目的依赖。

python -m venv .venv
# Windows PowerShell：不需要激活脚本
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe agent_reliability_demo.py
.venv\Scripts\python.exe -m unittest -v test_agent_reliability

macOS / Linux 把后面三行的解释器替换为 .venv/bin/python；本轮未在这两个系统实际运行。下载 .py 时若浏览器显示文本，保存时保留文件名和 UTF-8 编码，不要多出 .txt 后缀。

主程序会输出两条结果与对应日志：正常乘法得到 42；字符串参数得到 input_validation。随机运行标识和耗时每次都会不同。依赖安装需要网络，练习执行不需要网络或 API 密钥。

检查结果与学习顺序

配套程序的 14 项 unittest 测试已在上述环境通过，覆盖正常结果、非法输入、输出错误、重试、取消和日志等。这是本次新练习的测试，不是对历史 Agent 系统重新验收。

接下来读异常、超时与有限重试，再看一次运行的结构化日志。完整函数包含的细节以下载文件为准，页面代码只是输入与输出模型的讲解片段。

来源

主题承接个人笔记《Agent 学到哪里了---9.17》。技术行为核对自 Pydantic Models、严格模式与配置官方文档；程序和测试为本轮配套练习。核对日期：2026-09-21。