Add Runtime builtin_tools Support

[safina57]

Add Runtime Builtin Tools Support with Priority-Based Merging

Overview

This PR Fixes issue #2821 adds support for providing builtin tools at runtime in Agent.run(), Agent.run_sync(), Agent.run_stream() and Agent.iter() methods, with runtime tools taking priority over agent initialization tools. The implementation follows the exact same pattern as the existing model settings priority system.

Motivation

Previously, builtin tools could only be configured when creating an Agent instance. This limitation made it difficult to:

• Dynamically adjust tool configurations based on runtime context
• Override specific tools for individual runs without creating new agent instances
• Provide different tool configurations for different use cases with the same agent

Implementation Approach

Priority System Design

The implementation follows the established pattern used for model settings merge_model_settings() behavior:

Core Changes

1. Settings Module Enhancement

• Added merge_builtin_tools() function that implements type-based deduplication
• Runtime tools override base tools when both have the same type (e.g., both WebSearchTool)
• Different tool types are preserved from both runtime and base sets

2. Agent Interface Updates

• Added builtin_tools: Sequence[AbstractBuiltinTool] | None = None parameter to all agent method signatures
• Maintains backward compatibility - parameter defaults to None

3. Core Agent Implementation

• Integrated merge logic in the iter method (the base method all others delegate to)
• Runtime tools are merged with agent's base tools before being passed to GraphAgentDeps

4. Wrapper Agent Support

• Updated WrapperAgent to pass through the builtin_tools parameter
• Ensures compatibility with agent composition patterns

[safina57]

Heyy @DouweM
could you check on the approach please
Thanks ! ^^

[DouweM]

We can skip having a helper method using this trick, in a variable we build further up in this method:

builtin_tools = list(
    {
        **({type(tool): tool for tool in self._builtin_tools or []}),
        **({type(tool): tool for tool in builtin_tools or []}),
    }.values()
)

[DouweM]

We can drop these tests if we drop the merge helper as I suggested above

[DouweM]

We can replace these tests with one that verifies that test_model.last_model_request_parameters.builtin_tools contains what we expect