[1.x] Report a sub-agent that throws as a failed tool call

Merged
ME
7d ago
+122-29

When a sub-agent used as a tool throws (a provider error, a timeout), AgentTool catches it and returns Agent failed: <message> as a normal result. The catch was added on purpose in #348: before #1191, it was what kept the parent run alive, because any tool that threw ended the run. Since #1191 every other tool's failure is recovered, but to the rest of the package a failed sub-agent still looks like a successful call:

  • ToolInvoked is dispatched with the error text as the result, and ToolFailed never is.
  • The step's ToolResult has failed: false, so successful() is true and error() is null, in the response, the stream's tool_result event and the stored conversation.

A listener or UI that shows tool status can only spot a failed sub-agent by matching the Agent failed: prefix.

This PR removes the catch from AgentTool, so a sub-agent's failure is handled like any other tool's:

  • Prompted: executeTool() dispatches ToolFailed, and the model gets a failed result, The tool call failed: <message>. The exception is reported and the parent run continues, as for any tool since #1191.
  • Streamed: executeAgentToolStreaming() catches a throw from the sub-agent's stream and does the same. It had no try/catch before, because AgentTool::stream() never threw.
  • Resumed after approval: unchanged. That path already turns any tool's exception into a failed result, without reporting it, as #1191 left it.

The sub-agent's own AgentFailed is still dispatched.

[!WARNING]

  • The model now reads The tool call failed: … instead of Agent failed: …. Agents whose instructions mention the old text need the new wording.
  • A failing sub-agent is now passed to report(), so it shows up in the exception handler (Sentry, Flare) like any other failed tool.
  • ToolInvoked is no longer dispatched for a sub-agent that throws. Listen for ToolFailed instead.
  • Code that calls AgentTool::handle() or AgentTool::stream() directly now gets the exception instead of an Agent failed: string.

Until this ships, wrapping the sub-agent in a plain Tool whose handle() calls $agent->prompt() gets the same failed result, at the cost of the sub-agent's streamed output.

Tests cover a throwing sub-agent on the prompted and streamed paths, including one that throws after it has streamed output: ToolFailed, no ToolInvoked, the sub-agent's own AgentFailed, a failed result, and the parent run continuing.