参数校验与结构化错误：告诉 Agent 哪里失败了

{"name": "read_note", "arguments": {"note_id": "n1"}}

{
  "ok": false,
  "call_id": "call-1",
  "error": {
    "code": "invalid_arguments",
    "stage": "shape",
    "retryable": false
  }
}

mkdir -Force "F:\学习\agentdepth-l2-validation"
cd "F:\学习\agentdepth-l2-validation"

"""按阶段处理笔记查询，并返回结构化结果。"""
from __future__ import annotations

import json


# 固定笔记按用户身份分组。
NOTES = {"u1": {"n1": "退款窗口为 7 天。"}, "u2": {"n2": "另一份私人笔记。"}}


def handle(raw: str, identity: str, call_id: str = "call-1", result_override: dict | None = None) -> dict:
    # 用同一种格式返回错误，调用方可以按 code 和 stage 分支处理。
    def fail(code: str, stage: str, retryable: bool = False) -> dict:
        return {"ok": False, "call_id": call_id, "error": {"code": code, "stage": stage, "retryable": retryable}}

    # 第一步：把 JSON 文本解析为 Python 值。
    try:
        request = json.loads(raw)
    except json.JSONDecodeError:
        return fail("invalid_json", "parse")
    # 第二步：选择工具并检查参数字段和类型。
    if not isinstance(request, dict) or request.get("name") != "read_note":
        return fail("unknown_tool", "route")
    arguments = request.get("arguments")
    if not isinstance(arguments, dict) or set(arguments) != {"note_id"}:
        return fail("invalid_arguments", "shape")
    note_id = arguments["note_id"]
    if not isinstance(note_id, str) or not note_id.strip():
        return fail("invalid_arguments", "shape")
    # 第三步：在当前用户的笔记范围内查找。
    if identity not in NOTES or note_id not in NOTES[identity]:
        return fail("forbidden_or_missing", "resource")
    # 第四步：检查结果对象、字段、编号对应关系和正文类型。
    result = result_override if result_override is not None else {"note_id": note_id, "text": NOTES[identity][note_id]}
    if (not isinstance(result, dict) or set(result) != {"note_id", "text"}
            or not isinstance(result["note_id"], str) or result["note_id"] != note_id
            or not isinstance(result["text"], str)):
        return fail("invalid_tool_result", "output")
    return {"ok": True, "call_id": call_id, "result": result}


if __name__ == "__main__":
    # 每条固定输入观察一种处理路径。
    cases = [
        ("valid", '{"name":"read_note","arguments":{"note_id":"n1"}}', "u1"),
        ("invalid_json", '{"name":', "u1"),
        ("extra_field", '{"name":"read_note","arguments":{"note_id":"n1","admin":true}}', "u1"),
        ("wrong_owner", '{"name":"read_note","arguments":{"note_id":"n1"}}', "u2"),
    ]
    for label, raw, identity in cases:
        print(json.dumps({"case": label, **handle(raw, identity)}, ensure_ascii=False))

python -X utf8 validation_lab.py

{"case": "valid", "ok": true, "call_id": "call-1", "result": {"note_id": "n1", "text": "退款窗口为 7 天。"}}
{"case": "invalid_json", "ok": false, "call_id": "call-1", "error": {"code": "invalid_json", "stage": "parse", "retryable": false}}
{"case": "extra_field", "ok": false, "call_id": "call-1", "error": {"code": "invalid_arguments", "stage": "shape", "retryable": false}}
{"case": "wrong_owner", "ok": false, "call_id": "call-1", "error": {"code": "forbidden_or_missing", "stage": "resource", "retryable": false}}

python -X utf8 -m unittest -v test_validation_lab.py