Skip to content

Add Runtime builtin_tools Support #3009

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Add Runtime builtin_tools Support #3009

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
403a3b5
feat: Add builtin_tools parameter to Agent, WrapperAgent and DBOSAgen…
safina57 Sep 26, 2025
dc0c221
Merge branch 'main' into fix-webtools-user-location-runtime
safina57 Sep 26, 2025
af47826
test: Enhance test converage
safina57 Sep 26, 2025
00d2448
refactor: Remove merge_builtin_tools function and update Agent to han…
safina57 Oct 3, 2025
b4fc659
Merge branch 'main' into fix-webtools-user-location-runtime
safina57 Oct 3, 2025
3d71ff7
refactor: move builtin_tools tests to agent tests and update builtin_…
safina57 Oct 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions pydantic_ai_slim/pydantic_ai/agent/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -424,6 +424,7 @@ def iter(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
) -> AbstractAsyncContextManager[AgentRun[AgentDepsT, OutputDataT]]: ...

@overload
Expand All @@ -441,6 +442,7 @@ def iter(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
) -> AbstractAsyncContextManager[AgentRun[AgentDepsT, RunOutputDataT]]: ...

@asynccontextmanager
Expand All @@ -458,6 +460,7 @@ async def iter(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
) -> AsyncIterator[AgentRun[AgentDepsT, Any]]:
"""A contextmanager which can be used to iterate over the agent graph's nodes as they are executed.

Expand Down Expand Up @@ -530,6 +533,7 @@ async def main():
usage: Optional usage to start with, useful for resuming a conversation or agents used in tools.
infer_name: Whether to try to infer the agent name from the call frame if it's not set.
toolsets: Optional additional toolsets for this run.
builtin_tools: Optional additional builtin tools for this run.

Returns:
The result of the run.
Expand Down Expand Up @@ -601,7 +605,16 @@ async def get_instructions(run_context: RunContext[AgentDepsT]) -> str | None:
else:
instrumentation_settings = None
tracer = NoOpTracer()

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 = list(self._builtin_tools)
graph_deps = _agent_graph.GraphAgentDeps[AgentDepsT, RunOutputDataT](
user_deps=deps,
prompt=user_prompt,
Expand All @@ -614,7 +627,7 @@ async def get_instructions(run_context: RunContext[AgentDepsT]) -> str | None:
output_schema=output_schema,
output_validators=output_validators,
history_processors=self.history_processors,
builtin_tools=list(self._builtin_tools),
builtin_tools=builtin_tools,
tool_manager=tool_manager,
tracer=tracer,
get_instructions=get_instructions,
Expand Down
20 changes: 20 additions & 0 deletions pydantic_ai_slim/pydantic_ai/agent/abstract.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
usage as _usage,
)
from .._tool_manager import ToolManager
from ..builtin_tools import AbstractBuiltinTool
from ..output import OutputDataT, OutputSpec
from ..result import AgentStream, FinalResult, StreamedRunResult
from ..run import AgentRun, AgentRunResult
Expand Down Expand Up @@ -135,6 +136,7 @@ async def run(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
event_stream_handler: EventStreamHandler[AgentDepsT] | None = None,
) -> AgentRunResult[OutputDataT]: ...

Expand All @@ -153,6 +155,7 @@ async def run(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
event_stream_handler: EventStreamHandler[AgentDepsT] | None = None,
) -> AgentRunResult[RunOutputDataT]: ...

Expand All @@ -170,6 +173,7 @@ async def run(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
event_stream_handler: EventStreamHandler[AgentDepsT] | None = None,
) -> AgentRunResult[Any]:
"""Run the agent with a user prompt in async mode.
Expand Down Expand Up @@ -203,6 +207,7 @@ async def main():
infer_name: Whether to try to infer the agent name from the call frame if it's not set.
toolsets: Optional additional toolsets for this run.
event_stream_handler: Optional handler for events from the model's streaming response and the agent's execution of tools to use for this run.
builtin_tools: Optional additional builtin tools for this run.

Returns:
The result of the run.
Expand All @@ -223,6 +228,7 @@ async def main():
usage_limits=usage_limits,
usage=usage,
toolsets=toolsets,
builtin_tools=builtin_tools,
) as agent_run:
async for node in agent_run:
if event_stream_handler is not None and (
Expand All @@ -249,6 +255,7 @@ def run_sync(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
event_stream_handler: EventStreamHandler[AgentDepsT] | None = None,
) -> AgentRunResult[OutputDataT]: ...

Expand All @@ -267,6 +274,7 @@ def run_sync(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
event_stream_handler: EventStreamHandler[AgentDepsT] | None = None,
) -> AgentRunResult[RunOutputDataT]: ...

Expand All @@ -284,6 +292,7 @@ def run_sync(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
event_stream_handler: EventStreamHandler[AgentDepsT] | None = None,
) -> AgentRunResult[Any]:
"""Synchronously run the agent with a user prompt.
Expand Down Expand Up @@ -316,6 +325,7 @@ def run_sync(
infer_name: Whether to try to infer the agent name from the call frame if it's not set.
toolsets: Optional additional toolsets for this run.
event_stream_handler: Optional handler for events from the model's streaming response and the agent's execution of tools to use for this run.
builtin_tools: Optional additional builtin tools for this run.

Returns:
The result of the run.
Expand All @@ -336,6 +346,7 @@ def run_sync(
usage=usage,
infer_name=False,
toolsets=toolsets,
builtin_tools=builtin_tools,
event_stream_handler=event_stream_handler,
)
)
Expand All @@ -355,6 +366,7 @@ def run_stream(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
event_stream_handler: EventStreamHandler[AgentDepsT] | None = None,
) -> AbstractAsyncContextManager[result.StreamedRunResult[AgentDepsT, OutputDataT]]: ...

Expand All @@ -373,6 +385,7 @@ def run_stream(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
event_stream_handler: EventStreamHandler[AgentDepsT] | None = None,
) -> AbstractAsyncContextManager[result.StreamedRunResult[AgentDepsT, RunOutputDataT]]: ...

Expand All @@ -391,6 +404,7 @@ async def run_stream( # noqa C901
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
event_stream_handler: EventStreamHandler[AgentDepsT] | None = None,
) -> AsyncIterator[result.StreamedRunResult[AgentDepsT, Any]]:
"""Run the agent with a user prompt in async streaming mode.
Expand Down Expand Up @@ -430,6 +444,7 @@ async def main():
usage: Optional usage to start with, useful for resuming a conversation or agents used in tools.
infer_name: Whether to try to infer the agent name from the call frame if it's not set.
toolsets: Optional additional toolsets for this run.
builtin_tools: Optional additional builtin tools for this run.
event_stream_handler: Optional handler for events from the model's streaming response and the agent's execution of tools to use for this run.
It will receive all the events up until the final result is found, which you can then read or stream from inside the context manager.
Note that it does _not_ receive any events after the final result is found.
Expand Down Expand Up @@ -457,6 +472,7 @@ async def main():
usage=usage,
infer_name=False,
toolsets=toolsets,
builtin_tools=builtin_tools,
) as agent_run:
first_node = agent_run.next_node # start with the first node
assert isinstance(first_node, _agent_graph.UserPromptNode) # the first node should be a user prompt node
Expand Down Expand Up @@ -567,6 +583,7 @@ def iter(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
) -> AbstractAsyncContextManager[AgentRun[AgentDepsT, OutputDataT]]: ...

@overload
Expand All @@ -584,6 +601,7 @@ def iter(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
) -> AbstractAsyncContextManager[AgentRun[AgentDepsT, RunOutputDataT]]: ...

@asynccontextmanager
Expand All @@ -602,6 +620,7 @@ async def iter(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
) -> AsyncIterator[AgentRun[AgentDepsT, Any]]:
"""A contextmanager which can be used to iterate over the agent graph's nodes as they are executed.

Expand Down Expand Up @@ -674,6 +693,7 @@ async def main():
usage: Optional usage to start with, useful for resuming a conversation or agents used in tools.
infer_name: Whether to try to infer the agent name from the call frame if it's not set.
toolsets: Optional additional toolsets for this run.
builtin_tools: Optional additional builtin tools for this run.

Returns:
The result of the run.
Expand Down
6 changes: 6 additions & 0 deletions pydantic_ai_slim/pydantic_ai/agent/wrapper.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
models,
usage as _usage,
)
from ..builtin_tools import AbstractBuiltinTool
from ..output import OutputDataT, OutputSpec
from ..run import AgentRun
from ..settings import ModelSettings
Expand Down Expand Up @@ -81,6 +82,7 @@ def iter(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
) -> AbstractAsyncContextManager[AgentRun[AgentDepsT, OutputDataT]]: ...

@overload
Expand All @@ -98,6 +100,7 @@ def iter(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
) -> AbstractAsyncContextManager[AgentRun[AgentDepsT, RunOutputDataT]]: ...

@asynccontextmanager
Expand All @@ -115,6 +118,7 @@ async def iter(
usage: _usage.RunUsage | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[AgentDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
) -> AsyncIterator[AgentRun[AgentDepsT, Any]]:
"""A contextmanager which can be used to iterate over the agent graph's nodes as they are executed.

Expand Down Expand Up @@ -187,6 +191,7 @@ async def main():
usage: Optional usage to start with, useful for resuming a conversation or agents used in tools.
infer_name: Whether to try to infer the agent name from the call frame if it's not set.
toolsets: Optional additional toolsets for this run.
builtin_tools: Optional additional builtin tools for this run.

Returns:
The result of the run.
Expand All @@ -203,6 +208,7 @@ async def main():
usage=usage,
infer_name=infer_name,
toolsets=toolsets,
builtin_tools=builtin_tools,
) as run:
yield run

Expand Down
5 changes: 4 additions & 1 deletion pydantic_ai_slim/pydantic_ai/builtin_tools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,13 @@

from abc import ABC
from dataclasses import dataclass
from typing import Literal
from typing import TYPE_CHECKING, Literal

from typing_extensions import TypedDict

if TYPE_CHECKING:
from .builtin_tools import AbstractBuiltinTool

__all__ = (
'AbstractBuiltinTool',
'WebSearchTool',
Expand Down
Loading