Tool runner vs manual agent loop in the Claude SDK

Try 3 questions on this

Pick an answer to see why each option is right or wrong.

1. You drive your own functions with client.beta.messages.tool_runner(...) and iterate over the runner in a for loop that has no exit of its own, so nothing in your code tells the runner to stop. A task can keep looping for as long as Claude keeps requesting tools, and you want the number of turns it takes bounded. Which approach should you take?

   Right. In the game that’s Renown for your Agent Architecture and Orchestration building.

   Not that one: C is right. In the game your Agent Architecture and Orchestration building would lose a little Renown, and this question would come back later.

   Your answerA.Raise an exception from one of your functions, which ends the loop after a handful of turns whatever Claude has asked for next.Tool failures are part of normal operation for an agentic loop: the runner catches the exception and hands Claude a tool result with is_error: true carrying the exception's message, so Claude can retry, work around it, or report it. The loop keeps going.Your answerB.Rely on the ten-turn ceiling the runner applies by default, which ends the loop when Claude has taken that many turns, unless it finishes the work sooner on its own.Nothing stops an unbounded runner from looping as long as Claude keeps calling tools -- there is no default ceiling at ten turns or any other number. That is exactly why max_iterations exists and why the docs tell you to pass it.The answerC.Pass max_iterations to the runner, which ends the loop when Claude returns a message with no tool use, or when it reaches that many turns."The runner loops until Claude returns a message without a tool use, or until it reaches max_iterations if you set it." Each iteration the runner checks whether Claude requested a tool use; if it did, the runner runs the tool, sends the result back and yields the next message. The natural exit is therefore the first message with no tool call, and the only caller-supplied bound on the number of turns is max_iterations.Your answerD.Break when a response reports truncated output, which ends the loop after a handful of turns once Claude runs past the token budget.A truncated response is a state to handle, not a terminal one -- the documented pattern is to raise max_tokens and retry the turn. The loop's exit condition is the absence of a tool call, whatever the stop reason.

   Written from platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner

2. Your Python service drives three internal tools with the SDK tool runner. A teammate proposes leaving every failure as an uncaught exception, arguing that Claude will read the full stack trace in the tool result and correct its own arguments on the next turn. Your loop has no error handling of its own. How should you evaluate this proposal?

   Right. In the game that’s Renown for your Agent Architecture and Orchestration building.

   Not that one: B is right. In the game your Agent Architecture and Orchestration building would lose a little Renown, and this question would come back later.

   Your answerA.Sound: the runner catches the exception and hands Claude the full stack trace as the tool result content.The tool result the runner builds carries the exception's message, not the full stack trace. The trace is logged locally by the Python SDK, not sent to Claude.The answerB.Partly sound: the runner catches the exception and returns is_error: true, but the result carries only the exception's message.A tool that raises does not break the loop: the tool runner catches the exception and returns it to Claude as a tool result with is_error: true.Your answerC.Unsound: an uncaught exception escapes the runner and ends the iteration, so your caller must handle it.The runner catches exceptions raised by a tool and converts them into a tool result, so the loop continues rather than the exception reaching your caller.Your answerD.Unsound: the runner retries the failing tool two or three times and only then returns an error result.The runner does not re-run a tool that raised. Claude is the one that retries an invalid or incomplete tool call, two to three times, before giving up.

   Show the full explanation and doc quotes

   The result carries the exception's message, and in Python its type as well, not the full stack trace. The trace stays on your side, where the Python SDK logs it through the standard logging module. So the teammate is right that the loop keeps running and Claude sees the failure, and wrong that Claude sees the trace.

   Written from platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner

3. Your service drives an agent loop with the Anthropic Python SDK's tool runner (client.beta.messages.tool_runner). One tool raises an exception when a downstream billing API returns a hard decline. Today the loop continues and Claude retries the call with different arguments. Your service must stop the loop on that specific failure and surface it to its caller. Which approach should you take?

   Right. In the game that’s Renown for your Agent Architecture and Orchestration building.

   Not that one: B is right. In the game your Agent Architecture and Orchestration building would lose a little Renown, and this question would come back later.

   Your answerA.Let the tool's exception propagate out of the runner and catch it in the code that surrounds the loop.Assumes an unhandled tool exception escapes the runner. When a tool throws, the tool runner catches it and returns the error to Claude as a tool result with is_error: true carrying the exception's message, so nothing propagates for surrounding code to catch.The answerB.Inspect the result from generate_tool_call_response() in the loop body and break when it reports the decline.The tool runner catches an exception thrown by a tool and returns it to Claude as a tool result with is_error: true carrying the exception's message rather than the full stack trace, so the loop continues and Claude decides what to do next.Your answerC.Set max_iterations on the runner so that the loop is bounded once the tool starts failing.max_iterations is a bound on how many turns the runner will take, not a way to react to a particular tool result. The loop still runs its remaining iterations after the decline, and the caller cannot tell a decline from any other reason for stopping.Your answerD.Return a tool_result with is_error: true and a decline message from inside the tool body, so the runner stops the loop.Returning an errored tool result is exactly what the runner already does with a thrown exception. Tool errors are passed back to Claude by design so it can respond, which is the retry behaviour the service wants to prevent.

   Show the full explanation and doc quotes

   To act on a failure before it reaches Claude, the Python and TypeScript SDKs expose a tool response method -- generate_tool_call_response() in Python -- which yields the tool result inside the loop body, where the caller can inspect it and break.

   Written from platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner