ACI：Agent-Computer Interface

Q: 「ACI：Agent-Computer Interface」要解决的关键问题是什么？

工具是 Agent 和世界之间的契约。像设计人机界面一样设计 Agent 界面 让这个结论先证明自己值得留下。 把这一页当成决策工具，而不是需要背下来的定义。把概念连到一个真实任务、一个可观察结果，以及一个能改变你判断的失败上。 写下一个问题：试完这个方法后，你能用什么证据回答它？

本页解决的问题

先给结论

「ACI：Agent-Computer Interface」要解决的关键问题是什么？

工具是 Agent 和世界之间的契约。像设计人机界面一样设计 Agent 界面

判断标准

让这个结论先证明自己值得留下。把这一页当成决策工具，而不是需要背下来的定义。把概念连到一个真实任务、一个可观察结果，以及一个能改变你判断的失败上。

下一步

写下一个问题：试完这个方法后，你能用什么证据回答它？

常见误区

结论听起来很完整，却没有检查最关键的假设。

核心概念：工具是 Agent 和世界之间的契约

传统软件开发中，我们花大量精力设计用户界面（HCI）：按钮放在哪里、文案怎么写、交互怎么反馈。但当 Agent 成为系统的用户时，界面变成了工具定义。工具的名字、参数、描述，就是 Agent 的用户界面。

HCI 人 → 系统

人类通过按钮、表单、菜单与系统交互。UI 设计的好坏直接影响用户体验。

用户点击「查天气」按钮 → 系统调用 getWeather("NYC") → 返回结果给用户

确定性：相同操作 → 相同结果

ACI Agent → 系统

Agent 通过工具定义（名称、参数、描述）与系统交互。工具设计的好坏直接影响 Agent 表现。

用户说：「要不要带伞？」 → Agent 思考：需要调天气工具吗？ → 先问用户在哪个城市？ → 调用 get_weather(city="上海") → 综合判断后回答

非确定性：相同问题 → 不同调用路径

"Plan to invest as much effort into your Agent-Computer Interface (ACI) as you would into a Human-Computer Interface (HCI)."

工具和传统 API 的根本区别

用户说「要不要带伞」时，Agent 的决策过程

用户在哪？

如果对话历史中没提到位置，Agent 可能先问「你在哪个城市？」，再决定是否调工具。

需要调天气工具吗？

如果上一轮刚查过天气，Agent 可能直接用缓存结果回答，跳过工具调用。

调哪个工具？

是调 get_weather 还是 get_forecast？当前天气 vs 未来预报，工具名和描述决定了 Agent 的选择。

参数怎么填？

city 参数应该填「Shanghai」还是「上海」？格式不清晰时 Agent 经常出错。

传统 API 是确定性的：开发者写 getWeather("NYC")，每次执行路径完全一样。Agent 工具是非确定性的：模型需要理解什么时候用、怎么用，这完全取决于工具的设计质量。

工具设计四原则

PRINCIPLE 01

给模型足够的 Token 空间想清楚

模型生成参数是逐 Token 进行的，一旦开始写就很难回头修改。工具设计应该让模型在写复杂参数前，先写简单的方向性参数。

反例：第一个参数就要求写 500 行代码补丁
正例：先写 file_path、再写 change_type、最后写 content

PRINCIPLE 02

格式贴近模型的训练数据

模型在训练时见过大量自然语言和常见代码格式。工具参数格式越接近这些熟悉的模式，模型越不容易出错。

反例：用自定义 DSL 描述文件变更
正例：用标准 unified diff 格式，模型在训练数据中见过无数次

PRINCIPLE 03

避免不必要的格式开销

不要让模型做数行数、JSON 转义这类机械操作。模型不擅长精确计数，强迫它做只会增加出错概率。

反例：要求 {"start_line": 15, "end_line": 23} 精确行号
正例：用唯一的上下文字符串匹配目标位置

PRINCIPLE 04

Poka-yoke（防呆设计）

源自丰田生产系统的理念：通过改变设计，让错误更难发生。与其期望模型不犯错，不如让工具本身就不容易用错。

反例：参数接受相对路径（模型经常搞错当前目录）
正例：只接受绝对路径，从源头消除歧义

真实案例：SWE-bench 中的一个改动

文件路径：相对路径 vs 绝对路径

BEFORE -- 相对路径

{ "tool": "edit_file", "path": "src/utils/helper.py", "content": "..." }

Agent 频繁搞错当前工作目录，导致编辑错误文件或文件找不到

AFTER -- 绝对路径

{ "tool": "edit_file", "path": "/repo/src/utils/helper.py", "content": "..." }

消除路径歧义，工具调用从频繁出错变成几乎完美

这个改动的代码量极小：只是把参数从接受相对路径改为要求绝对路径。但效果巨大：一个参数设计的改变，让整个 Agent 的可靠性大幅提升。这就是 Poka-yoke 的力量。

工具描述的学问

业界最佳实践建议：像给一个聪明但没有上下文的初级开发者写文档一样写工具描述。这个开发者什么都不知道，但理解力很强，你需要告诉他所有前提条件。

好的工具描述应该包含

示例用法：具体的输入输出样例，让模型一看就会

边界情况说明：输入为空怎么办？找不到结果返回什么？

输入格式要求：日期用 ISO 8601 还是时间戳？路径用绝对还是相对？

和其他工具的区别：「用 search_code 搜代码，用 search_files 搜文件名，不要搞混」

何时不该用这个工具：「如果只需要检查文件是否存在，用 file_exists；read_file 留给需要读取内容的场景」

工具描述对比

差的工具描述

{ "name": "search", "description": "Search for things" }

模型不知道搜什么（代码？文件？网页？），参数格式不清楚，和其他搜索工具分不清

好的工具描述

{ "name": "search_code", "description": "Search for code patterns across the repository using regex. Returns matching file paths and line numbers. Use search_files for filename matching instead. Example: search_code({ pattern: 'def process_', file_glob: '*.py' })" }

名字精确、描述清晰、有示例、有和其他工具的边界说明

工具设计的投入应该和 Prompt 设计一样多。工具名称、参数结构、描述文案，都是 Agent 的用户界面。一个参数的改动可能让 Agent 从不可用变得可靠，正如 SWE-bench 中的绝对路径案例所示。

「核心概念：工具是 Agent 和世界之间的契约」为什么要看操作

「传统软件开发中，我们花大量精力设计用户界面（HCI）：按钮放在哪里、文案怎么写、交互怎么反馈。但当 Agent 成为系统的用户时，界面变成了工具定义。工具的名字、参数、描述，就是 Agent 的用户界面」把结构落到了一个具体动作。这里真正要比较的不是名词谁更高级，而是数据如何被放置，以及最常发生的操作需要走多远。

读懂结构，要同时看访问方式和变化方式

「业界最佳实践建议：像给一个聪明但没有上下文的初级开发者写文档一样写工具描述。这个开发者什么都不知道，但理解力很强，你需要告诉他所有前提条件」揭示了一个容易被忽略的取舍：按位置读取、按键查找、从两端进出、插入新元素和遍历关系，适合的组织方式并不相同。一个结构在某个操作上很快，不代表它在所有操作上都快。

把规模和更新频率一起算进去

实践时可以把「业界最佳实践建议：像给一个聪明但没有上下文的初级开发者写文档一样写工具描述。这个开发者什么都不知道，但理解力很强，你需要告诉他所有前提条件」当作边界提醒：先写下数据量、最常用的操作和允许的延迟，再看 AI 给出的结构是否真的匹配。

从「核心概念：工具是 Agent 和世界之间的契约」走到「HCI 人 → 系统」

「核心概念：工具是 Agent 和世界之间的契约」先把问题落在「传统软件开发中，我们花大量精力设计用户界面（HCI）：按钮放在哪里、文案怎么写、交互怎么反馈。但当 Agent 成为系统的用户时，界面变成了工具定义。工具的名字、参数、描述，就是 Agent 的用户界面」上；到了「HCI 人 → 系统」，讨论继续推进到「人类通过按钮、表单、菜单与系统交互。UI 设计的好坏直接影响用户体验。用户点击「查天气」按钮 → 系统调用 getWeather("NYC") → 返回结果给用户确定性：相同操作 → 相同结果」。两段连起来，重点就不只是记住一个结论，而是看清它成立所依赖的条件。

把这条判断带到下一个场景

遇到一个新的数据结构时，不要从定义开始背。先写出最频繁的操作，再估计数据量和更新方式，最后检查结构是否让这三个条件同时成立。

「核心概念：工具是 Agent 和世界之间的契约」：传统软件开发中，我们花大量精力设计用户界面（HCI）：按钮放在哪里、文案怎么写、交互怎么反馈。但当 Agent 成为系统的用户时，界面变成了工具定义。工具的名字、参数、描述，就是 Agent 的用户界面
「HCI 人 → 系统」：人类通过按钮、表单、菜单与系统交互。UI 设计的好坏直接影响用户体验。用户点击「查天气」按钮 → 系统调用 getWeather("NYC") → 返回结果给用户确定性：相同操作 → 相同结果
「工具描述的学问」：业界最佳实践建议：像给一个聪明但没有上下文的初级开发者写文档一样写工具描述。这个开发者什么都不知道，但理解力很强，你需要告诉他所有前提条件

最后的「工具描述的学问」把讨论落到「业界最佳实践建议：像给一个聪明但没有上下文的初级开发者写文档一样写工具描述。这个开发者什么都不知道，但理解力很强，你需要告诉他所有前提条件」。回看这条线索时，最值得保留的是：当输入、规模或风险改变，哪些判断需要重新做一遍。

标记为已学完 阅读进度会自动记录

文章讨论

读到这里，留下一个判断。

把刚想明白的地方、还没想通的问题，留给下一位一起学习的人。

↗

正在讨论 ACI：Agent-Computer Interface 可靠 Agent 的工程模式

3条讨论文章讨论 · 与共学社区同步

在共学社区查看

Asha Morgan内容编辑2026年8月20日

观点实践记录

我把这篇文章里的一个判断改写成了今天可以验证的小实验。比记住结论更有用的是，知道下一步要观察什么。

文章讨论7 有帮助

Lin Harper独立开发者2026年8月18日

观点观点

读完以后我先回头找它成立的条件，而不是直接把方法搬进项目。这个顺序让后面的取舍清楚很多。

文章讨论5 有帮助

Kiki Moore产品运营2026年8月15日

问题问题

如果把这个判断放到真实工作里，最先需要补的约束是什么？我想知道从阅读到第一次实践之间，哪一步最值得先做。

文章讨论4 有帮助