Description

Adds a retry field to AfterToolCallEvent that allows hook callbacks to trigger tool re-execution. When
set to True, the tool executor discards the current result and invokes the tool again with the same
tool_use_id.

This provides the hook infrastructure needed for implementing custom retry strategies for tool
failures, timeouts, or transient errors.

Changes

• Add AfterToolCallEvent.retry: bool = False field
• Add retry loop in tool executor that checks after_event.retry after each tool call
• Use getattr(after_event, "retry", False) to maintain compatibility with BidiAfterToolCallEvent

Streaming behavior

When retry=True:

• ToolStreamEvents (intermediate) are emitted immediately and visible from ALL attempts
• ToolResultEvent is only emitted for the final attempt

Callers consuming streamed events should be prepared to see intermediate events from discarded
attempts.

Example Hook implementation

    def retry_on_first_error(event: AfterToolCallEvent) -> None:
        call_count++
        # Retry once on error
        if event.result.get("status") == "error" and state["call_count"] == 1:
            event.retry = True

    agent = Agent(tools=[flaky_tool])
    agent.hooks.add_callback(AfterToolCallEvent, retry_on_first_error)

Related Issues

#1405

Documentation PR

Todo

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.