案例分析一：Coding Agent 为什么总把 filename 传给 read_file(path)？

场景背景

我们做了一个 Coding Agent。

Tool：

def read_file(
    path: str,
):
    ...

Prompt 里只告诉模型：

你可以使用 read_file 读取文件。

运行中经常出现：

{
  "name": "read_file",
  "arguments": {
    "filename": "app.py"
  }
}

Harness 报：

unexpected keyword argument 'filename'

第一反应

很多人会说，“在 Prompt 里提醒模型参数叫 path。”

于是 System Prompt 又加：

read_file 的参数名一定是 path，不要使用 filename。

暂时有效。

以后 Tool 增加到 20 个，Prompt 开始充满：

A 工具参数叫...
B 工具参数叫...
C 工具不要传...

这条路很难维护。

正确改造

直接给模型正式 Schema：

{
  "name": "read_file",
  "description": "读取工作目录内指定文本文件",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string"
      }
    },
    "required": [
      "path"
    ]
  }
}

Provider 把它作为 Tool 定义传给模型。

模型现在不需要靠自然语言猜，参数名到底是什么。

Harness 仍然做校验

即便 Schema 已经正确，也不能：

read_file(**arguments)

无条件执行。

Harness 仍然：

Schema Validation
 ↓
Path Validation
 ↓
Registry Execute

如果模型仍然返回：

filename

就明确：

InvalidArguments

并作为 Observation 回去。

结果

错误率明显下降。

而且新增 Tool 不需要继续污染 System Prompt。

复盘与迁移

这个案例说明，参数协议应该由 Tool Schema 表达，而不是靠 Prompt 口头约定。

这和普通软件工程一样。

API 参数不应该只写在一段说明里。

应该尽量有机器可读协议。

Tool Schema 就是 Agent 工具世界里的机器可读 API 协议。