---
schema_version: "newruntime-agent-readable-v0.1"
type: "post"
slug: "agent-api-design"
title: "Agent APIs Need Fewer Magic Tricks and More Facts"
description: "Agent-first APIs should return explicit fields, precise errors, raw facts, and traceable metadata so models can repair tool calls deterministically instead of guessing world state."
status: "published"
published_at: "2026-07-21"
topics: ["api-design","agents","tool-use"]
source_urls: ["https://www.freestyle.sh/blog/opinion/designing-apis-for-agents"]
routes: {"html":"https://newruntime.com/posts/agent-api-design/","markdown":"https://newruntime.com/posts/agent-api-design.md","json":"https://newruntime.com/posts/agent-api-design.json"}
source_format: "markdown"
---

# Agent APIs Need Fewer Magic Tricks and More Facts

An API that feels convenient to a human is not automatically convenient to an agent. Humans benefit from defaults, short quickstarts, and SDK methods that hide details. Agents benefit from explicit state.

The agent needs to know what actually happened after a tool call: command, exit code, stdout, stderr, runtime, request id, timeout, allowed values, and the raw response when something fails.

## Example

A human-first SDK might expose a pleasant wrapper:

```text
runCode("summary(cars)", { language: "r" })
```

That wrapper is useful until the call fails. An agent-first API should return the runtime, supported languages, exact field path, request metadata, and error category. Then the next attempt is guided by facts instead of by pattern-matching against similar APIs in memory.

## Why retries change

When the error says `something went wrong`, the agent starts guessing.

When the error says:

```text
field sandbox.runtime must be one of node20, python3.12
```

the next call is almost deterministic.

For tool schemas this means fewer magical options bags and more enums, field paths, allowed values, retry hints, and raw response metadata.

## New Runtime Read

> An agent often needs one boring internal HTTP client with auth, retries, logging, and raw bodies more than five friendly SDKs with five exception styles.

The point is not that SDKs are bad. The harmful abstraction is the one that hides world state from the same executor that must later repair the failure and leave a trace for a human.