Agent-First HTTP v0.3.2: Requests Became Previewable

An HTTP tool is dangerous when the only way to inspect a request is to send it.

Agents build commands from context. They may choose the wrong method, attach the wrong header, or send a body to the wrong URL. A human can pause and read a curl command before pressing enter. An agent needs a structured preview path.

Agent-First HTTP v0.3.2 added that path.

The problem: a generated request needs an inspection step

A generated command is not just text. It is an intended side effect: method, URL, headers, body, redirects, timeouts, and output limits.

If the only runtime modes are “send it” or “fail parsing”, an agent has to guess whether it assembled the request correctly. That is backwards. The connector should be able to say what it is about to do.

The change: dry-run became a first-class event

--dry-run emits the resolved request without opening the network connection. The agent sees the method, URL, headers, and body after CLI parsing and config resolution.

{"code":"dry_run","method":"POST","url":"https://api.example.com/users","headers":{"content-type":"application/json"}}

That gives the agent a safe checkpoint. It can show the user the intended call, compare it with the task, or correct the command before any remote state changes.

The companion: errors started carrying hints

The same release added hint to runtime errors. DNS failures, connect timeouts, redirect loops, and response-size limits can now point to the likely next action: check the hostname, raise a limit, reduce the response, or enable streaming.

{"code":"error","error_code":"response_too_large","hint":"retry with stream_body=true or increase response limits"}

The error is still structured. The hint is not a replacement for error_code; it is the human-readable suggestion that helps an agent recover without scraping a sentence from stderr.

Where this fits: agent safety before network effects

This update made afhttp more than a structured curl. It introduced an agent workflow: preview the request, execute only when the shape is right, and recover from failures through stable codes plus hints.

For agents, the safest HTTP call is the one they can inspect before making.