ACI (Agent-Computer Interface) Principles: A Complete Guide for LLM Tool Design

ACI (Agent-Computer Interface) is a design philosophy that treats tools as interfaces for AI agents rather than traditional programmer-centric APIs, built on three core principles: Capability Representation, Tool Description, and Faithful Parameter Passing.

ACI draws direct inspiration from HCI (Human-Computer Interaction)—just as HCI studies how people interact with computers, ACI studies how agents interact with computers. According to the bojieli/ai-agent-book source code, this framework emerged from the need to make tools intuitive, self-describing, and robust for large language models (LLMs) to discover, select, and invoke correctly.

The Three Core ACI Principles

The ACI framework in book-en/chapter4.md establishes three foundational principles that govern effective agent-computer interface design.

1. Capability Representation

Capability Representation determines how a capability is expressed to the agent—whether as a function, a schema, or a structured description.

The form must be immediately recognizable to the model. In practice, this means:

• Function names should directly reflect the agent's goal
• Schemas must map cleanly to the agent's reasoning process
• Structured descriptions should eliminate ambiguity about what the tool achieves

The example in book-en/chapter1.md demonstrates this with fetch_weather()—a name that leaves no doubt about the intended outcome.

2. Tool Description

Tool Description provides concise, human-readable (and machine-parsable) metadata framed from the agent's perspective.

Effective descriptions in ACI-compliant tools cover:

• Purpose: What goal the tool accomplishes
• Expected inputs: Parameter names, types, and constraints
• Output format: What the agent receives upon successful invocation

Natural language alignment is critical. The description must match how the agent reasons about tasks, not how a developer documents an API.

3. Faithful Parameter Passing

Faithful Parameter Passing ensures parameters travel from agent to tool exactly as intended—no distortion, no semantic loss.

This principle eliminates "error-amplifying" ambiguities that cause systematic downstream failures. The bojieli/ai-agent-book implementation emphasizes validation wrappers that guarantee:

• Required parameters are present
• Types match specifications
• Values are transmitted without transformation

Practical ACI Implementation in Python

The source repository provides a canonical implementation in book-en/chapter4.md demonstrating all three principles:

from typing import TypedDict, List

# 1️⃣ Capability representation – clear function name conveying the goal

def fetch_weather(city: str) -> str:
    """Fetches the current weather for a given city."""
    # Imagine an underlying API call here

    return f"The weather in {city} is sunny."

# 2️⃣ Tool description – structured schema the agent can read

class WeatherToolSpec(TypedDict):
    name: str          # Human‑readable name

    description: str   # Goal‑oriented description

    parameters: List[dict]  # Parameter specs

weather_tool: WeatherToolSpec = {
    "name": "fetch_weather",
    "description": "Obtain the real‑time weather for the specified city.",
    "parameters": [
        {"name": "city", "type": "string", "description": "Name of the city"}
    ],
}

# 3️⃣ Faithful parameter passing – wrapper validating inputs before calling

def invoke_tool(spec: WeatherToolSpec, args: dict) -> str:
    for param in spec["parameters"]:
        if param["name"] not in args:
            raise ValueError(f"Missing required argument: {param['name']}")
    return fetch_weather(args["city"])

# Example usage by an agent

result = invoke_tool(weather_tool, {"city": "Paris"})
print(result)   # → The weather in Paris is sunny.

Key implementation details from this pattern:

• fetch_weather embodies Capability Representation through its goal-direct name
• WeatherToolSpec fulfills Tool Description with agent-oriented metadata
• invoke_tool enforces Faithful Parameter Passing via pre-call validation

Error-Proofing with Poka-Yoke Design

The ACI framework incorporates poka-yoke (mistake-proofing) concepts from manufacturing: interfaces are crafted so that misuse is impossible by design.

Specific techniques surfaced in book-en/chapter4.md include:

• Unambiguous naming conventions that prevent similar-tool confusion
• Explicit required/optional parameter distinctions
• Validation layers that fail fast on malformed inputs

This proactive approach prevents error propagation rather than handling failures reactively.

Key Source Files for ACI Reference

The bojieli/ai-agent-book repository maintains ACI documentation across multiple languages:

File	Purpose
book-en/chapter4.md	Primary English exposition of ACI principles and rationale
book-en/chapter1.md	Introductory overview with illustrative tool interface examples
book-zhtw/chapter4.zhtw.md	Traditional Chinese translation
book-tr/chapter4.tr.md	Turkish translation
book-ta/chapter4.ta.md	Tamil translation

These files collectively define the ACI concept and practical guidelines for designing agent-friendly tool interfaces.

ACI vs. Traditional API Design

Dimension	Traditional API	ACI-Designed Tool
Primary user	Human developer	AI agent/LLM
Naming priority	Consistency with codebase	Clarity of goal/intent
Documentation	Comprehensive reference	Concise, reasoning-aligned description
Error handling	Rich exception hierarchies	Fail-fast, unambiguous validation
Parameter design	Flexibility for varied use cases	Precision for specific agent tasks

Summary

• ACI (Agent-Computer Interface) reframes tools as agent-facing interfaces rather than programmer APIs
• Three principles govern ACI design: Capability Representation, Tool Description, and Faithful Parameter Passing
• Poka-yoke techniques eliminate misuse through structural design choices
• Python implementations use TypedDict schemas, validation wrappers, and goal-direct naming
• Source files in bojieli/ai-agent-book provide multilingual, in-depth coverage across book-en/chapter4.md and related chapters

Frequently Asked Questions

What is the difference between ACI and HCI?

ACI studies how AI agents interact with computers; HCI studies how humans interact with computers. Both are interface design disciplines, but ACI optimizes for LLM reasoning patterns rather than human cognitive ergonomics. The bojieli/ai-agent-book explicitly draws this parallel in book-en/chapter4.md to establish ACI's conceptual foundation.

Why is Faithful Parameter Passing critical for agent reliability?

Without faithful transmission, small ambiguities compound into systematic failures. When an agent specifies city="Paris" but the value arrives distorted or mislabeled, subsequent logic fails unpredictably. The invoke_tool() wrapper pattern in the source code demonstrates how validation guarantees exactly what the agent intended reaches the underlying function.

How does ACI prevent common agent tool errors?

ACI incorporates poka-yoke (error-proofing) by designing interfaces where mistakes are structurally impossible. Examples include naming conventions that prevent ambiguous tool selection, required parameter validation that fails before execution, and descriptions framed to match agent reasoning—each constraint eliminates entire categories of misuse rather than catching errors after they occur.

Where can I find the complete ACI specification?

The definitive ACI exposition resides in book-en/chapter4.md of the bojieli/ai-agent-book repository, with practical introductions in book-en/chapter1.md. Translated versions in Traditional Chinese (book-zhtw/chapter4.zhtw.md), Turkish (book-tr/chapter4.tr.md), and Tamil (book-ta/chapter4.ta.md) ensure accessibility across language communities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}