---
schema_version: "newruntime-agent-readable-v0.1"
type: "capability_delta"
slug: "agent-first-api-contracts"
title: "Agent-first API makes retries deterministic"
description: "Explicit fields, precise errors, request metadata, and raw facts turn an agent retry from guessing into near-deterministic repair."
status: "published"
observed_at: "2026-07-21"
before_capability: "Agent calls a human-friendly SDK and receives an opaque failure."
enabling_change: "API returns command, exit code, stderr, allowed values, request id, timeout, and raw metadata."
after_capability: "Agent can correct the next tool call from explicit machine-readable facts."
human_consequence: "The human spends less time reading logs for the agent and explaining what exactly broke."
verification_level: "source-inspected"
buildability_class: "B2"
bottleneck: "API providers must expose boring runtime facts instead of hiding them behind convenience SDKs."
related_shift: "generated-interface-from-answer"
related_posts: ["agent-api-design"]
topics: ["api-design","agents","tool-use"]
source_urls: ["https://www.freestyle.sh/blog/opinion/designing-apis-for-agents"]
featured: true
routes: {"html":"https://newruntime.com/deltas/agent-first-api-contracts/","markdown":"https://newruntime.com/deltas/agent-first-api-contracts.md","json":"https://newruntime.com/deltas/agent-first-api-contracts.json"}
source_format: "markdown"
---

# Agent-first API makes retries deterministic

This is the first homepage delta for New Runtime. It shows that post-app
software starts not with beautiful generated UI, but with the right contract
between the model, tools, and the state of the world.

## Why now

As tool use grows, the API becomes the environment where the agent thinks and
repairs itself. An opaque error breaks the loop; an explicit error gives the
next step.