How it works
An agent-computer interface sits between model output and computer execution. It turns a proposed action into a request that the harness can inspect before any tool, service, or operating-system capability runs. The interface describes available operations, their arguments, result shapes, error states, and relevant execution semantics. Names and schemas matter, but the contract also needs to say what an operation means: whether it reads or writes, whether repeating it is safe, and which outcomes may be ambiguous.
A typical invocation follows a short control sequence:
- The harness exposes a bounded set of operations and descriptions to the agent.
- The agent selects an operation and emits structured arguments.
- The harness validates the request against the operation schema and current run state.
- Permission checks, approval policies, budgets, and other deterministic controls decide whether execution is allowed.
- An adapter invokes the underlying computer capability.
- The interface returns a structured success, rejection, failure, or unknown outcome and records the event.
This boundary separates proposing an action from authorizing and performing it. The model can remain probabilistic while validation, permission enforcement, and result handling remain explicit. The interface can change internally, but its observable contract should change deliberately because prompts, policies, traces, and evaluations depend on it.
Why it matters in an agent harness
A model can describe an intended action in natural language, but natural language is a weak execution contract. It leaves too much room for argument ambiguity, hidden defaults, and inconsistent error handling. An agent-computer interface narrows that ambiguity into operations the harness can reason about.
The first outcome is control. Each invocation becomes an enforcement point for permission scope, approval requirements, execution limits, and state-dependent rules. A file-reading operation can be restricted to specific paths. A write can require a diff or checkpoint. A destructive action can be rejected even when the model confidently requests it. These controls belong at the interface because a prompt-level prohibition is guidance, not authorization.
The second outcome is legibility. Structured requests and results let an operator answer concrete questions: What did the agent ask to do? Which arguments were supplied? Which policy allowed it? What actually ran? What result came back? An execution trace built from these events is more useful than a transcript that records only the model's narration.
The third outcome is failure containment. The interface can distinguish validation failure, policy rejection, provider failure, completed execution, and unknown outcome. That distinction changes recovery. A rejected request may be revised safely. A confirmed failure may be retried if the operation is idempotent. An unknown outcome requires reconciliation before retrying, because the original action may already have taken effect.
The interface also creates an evaluation surface. You can test operation selection, argument construction, permission enforcement, response interpretation, and recovery behavior independently. Without this boundary, failures collapse into a vague conclusion that the agent behaved badly. With it, the harness can locate whether the defect came from planning, contract design, authorization, execution, or observation.
Agent-computer interface vs tool surface
The terms are related, but they answer different design questions. The tool surface is the set of capabilities exposed to an agent. The agent-computer interface is the contract and control path through which those capabilities are requested and observed.
| Design question | Agent-computer interface | Tool surface |
|---|---|---|
| Primary concern | Invocation and result contract | Which capabilities are available |
| Main artifacts | Schemas, semantics, error states, policy hooks | Tool inventory, grouping, descriptions |
| Typical risk | Ambiguous effects or unsafe recovery | Excess authority or excessive choice |
| Typical change | Revise arguments, outcomes, or enforcement | Add, remove, split, or hide capabilities |
Reducing the tool surface limits what an agent can attempt. Strengthening the interface controls how an allowed attempt becomes a computer action. Production harnesses need both. A small surface with vague semantics can still be dangerous, while a precise interface cannot compensate for exposing capabilities the task never required.
The Rifty take
We treat the agent-computer interface as an authority boundary, not merely a convenience for tool calling. We optimize for explicit effects, inspectable decisions, and recoverable outcomes, even when that adds contract design and adapter work. If an operation cannot report enough state to distinguish safe retry from possible duplicate execution, its interface is incomplete for autonomous use.
Implementation checks
- Give every operation a narrow purpose and a description that states its effect, not just its implementation.
- Validate operation names and arguments before execution. Reject unknown fields when accepting them would hide agent mistakes.
- Declare whether an operation reads, writes, deletes, communicates externally, or changes authority.
- Apply permissions and approval policy from trusted harness state, never from model-supplied claims.
- Return structured success, rejection, failure, and unknown-outcome states rather than flattening them into text.
- Define retry semantics. Mark idempotent operations and require reconciliation or compensating action for ambiguous writes.
- Record per-call attribution, validated arguments, policy decisions, execution identity, and results in the trace.
- Avoid plausible defaults for missing safety-relevant arguments. Missing scope, destination, or target identity should fail visibly.
- Version consequential contract changes and run regression evaluations against existing agent behavior.
- Test malformed arguments, denied permissions, timeouts, partial effects, duplicate requests, and interrupted result delivery.
Frequently asked questions
Is an agent-computer interface just a tool-calling schema?
No. A tool-calling schema describes operation names and argument shapes, but the interface also covers effect semantics, authorization, result states, retries, attribution, and recovery. The schema is one artifact inside the broader boundary that converts a model's proposed action into an observable computer operation.
Where should permission checks happen?
Permission checks should run in trusted harness code before the underlying capability executes. They should use authenticated run state, scoped credentials, operation metadata, and current policy. The agent may supply a target or rationale, but it must not be allowed to assert its own authority or bypass an approval requirement.
How should the interface represent tool failures?
Represent failures as structured states that distinguish invalid requests, policy rejections, confirmed execution failures, partial effects, and unknown outcomes. Include stable error categories and enough bounded detail for recovery. Do not turn every failure into free-form text, because the harness then cannot choose safe retry or escalation behavior reliably.
What makes an operation safe to retry?
An operation is safe to retry when its contract guarantees idempotency or the harness can prove that the first attempt had no effect. For non-idempotent writes, use request identifiers, reconciliation checks, checkpoints, or compensating actions. A timeout alone does not prove failure; the outcome may simply be unobserved.
Should every computer capability be exposed to the agent?
No. Expose only the capabilities required for the delegated task and current autonomy level. A narrower tool surface reduces accidental selection and limits blast radius. Capabilities with broad, destructive, or poorly observable effects should be decomposed, tightly scoped, approval-gated, or kept outside autonomous execution.