Let builtin_tools be specified at agent run time

[safina57]

Add Runtime Builtin Tools Support with Priority-Based Merging

Overview

Fixes #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 ! ^^

[safina57]

Heyy @DouweM Thanks for the feedback !
I've made the requested changes
I have a quick question though, why did we discard the helper function in favour of the dict comprehension? To me, the helper feels a bit more readable and easier to maintain

[DouweM]

@safina57 I suggest moving this to a variable further up, with a comment explaining what it does. Like:

if builtin_tools:
    # Deduplicate builtin tools passed to the agent and the run based on type
    builtin_tools = list(
        {
            **({type(tool): tool for tool in self._builtin_tools or []}),
            **({type(tool): tool for tool in builtin_tools}),
        }.values()
    )
else:
    builtin_tools = self._builtin_tools

I like it a bit better than the 10-line method because this is still sufficiently clear to someone familiar with Python, and much more concise. The separate method makes it seem like something complicated is going on, while it's really just deduplication.

We could also do it like this if you think it's more clear:

if builtin_tools:
    if self.builtin_tools:
        builtin_tool_types = [type(tool) for tool in builtin_tools]
        builtin_tools.extend([tool for tool in self._builtin_tools if type(tool) not in builtin_tool_types])
else:
    builtin_tools = self._builtin_tools

[safina57]

okyy got it
thanks ^^

[DouweM]

@safina57 Thanks Mohamed!