Skip to content

Conversation

@DEENUU1
Copy link

@DEENUU1 DEENUU1 commented Nov 28, 2025

Add tool timeout

Summary

This PR adds tool timeout support for function tools. When a tool exceeds timeout, a RetryPromptPart is returned to the model, enabling the model to try a different approach.

Features

  • Agent-level timeout: Set default timeout for all tools via
    Agent(tool_timeout=60)
  • Per-tool timeout: Override default with @agent.tool(timeout=30)
  • Backward compatible: Default is None (no timeout)
  • Function tools only: MCP servers have their own timeout mechanisms

Usage

from pydantic_ai import Agent

# Agent-level timeout applies to all tools
agent = Agent('openai:gpt-4o', tool_timeout=60)

@agent.tool_plain
async def tool_with_default_timeout() -> str:
# Will timeout after 60 seconds (agent default)
    ...

@agent.tool_plain(timeout=10)
async def tool_with_custom_timeout() -> str:
# Will timeout after 10 seconds (overrides agent default)
    ...

Implementation

  • Timeout logic in FunctionToolset.call_tool() using anyio.fail_after()
  • Agent passes tool_timeout to FunctionToolset as default_timeout (same pattern as max_retries)
  • Per-tool timeout takes precedence over agent-level default
  • On timeout, returns RetryPromptPart with message: "Timed out after {timeout} seconds."
  • Timeout counts as a tool failure (increments retry counter)
  • Added timeout field to Tool, ToolDefinition, and ToolsetTool classes

Tests Added

  • test_tool_timeout_triggers_retry - Verifies slow tools return RetryPromptPart
  • test_tool_with_timeout_completes_successfully - Verifies tool completes within timeout
  • test_no_timeout_by_default - Verifies backward compatibility
  • test_tool_timeout_retry_counts_as_failed - Verifies retry mechanism integration
  • test_tool_timeout_message_format - Verifies error message format
  • test_tool_timeout_definition - Verifies ToolDefinition has timeout field
  • test_tool_timeout_default_none - Verifies default timeout is None
  • test_tool_timeout_exceeds_retry_limit - Verifies UnexpectedModelBehavior on retry limit exceeded
  • test_agent_level_tool_timeout - Verifies agent-level timeout applies to all tools
  • test_per_tool_timeout_overrides_agent_timeout - Verifies per-tool timeout overrides agent default
  • test_agent_tool_timeout_passed_to_toolset - Verifies agent passes timeout to FunctionToolset

@DouweM DouweM self-assigned this Dec 1, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants