ACI: Agent-Computer Interface

THE QUESTION THIS PAGE ANSWERS

ANSWER FIRST

What is the key idea behind “ACI: Agent-Computer Interface”?

Tools are the contract between Agents and the world. Design Agent interfaces like you design human interfaces

DECISION RULE

Make the claim earn its place. Use this page as a decision aid, not a definition to memorize. Connect the idea to one real task, one observable result, and one failure that would change your mind.

TRY NEXT

Write one question you could answer with evidence after trying this idea.

WATCH FOR

A conclusion that sounds complete but leaves the key assumption untested.

Core Concept: Tools Are the Contract Between Agent and World

In traditional software development, we invest heavily in designing user interfaces (HCI): where to place buttons, how to write copy, how interactions should respond. But when an Agent becomes the user of a system, the interface becomes the tool definition. The tool's name, parameters, and description are the Agent's user interface.

HCI Human → System

Humans interact with systems through buttons, forms, and menus. The quality of UI design directly impacts user experience.

User clicks "Check Weather" button → System calls getWeather("NYC") → Returns result to user

Deterministic: same action → same result

ACI Agent → System

Agents interact with systems through tool definitions (name, parameters, description). The quality of tool design directly impacts Agent performance.

User says: "Should I bring an umbrella?" → Agent thinks: do I need the weather tool? → First asks: which city are you in? → Calls get_weather(city="Shanghai") → Makes holistic judgment and responds

Non-deterministic: same question → different call paths

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

The Fundamental Difference Between Tools and Traditional APIs

When a user says "Should I bring an umbrella?", the Agent's decision process

Where is the user?

If no location is mentioned in conversation history, the Agent may first ask "Which city are you in?" before deciding whether to call the tool.

Does it need to call the weather tool?

If the weather was just checked in the previous turn, the Agent may answer directly using cached results, skipping the tool call.

Which tool should it call?

Use get_weather or get_forecast? Current conditions vs. future forecast — the tool name and description determine the Agent's choice.

How to fill in the parameters?

Should the city parameter be "Shanghai" or "上海"? When the format is unclear, Agents frequently make mistakes.

Traditional APIs are deterministic: a developer writes getWeather("NYC") and the execution path is identical every time. Agent tools are non-deterministic: the model needs to understand when and how to use them — which depends entirely on the quality of the tool's design.

Four Principles of Tool Design

PRINCIPLE 01

Give the model enough Token space to think clearly

The model generates parameters token by token, and once it starts writing it is hard to go back. Tool design should let the model write simple directional parameters before tackling complex ones.

Anti-pattern: The first parameter requires a 500-line code patch
Best practice: Write file_path first, then change_type, and finally content

PRINCIPLE 02

Formats should match the model's training data

The model has seen large amounts of natural language and common code formats during training. The closer the tool parameter format is to these familiar patterns, the less likely the model is to make mistakes.

Anti-pattern: Using a custom DSL to describe file changes
Best practice: Use standard unified diff format — the model has seen it countless times in training data

PRINCIPLE 03

Avoid unnecessary formatting overhead

Don't ask the model to count lines or handle JSON escaping. Models are not good at precise counting — forcing them to do so only increases error rates.

Anti-pattern: Requiring exact line numbers like {"start_line": 15, "end_line": 23}
Best practice: Use unique surrounding context strings to identify target locations

PRINCIPLE 04

Poka-yoke (Mistake-proofing)

A concept from the Toyota Production System: redesign to make errors harder to occur. Rather than hoping the model won't make mistakes, design tools that are inherently difficult to misuse.

Anti-pattern: Parameters accepting relative paths (the model frequently gets the working directory wrong)
Best practice: Only accept absolute paths, eliminating ambiguity at the source

Real Case: A Change in SWE-bench

File Path: Relative Path vs. Absolute Path

BEFORE -- Relative Path

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

The Agent frequently got the working directory wrong, causing edits to the wrong file or file-not-found errors

AFTER -- Absolute Path

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

Path ambiguity eliminated; tool calls went from frequent errors to nearly flawless

The code change itself was tiny: simply switching a parameter from accepting relative paths to requiring absolute paths. But the effect was enormous: a single parameter design change dramatically improved the entire Agent's reliability. That is the power of poka-yoke.

The Art of Writing Tool Descriptions

Industry best practice recommends writing tool descriptions as if you are documenting for a smart but context-free junior developer. This developer knows nothing about the system but learns quickly — you need to tell them every prerequisite.

A good tool description should include

Usage examples: Concrete input/output samples that let the model understand at a glance

Edge case handling: What to do when input is empty? What is returned when no result is found?

Input format requirements: ISO 8601 or Unix timestamp for dates? Absolute or relative paths?

Differences from other tools: "Use search_code to search code, use search_files to search filenames — don't mix them up"

When NOT to use this tool: "If you only need to check whether a file exists, use file_exists; reserve read_file for when you need to read the content"

Tool Description Comparison

Poor tool description

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

The model doesn't know what to search (code? files? web pages?), the parameter format is unclear, and it can't be distinguished from other search tools

Good tool description

{ "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' })" }

Precise name, clear description, includes examples, and clarifies boundaries with other tools

Tool design deserves as much investment as Prompt engineering. Tool names, parameter structure, and description copy are all part of the Agent's user interface. A single parameter change can turn an unreliable Agent into a dependable one — as demonstrated by the absolute path case in SWE-bench.

Why “Core Concept: Tools Are the Contract Between Agent and World” depends on the operation

“In traditional software development, we invest heavily in designing user interfaces (HCI): where to place buttons, how to write copy, how interactions should respond.” makes the structure concrete. The useful comparison is not which name sounds more advanced, but how the data is arranged and how far the most common operation has to travel.

Read a structure through access and change

“Industry best practice recommends writing tool descriptions as if you are documenting for a smart but context-free junior developer .” exposes a trade-off that is easy to miss: reading by position, looking up by key, adding at either end, inserting in the middle, and traversing relationships do not favor the same organization. A structure that is fast for one operation is not automatically fast for all of them.

Count scale and update frequency together

Use “Industry best practice recommends writing tool descriptions as if you are documenting for a smart but context-free junior developer .” as a boundary check. Write down the data size, the dominant operation, and the latency you can accept before deciding whether an AI-generated structure actually fits.

From “Core Concept: Tools Are the Contract Between Agent and World” to “HCI Human → System”

“Core Concept: Tools Are the Contract Between Agent and World” grounds the problem in “In traditional software development, we invest heavily in designing user interfaces (HCI): where to place buttons, how to write copy, how interactions should respond. But when an Agent becomes the user of a sys…”. “HCI Human → System” then moves it toward “Humans interact with systems through buttons, forms, and menus. The quality of UI design directly impacts user experience. User clicks "Check Weather" button → System calls getWeather("NYC") → Returns…”. Together, they show that the lesson is not just a conclusion to remember, but a claim with conditions.

Carry the judgment into the next situation

When you meet a new data structure, do not begin by memorizing its definition. Write down the most frequent operation, estimate scale and update behavior, and check whether the structure satisfies all three conditions.

“Core Concept: Tools Are the Contract Between Agent and World”: In traditional software development, we invest heavily in designing user interfaces (HCI): where to place buttons, how to write copy, how interactions should respond. But when an Agent becomes the user of a sys…
“HCI Human → System”: Humans interact with systems through buttons, forms, and menus. The quality of UI design directly impacts user experience. User clicks "Check Weather" button → System calls getWeather("NYC") → Returns…
“The closing point”: Industry best practice recommends writing tool descriptions as if you are documenting for a smart but context-free junior developer . This developer knows nothing about the system but learns quickly — you need…

The final “The closing point” brings the discussion to “Industry best practice recommends writing tool descriptions as if you are documenting for a smart but context-free junior developer . This developer knows nothing about the system but learns quickly — you need…”. The useful thing to carry forward is knowing which judgments must be revisited when input, scale, or risk changes.

Mark as learned Your reading progress updates automatically

ARTICLE DISCUSSION

Leave one useful thought here.

Keep the idea that clicked, the question that stayed open, or a small note for the next learner.

↗

Discussing ACI: Agent-Computer Interface Engineering Patterns for Reliable Agents

3discussionsArticle discussion · synced with the Circle

View in the learning circle

Asha MorganContent editorAug 20, 2026

INSIGHTField note

I turned one judgment from this article into a small experiment I could run today. Knowing what to observe next is more useful than simply remembering the conclusion.

ARTICLE DISCUSSION7 helpful

Lin HarperIndie developerAug 18, 2026

INSIGHTInsight

After reading this, I first looked for the conditions behind the idea instead of copying the method into a project. That order made the later trade-offs much clearer.

ARTICLE DISCUSSION5 helpful

Kiki MooreProduct operationsAug 15, 2026

QUESTIONQuestion

When this judgment reaches real work, which constraint should be added first? I am curious which step matters most between reading and the first practical attempt.

ARTICLE DISCUSSION4 helpful