Debug with an agent

These recipes cover common jobs an agent does with ReqRes, each with the tools involved and a prompt to adapt. Tools that change ReqRes ask for your approval first, unless you allowed agent changes. exclude_host and replay_request ask every time.

Check setup first#

capture_status tells the agent whether capture is running and whether setup is finished. It also lists each protocol with its status. A relayed or not_captured kind, such as HTTP/3 or an excluded host, is missing or unread by design.

If ReqRes crashed or was force quit while capturing, capture kept running. For a few seconds after ReqRes opens again, the Delivery: line of capture_status reads reconnecting, and then says how many requests were captured meanwhile. The agent should call it again in a moment, not restart capture. See What the Delivery line says.

When requests are missing, diagnose_setup runs the setup checks in order and names the first thing to fix. It also reports a proxy port that another program holds, and apps that refused ReqRes's certificate. Most fixes are System Settings approvals and certificate trust, which only you can do.

Call capture_status. If nothing is being captured, run diagnose_setup and tell me the first thing to fix.

Watch a bug happen#

wait_for_session waits for the next matching request and ignores older ones. It also skips failed, aborted and timed-out requests, because browsers cancel requests all the time. Set include_failed to true to catch those too.

Ask the agent to start waiting, then reproduce the bug yourself. When one action sends several requests, such as a sign-in, wait_for_sessions collects them. By default it stops 2 seconds after the last match.

Wait for requests to api.example.com, failed ones included. I'm about to click Sign in. Tell me which request fails and why.

Turn a real response into an error#

mock_from_session turns a captured response into a rule, with the status, body or headers you choose. The rule answers your app without contacting the server, so the mock works with the server down. It matches only the captured method.

• Ask for a body that is not empty. An override with an empty body still sends the request to the server, and only replaces the status and headers of the real answer.
• A capture with no response body, or one ReqRes kept only in part, is refused unless the agent gives a new body.
• The rule works only while capture is running, and it counts toward the free limit of 1 rule. If the host has no host filter, the mock adds one, which counts toward the free 2.

Take the last response from GET /v1/orders and mock it as a 500 with the body {"error":"server_error"}. I want to test the error screen.

Tag requests without changing responses#

create_rule with mode set to extend and request_headers sets those headers on the requests the rule matches. Without a response_status, the rule keeps the server's status, and without response_headers it adds no Content-Type, so each response comes back as the server sent it. A rule belongs to a host filter, which add_host creates, and it counts toward the free limit of 1 rule.

Add an extend rule for api.example.com that sets the header X-Debug-Session: local on its requests. Leave the server's responses as they are.

Compare a working and a failing request#

diff_sessions returns only what differs between 2 requests: status, method, query parameters, headers, and JSON bodies by key path. Use it when a request works in curl and fails in your app.

Compare my last curl request to /v1/login with the last one my app sent. What differs?

Read one value from a large body#

query_session_body with mode set to structure returns the shape of a JSON body: keys, types and array lengths. With mode set to path, it returns one value, such as data.items[0].id.

Show me the structure of the last /v1/catalog response, then read the price of the first item.

Read a streamed LLM answer#

wait_for_session with until set to first_message returns when the first complete event of an SSE or NDJSON stream arrives, while the answer is still streaming. get_session with view set to assembled puts an Anthropic or OpenAI stream back together: text, tool calls with their arguments, stop reason, token usage and model. With view set to events, the agent reads the events a page at a time. See Read streaming responses.

Wait for the next request to api.anthropic.com until its first event arrives. When it finishes, show me the assembled answer and any tool calls.

Watch a WebSocket#

A WebSocket is one row, its 101 Switching Protocols handshake. list_messages reads its messages both ways, filtered by direction, opcode or text. wait_for_message waits for the next matching message, so the agent can watch a realtime API while you act. Its contains filter matches the redacted text. See Read WebSocket messages.

Wait for the next WebSocket message from the server that contains transcript.final. I'm about to start speaking.

Find failed gRPC calls#

A gRPC-Web error arrives as HTTP 200, so the status code does not show it. list_sessions with grpc set to error lists the calls whose own status is not OK. get_session with view set to rpc decodes each message without the .proto file and says where the status came from. Native gRPC needs Capture HTTP/2 (beta) on. See Capture HTTP/2 and gRPC.

List the gRPC calls that failed, then decode the messages of the newest one.

Find out why requests fail#

A request that did not complete is still a row. list_sessions with outcome set to failed lists them, and get_session gives the cause in one sentence. A tlsClient failure means the app refused ReqRes's certificate:

• A command-line tool usually lacks the ReqRes CA as a file. capture_environment gives the lines.
• An app that pins its certificate is remembered after it refuses ReqRes's. ReqRes then passes that app's connections to the host's domain through untouched, and the app works when you try again. See Keep SSL-pinned apps working.
• To stop recording a host at all, the agent can call exclude_host. ReqRes asks you every time, and new requests to the host then stop appearing in the traffic list.

See See why a request failed.

List the requests that failed and tell me why. If an app refuses ReqRes's certificate, ask me before you exclude its host.

Check that a mock fires#

replay_request sends a captured GET, HEAD or OPTIONS request again. With capture on, the ReqRes CA trusted and the host not excluded, the replay goes through ReqRes, so your rules apply and the replay appears in the traffic list. Otherwise the real server answers, and the result says the replay was relayed or sent directly. ReqRes asks you before every replay.

Replay the last GET /v1/orders and check that the 500 mock answers it.

Capture your own tool's traffic#

Some command-line tools ignore the system proxy: curl and git (Apple's included), the Claude Code CLI, node, Go and Rust programs, and processes inside Docker containers. capture_environment prints the shell lines that send such a tool through ReqRes, at the configured proxy port. It changes nothing and needs no approval. The lines set each proxy variable in both spellings, such as HTTP_PROXY and http_proxy, because curl and git take the proxy for plain http:// only from http_proxy. They carry no comments, so paste them exactly as printed. Start the tool again after you export the lines, because a running tool does not see them. See Capture command-line tools and agents.

My CLI's requests don't show up in ReqRes. Call capture_environment and give me the lines to paste.

Keep evidence#

save_session keeps one captured request after the run ends, with a note of up to 280 characters. Otherwise captured traffic is gone when ReqRes quits or you clear it, and the oldest requests drop off after 5,000. export_sessions writes up to 100 requests to a HAR 1.2 file, with values redacted. Neither takes a request still in flight: save_session refuses it, and export_sessions leaves it out and says how many.

Save the failing checkout request with a note that says why it matters. Then export the sign-in requests as signin.har.

See where a tool sends data#

list_destinations groups captured requests by destination country, from an offline lookup. Set app to see one tool: claude covers both the Claude app and the claude command-line tool. Add country to list the hosts and apps behind one destination.

Where does claude send data? Call list_destinations with app set to claude and list the hosts for each country.

Answer a held request#

With Settings ▸ Breakpoints ▸ Let agents answer held requests on, an agent can resume, edit or abort a held request, over HTTPS or plain http. Agents cannot create breakpoints. You add them in Settings ▸ Breakpoints.

list_paused_requests shows each held request with the seconds it has left and what its body declares, such as its size, but never the body itself. When the agent resumes without a new body, the original body goes on unchanged, except for a TRACE that arrives with a body of its own: ReqRes answers that one 502 over HTTP/1.1, as its body: line says, so the agent should abort it instead. A new body replaces the original, and none of the original reaches the server. A held request continues untouched after 60 seconds, so the agent has to act fast.

Nothing is held while ReqRes is not receiving capture, for example while it reconnects after you open it again: a matching request goes through.

I set a breakpoint on /v1/orders. When it holds a request, abort it with a 503 so I can watch the retry logic.

Remove the rules you created#

Rules stay until someone deletes them. Ask the agent to find its rules with list_rules, then delete them with delete_rule or turn them off with update_rule. To reverse a single agent change yourself, see Undo a change.

Delete the mock you made for /v1/orders, and confirm no rules are left for api.example.com.