Skip to content
Kiberon LabsAgentic Engineering Ebook

Agent-Computer Interface (ACI)

Description

Section titled “Description”

The Agent-Computer Interface is the surface through which an agent perceives and acts on its environment: the file viewer, the edit command, the search tool, the shell wrapper, the format in which results come back. It is the agent-facing analogue of a human’s IDE and terminal.

The central, counter-intuitive finding from the field is that this interface is a designed artifact that determines a large fraction of agent capability independently of the model.

A meaningful share of “agent quality” lives in the harness, not the weights.

Source: SWE-agent (arXiv:2405.15793)

This page is distinct from ACRI. ACRI is the interface above the agent (Orchestrator ↔ harness lifecycle). The ACI is the interface below the agent (agent ↔ environment tools). A harness needs both: a clean ACRI driver so the Orchestrator can manage it, and a well-designed ACI so the agent inside it can work reliably.

Why a Bash Terminal Is the Wrong Default

Section titled “Why a Bash Terminal Is the Wrong Default”

A raw shell is a human interface. It assumes a reader who can scroll, remember screen state, and tolerate verbose output. Agents have none of those affordances: every byte of tool output consumes context budget and attention (see Runtime Context Management), and an agent cannot “scroll back” it only sees what is in the window now.

Giving an agent a bare terminal therefore wastes its capability on interface friction. The fix is to wrap the environment in commands designed for an LLM consumer.

The Four ACI Design Principles

Section titled “The Four ACI Design Principles”

From SWE-agent, with the failure mode each one prevents:

  1. Consolidated, efficient actions. Collapse multi-step operations into single commands. Compact, reliable file editing is the single most performance-critical capability an agent that has to issue five commands to make one edit will get lost between them.
  2. Informative feedback. After an action, show the agent the resulting state e.g. the revised file region after an edit so it can verify the effect rather than assuming success.
  3. Guardrails at the interface. Prevent common mistakes before they land. The standout example: an edit command with built-in linting that rejects edits which would break syntax, so the agent never commits a broken state. Catch errors at the interface layer, not three steps later at the test layer.
  4. Simple, LLM-parseable commands and output. Wrap raw tools in structured, summarised output. Verbose human-readable output actively hurts more context is not better.

Concrete Components

Section titled “Concrete Components”
  • Windowed file viewer. Show a bounded region (~100 lines) with cursor position rather than dumping whole files. Bounded, scrollable, predictable context cost.
  • Lint-on-edit. The editor refuses to apply a change that breaks parse/syntax and returns the error for immediate correction. This is the highest-leverage guardrail.
  • Concise search. find / grep / view that return summarised results. Prefer exact-symbol agentic search over verbose dumps; truncate and rank.
  • Consolidated shell wrapper. Structured stdout/stderr with clear delimiters, exit codes surfaced explicitly, output truncated with a continuation handle.

Edit Formats

Section titled “Edit Formats”

How the agent expresses a code change is itself a tuned variable, and the right choice depends on the model (Aider’s hard-won result, from benchmark-driven development against a fixed eval):

FormatShapeTrade-off
whole-filereturn the entire filemost reliable for weaker models; token-expensive; caps file size
search/replace difffind-block → replace-blockfar fewer tokens; needs a stronger model to target precisely
unified diff (udiff)simplified unified diffinvented specifically to suppress “lazy coding” models eliding code with # ... rest unchanged placeholders
architect / editor splita reasoner decides the change, a cheaper editor applies the diffclean cost/reliability separation; mirrors planner/implementer routing

Lazy coding the model writing # ... existing code here instead of the real code is a named failure mode to defend against explicitly. The edit format is one of the defences.

Source: Aider edit formats

The Repo Map: Interface to the Codebase

Section titled “The Repo Map: Interface to the Codebase”

Reading files one at a time is a poor interface to a large codebase. Aider’s repo map is the deterministic gold standard for selecting what the agent sees:

  • Parse every file with tree-sitter; extract definitions and references.
  • Build a graph of symbols and rank it with PageRank, personalised toward the files and identifiers currently in play.
  • Binary-search a token budget (~1k tokens default) to fit the highest-ranked symbols.

The insight: “a function called by 20 others is more valuable context than a private helper called once.” This is graph-ranked just-in-time context a cheap, deterministic alternative to embedding search that also resists staleness. See Knowledge Base for the agentic-search-vs-RAG framing this sits inside, and Context Engines for the tooling layer.

Source: Aider repository map

Implications for Harness Selection

Section titled “Implications for Harness Selection”

ACI quality should be an explicit criterion when evaluating harnesses, alongside benchmark scores and model support. A harness with strong OpenBench numbers is, in part, a harness with a good ACI. When building custom tools or MCP servers, apply the same four principles: minimal, non-overlapping, structured-output, guardrailed. Bloated and overlapping tool sets degrade performance the same way verbose output does.

Section titled “Related Concepts”