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

> Explore ACI Agent Computer Interface principles for LLM tool design. Learn how to create effective AI agent interfaces focusing on capability representation, tool description, and faithful parameter passing.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: deep-dive
- Published: 2026-08-25

---

**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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/book-en/chapter4.md) demonstrating all three principles:

```python
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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/book-en/chapter4.md) | Primary English exposition of ACI principles and rationale |
| [`book-en/chapter1.md`](https://github.com/bojieli/ai-agent-book/blob/main/book-en/chapter1.md) | Introductory overview with illustrative tool interface examples |
| [`book-zhtw/chapter4.zhtw.md`](https://github.com/bojieli/ai-agent-book/blob/main/book-zhtw/chapter4.zhtw.md) | Traditional Chinese translation |
| [`book-tr/chapter4.tr.md`](https://github.com/bojieli/ai-agent-book/blob/main/book-tr/chapter4.tr.md) | Turkish translation |
| [`book-ta/chapter4.ta.md`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/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`](https://github.com/bojieli/ai-agent-book/blob/main/book-en/chapter4.md) of the `bojieli/ai-agent-book` repository**, with practical introductions in [`book-en/chapter1.md`](https://github.com/bojieli/ai-agent-book/blob/main/book-en/chapter1.md). Translated versions in Traditional Chinese ([`book-zhtw/chapter4.zhtw.md`](https://github.com/bojieli/ai-agent-book/blob/main/book-zhtw/chapter4.zhtw.md)), Turkish ([`book-tr/chapter4.tr.md`](https://github.com/bojieli/ai-agent-book/blob/main/book-tr/chapter4.tr.md)), and Tamil ([`book-ta/chapter4.ta.md`](https://github.com/bojieli/ai-agent-book/blob/main/book-ta/chapter4.ta.md)) ensure accessibility across language communities.