1"""Test the base tool implementation."""23import asyncio4import inspect5import json6import logging7import pickle8import sys9import textwrap10import threading11import warnings12from collections.abc import Callable13from dataclasses import dataclass14from datetime import datetime15from enum import Enum16from functools import partial17from typing import (18 Annotated,19 Any,20 Generic,21 Literal,22 TypeVar,23 cast,24 get_type_hints,25)2627import pytest28from pydantic import (29 AliasChoices,30 BaseModel,31 ConfigDict,32 Field,33 RootModel,34 ValidationError,35 field_serializer,36)37from pydantic.errors import PydanticUndefinedAnnotation38from pydantic.v1 import BaseModel as BaseModelV139from pydantic.v1 import ValidationError as ValidationErrorV140from typing_extensions import TypedDict, override4142from langchain_core import tools43from langchain_core.callbacks import (44 AsyncCallbackManagerForToolRun,45 BaseCallbackHandler,46 CallbackManagerForToolRun,47)48from langchain_core.callbacks.manager import (49 CallbackManagerForRetrieverRun,50)51from langchain_core.documents import Document52from langchain_core.messages import ToolCall, ToolMessage53from langchain_core.messages.tool import ToolOutputMixin54from langchain_core.retrievers import BaseRetriever55from langchain_core.runnables import (56 Runnable,57 RunnableConfig,58 RunnableLambda,59 ensure_config,60)61from langchain_core.tools import (62 BaseTool,63 StructuredTool,64 Tool,65 ToolException,66 convert_runnable_to_tool,67 tool,68)69from langchain_core.tools.base import (70 TOOL_MESSAGE_BLOCK_TYPES,71 ArgsSchema,72 InjectedToolArg,73 InjectedToolCallId,74 SchemaAnnotationError,75 _DirectlyInjectedToolArg,76 _format_output,77 _is_message_content_block,78 _normalize_message_content,79 create_schema_from_function,80 get_all_basemodel_annotations,81)82from langchain_core.utils.function_calling import (83 convert_to_openai_function,84 convert_to_openai_tool,85)86from langchain_core.utils.pydantic import (87 TypeBaseModel,88 _create_subset_model,89 create_model_v2,90 model_json_schema,91)92from tests.unit_tests.fake.callbacks import FakeCallbackHandler93from tests.unit_tests.pydantic_utils import (94 _normalize_schema,95 _schema,96 skip_if_no_pydantic_v1,97)9899try:100 from langgraph.prebuilt import ToolRuntime # type: ignore[import-not-found]101102 HAS_LANGGRAPH = True103except ImportError:104 HAS_LANGGRAPH = False105106107def _get_tool_call_json_schema(tool: BaseTool) -> dict[str, Any]:108 tool_schema = tool.tool_call_schema109 if isinstance(tool_schema, dict):110 return tool_schema111112 if issubclass(tool_schema, BaseModel):113 return tool_schema.model_json_schema()114 if issubclass(tool_schema, BaseModelV1):115 return tool_schema.schema()116 return {} # type: ignore[unreachable]117118119def test_unnamed_decorator() -> None:120 """Test functionality with unnamed decorator."""121122 @tool123 def search_api(query: str) -> str:124 """Search the API for the query."""125 return "API result"126127 assert isinstance(search_api, BaseTool)128 assert search_api.name == "search_api"129 assert not search_api.return_direct130 assert search_api.invoke("test") == "API result"131132133class _MockSchema(BaseModel):134 """Return the arguments directly."""135136 arg1: int137 arg2: bool138 arg3: dict[str, Any] | None = None139140141class _MockStructuredTool(BaseTool):142 name: str = "structured_api"143 args_schema: type[BaseModel] = _MockSchema144 description: str = "A Structured Tool"145146 @override147 def _run(self, *, arg1: int, arg2: bool, arg3: dict[str, Any] | None = None) -> str:148 return f"{arg1} {arg2} {arg3}"149150 async def _arun(151 self, *, arg1: int, arg2: bool, arg3: dict[str, Any] | None = None152 ) -> str:153 raise NotImplementedError154155156class _FakeOutput(ToolOutputMixin):157 """Minimal ToolOutputMixin subclass used only in tests."""158159 def __init__(self, value: int) -> None:160 self.value = value161162 def __eq__(self, other: object) -> bool:163 return isinstance(other, _FakeOutput) and self.value == other.value164165 def __hash__(self) -> int:166 return hash(self.value)167168 def __repr__(self) -> str:169 return f"_FakeOutput({self.value})"170171172def test_structured_args() -> None:173 """Test functionality with structured arguments."""174 structured_api = _MockStructuredTool()175 assert isinstance(structured_api, BaseTool)176 assert structured_api.name == "structured_api"177 expected_result = "1 True {'foo': 'bar'}"178 args = {"arg1": 1, "arg2": True, "arg3": {"foo": "bar"}}179 assert structured_api.run(args) == expected_result180181182def test_misannotated_base_tool_raises_error() -> None:183 """Test that a BaseTool with the incorrect typehint raises an exception."""184 with pytest.raises(SchemaAnnotationError):185186 class _MisAnnotatedTool(BaseTool):187 name: str = "structured_api"188 # This would silently be ignored without the custom metaclass189 args_schema: BaseModel = _MockSchema # type: ignore[assignment]190 description: str = "A Structured Tool"191192 @override193 def _run(194 self, *, arg1: int, arg2: bool, arg3: dict[str, Any] | None = None195 ) -> str:196 return f"{arg1} {arg2} {arg3}"197198 async def _arun(199 self, *, arg1: int, arg2: bool, arg3: dict[str, Any] | None = None200 ) -> str:201 raise NotImplementedError202203204def test_forward_ref_annotated_base_tool_accepted() -> None:205 """Test that a using forward ref annotation syntax is accepted."""206207 class _ForwardRefAnnotatedTool(BaseTool):208 name: str = "structured_api"209 args_schema: "type[BaseModel]" = _MockSchema210 description: str = "A Structured Tool"211212 @override213 def _run(214 self, *, arg1: int, arg2: bool, arg3: dict[str, Any] | None = None215 ) -> str:216 return f"{arg1} {arg2} {arg3}"217218 async def _arun(219 self, *, arg1: int, arg2: bool, arg3: dict[str, Any] | None = None220 ) -> str:221 raise NotImplementedError222223224def test_subclass_annotated_base_tool_accepted() -> None:225 """Test BaseTool child w/ custom schema isn't overwritten."""226227 class _ForwardRefAnnotatedTool(BaseTool):228 name: str = "structured_api"229 args_schema: type[_MockSchema] = _MockSchema230 description: str = "A Structured Tool"231232 @override233 def _run(234 self, *, arg1: int, arg2: bool, arg3: dict[str, Any] | None = None235 ) -> str:236 return f"{arg1} {arg2} {arg3}"237238 async def _arun(239 self, *, arg1: int, arg2: bool, arg3: dict[str, Any] | None = None240 ) -> str:241 raise NotImplementedError242243 assert issubclass(_ForwardRefAnnotatedTool, BaseTool)244 tool = _ForwardRefAnnotatedTool()245 assert tool.args_schema == _MockSchema246247248def test_decorator_with_specified_schema() -> None:249 """Test that manually specified schemata are passed through to the tool."""250251 @tool(args_schema=_MockSchema)252 def tool_func(*, arg1: int, arg2: bool, arg3: dict[str, Any] | None = None) -> str:253 return f"{arg1} {arg2} {arg3}"254255 assert isinstance(tool_func, BaseTool)256 assert tool_func.args_schema == _MockSchema257258259@pytest.mark.skipif(260 sys.version_info >= (3, 14),261 reason="pydantic.v1 namespace not supported with Python 3.14+",262)263def test_decorator_with_specified_schema_pydantic_v1() -> None:264 """Test that manually specified schemata are passed through to the tool."""265266 class _MockSchemaV1(BaseModelV1):267 """Return the arguments directly."""268269 arg1: int270 arg2: bool271 arg3: dict[str, Any] | None = None272273 @tool(args_schema=cast("ArgsSchema", _MockSchemaV1))274 def tool_func_v1(275 *, arg1: int, arg2: bool, arg3: dict[str, Any] | None = None276 ) -> str:277 return f"{arg1} {arg2} {arg3}"278279 assert isinstance(tool_func_v1, BaseTool)280 assert tool_func_v1.args_schema == cast("ArgsSchema", _MockSchemaV1)281282283def test_decorated_function_schema_equivalent() -> None:284 """Test that a BaseTool without a schema meets expectations."""285286 @tool287 def structured_tool_input(288 *, arg1: int, arg2: bool, arg3: dict[str, Any] | None = None289 ) -> str:290 """Return the arguments directly."""291 return f"{arg1} {arg2} {arg3}"292293 assert isinstance(structured_tool_input, BaseTool)294 assert structured_tool_input.args_schema is not None295 assert (296 _schema(structured_tool_input.args_schema)["properties"]297 == _schema(_MockSchema)["properties"]298 == _normalize_schema(structured_tool_input.args)299 )300301302def test_args_kwargs_filtered() -> None:303 class _SingleArgToolWithKwargs(BaseTool):304 name: str = "single_arg_tool"305 description: str = "A single arged tool with kwargs"306307 @override308 def _run(309 self,310 some_arg: str,311 run_manager: CallbackManagerForToolRun | None = None,312 **kwargs: Any,313 ) -> str:314 return "foo"315316 async def _arun(317 self,318 some_arg: str,319 run_manager: AsyncCallbackManagerForToolRun | None = None,320 **kwargs: Any,321 ) -> str:322 raise NotImplementedError323324 tool = _SingleArgToolWithKwargs()325 assert tool.is_single_input326327 class _VarArgToolWithKwargs(BaseTool):328 name: str = "single_arg_tool"329 description: str = "A single arged tool with kwargs"330331 @override332 def _run(333 self,334 *args: Any,335 run_manager: CallbackManagerForToolRun | None = None,336 **kwargs: Any,337 ) -> str:338 return "foo"339340 async def _arun(341 self,342 *args: Any,343 run_manager: AsyncCallbackManagerForToolRun | None = None,344 **kwargs: Any,345 ) -> str:346 raise NotImplementedError347348 tool2 = _VarArgToolWithKwargs()349 assert tool2.is_single_input350351352def test_structured_args_decorator_no_infer_schema() -> None:353 """Test functionality with structured arguments parsed as a decorator."""354355 @tool(infer_schema=False)356 def structured_tool_input(357 arg1: int, arg2: float | datetime, opt_arg: dict[str, Any] | None = None358 ) -> str:359 """Return the arguments directly."""360 return f"{arg1}, {arg2}, {opt_arg}"361362 assert isinstance(structured_tool_input, BaseTool)363 assert structured_tool_input.name == "structured_tool_input"364 args = {"arg1": 1, "arg2": 0.001, "opt_arg": {"foo": "bar"}}365 with pytest.raises(ToolException):366 assert structured_tool_input.run(args)367368369def test_structured_single_str_decorator_no_infer_schema() -> None:370 """Test functionality with structured arguments parsed as a decorator."""371372 @tool(infer_schema=False)373 def unstructured_tool_input(tool_input: str) -> str:374 """Return the arguments directly."""375 assert isinstance(tool_input, str)376 return f"{tool_input}"377378 assert isinstance(unstructured_tool_input, BaseTool)379 assert unstructured_tool_input.args_schema is None380 assert unstructured_tool_input.description == "Return the arguments directly."381 assert unstructured_tool_input.run("foo") == "foo"382383384def test_simple_tool_decorator_no_infer_schema_uses_explicit_description() -> None:385 """Test that a simple tool preserves an explicit description."""386387 @tool(infer_schema=False, description="Echo the supplied input.")388 def echo(tool_input: str) -> str:389 return tool_input390391 assert echo.description == "Echo the supplied input."392393394def test_simple_tool_decorator_no_infer_schema_requires_description_or_docstring() -> (395 None396):397 """Test that a simple tool requires an authored description."""398 with pytest.raises(399 ValueError,400 match="Function must have either a docstring or description",401 ):402403 @tool(infer_schema=False)404 def echo(tool_input: str) -> str:405 return tool_input406407408def test_structured_tool_types_parsed() -> None:409 """Test the non-primitive types are correctly passed to structured tools."""410411 class SomeEnum(Enum):412 A = "a"413 B = "b"414415 class SomeBaseModel(BaseModel):416 foo: str417418 @tool419 def structured_tool(420 some_enum: SomeEnum,421 some_base_model: SomeBaseModel,422 ) -> dict[str, Any]:423 """Return the arguments directly."""424 return {425 "some_enum": some_enum,426 "some_base_model": some_base_model,427 }428429 assert isinstance(structured_tool, StructuredTool)430 args = {431 "some_enum": SomeEnum.A.value,432 "some_base_model": SomeBaseModel(foo="bar").model_dump(),433 }434 result = structured_tool.run(json.loads(json.dumps(args)))435 expected = {436 "some_enum": SomeEnum.A,437 "some_base_model": SomeBaseModel(foo="bar"),438 }439 assert result == expected440441442@pytest.mark.skipif(443 sys.version_info >= (3, 14),444 reason="pydantic.v1 namespace not supported with Python 3.14+",445)446def test_structured_tool_types_parsed_pydantic_v1() -> None:447 """Test the non-primitive types are correctly passed to structured tools."""448449 class SomeBaseModel(BaseModelV1):450 foo: str451452 class AnotherBaseModel(BaseModelV1):453 bar: str454455 @tool456 def structured_tool(some_base_model: SomeBaseModel) -> AnotherBaseModel:457 """Return the arguments directly."""458 return AnotherBaseModel(bar=some_base_model.foo)459460 assert isinstance(structured_tool, StructuredTool)461462 expected = AnotherBaseModel(bar="baz")463 for arg in [464 SomeBaseModel(foo="baz"),465 SomeBaseModel(foo="baz").dict(),466 ]:467 args = {"some_base_model": arg}468 result = structured_tool.run(args)469 assert result == expected470471472def test_structured_tool_types_parsed_pydantic_mixed() -> None:473 """Test handling of tool with mixed Pydantic version arguments."""474475 class SomeBaseModel(BaseModelV1):476 foo: str477478 class AnotherBaseModel(BaseModel):479 bar: str480481 with pytest.raises(NotImplementedError):482483 @tool484 def structured_tool(485 some_base_model: SomeBaseModel, another_base_model: AnotherBaseModel486 ) -> None:487 """Return the arguments directly."""488489490def test_base_tool_inheritance_base_schema() -> None:491 """Test schema is correctly inferred when inheriting from BaseTool."""492493 class _MockSimpleTool(BaseTool):494 name: str = "simple_tool"495 description: str = "A Simple Tool"496497 @override498 def _run(self, tool_input: str) -> str:499 return f"{tool_input}"500501 @override502 async def _arun(self, tool_input: str) -> str:503 raise NotImplementedError504505 simple_tool = _MockSimpleTool()506 assert simple_tool.args_schema is None507 expected_args = {"tool_input": {"title": "Tool Input", "type": "string"}}508 assert simple_tool.args == expected_args509510511def test_tool_lambda_args_schema() -> None:512 """Test args schema inference when the tool argument is a lambda function."""513 tool = Tool(514 name="tool",515 description="A tool",516 func=lambda tool_input: tool_input,517 )518 assert tool.args_schema is None519 expected_args = {"tool_input": {"type": "string"}}520 assert tool.args == expected_args521522523def test_structured_tool_from_function_docstring() -> None:524 """Test that structured tools can be created from functions."""525526 def foo(bar: int, baz: str) -> str:527 """Docstring.528529 Args:530 bar: the bar value531 baz: the baz value532 """533 raise NotImplementedError534535 structured_tool = StructuredTool.from_function(foo)536 assert structured_tool.name == "foo"537 assert structured_tool.args == {538 "bar": {"title": "Bar", "type": "integer"},539 "baz": {"title": "Baz", "type": "string"},540 }541542 assert _schema(structured_tool.args_schema) == {543 "properties": {544 "bar": {"title": "Bar", "type": "integer"},545 "baz": {"title": "Baz", "type": "string"},546 },547 "description": inspect.getdoc(foo),548 "title": "foo",549 "type": "object",550 "required": ["bar", "baz"],551 }552553 assert foo.__doc__ is not None554 assert structured_tool.description == textwrap.dedent(foo.__doc__.strip())555556557def test_structured_tool_from_function_docstring_complex_args() -> None:558 """Test that structured tools can be created from functions."""559560 def foo(bar: int, baz: list[str]) -> str:561 """Docstring.562563 Args:564 bar: int565 baz: list[str]566 """567 raise NotImplementedError568569 structured_tool = StructuredTool.from_function(foo)570 assert structured_tool.name == "foo"571 assert structured_tool.args == {572 "bar": {"title": "Bar", "type": "integer"},573 "baz": {574 "title": "Baz",575 "type": "array",576 "items": {"type": "string"},577 },578 }579580 assert _schema(structured_tool.args_schema) == {581 "properties": {582 "bar": {"title": "Bar", "type": "integer"},583 "baz": {584 "title": "Baz",585 "type": "array",586 "items": {"type": "string"},587 },588 },589 "description": inspect.getdoc(foo),590 "title": "foo",591 "type": "object",592 "required": ["bar", "baz"],593 }594595 assert foo.__doc__ is not None596 assert structured_tool.description == textwrap.dedent(foo.__doc__).strip()597598599def test_structured_tool_lambda_multi_args_schema() -> None:600 """Test args schema inference when the tool argument is a lambda function."""601 tool = StructuredTool.from_function(602 name="tool",603 description="A tool",604 func=lambda tool_input, other_arg: f"{tool_input}{other_arg}",605 )606 assert tool.args_schema is not None607 expected_args = {608 "tool_input": {"title": "Tool Input"},609 "other_arg": {"title": "Other Arg"},610 }611 assert tool.args == expected_args612613614def test_tool_partial_function_args_schema() -> None:615 """Test args schema inference when the tool argument is a partial function."""616617 def func(tool_input: str, other_arg: str) -> str:618 assert isinstance(tool_input, str)619 assert isinstance(other_arg, str)620 return tool_input + other_arg621622 tool = Tool(623 name="tool",624 description="A tool",625 func=partial(func, other_arg="foo"),626 )627 assert tool.run("bar") == "barfoo"628629630def test_empty_args_decorator() -> None:631 """Test inferred schema of decorated fn with no args."""632633 @tool634 def empty_tool_input() -> str:635 """Return a constant."""636 return "the empty result"637638 assert isinstance(empty_tool_input, BaseTool)639 assert empty_tool_input.name == "empty_tool_input"640 assert empty_tool_input.args == {}641 assert empty_tool_input.run({}) == "the empty result"642643644def test_tool_from_function_with_run_manager() -> None:645 """Test run of tool when using run_manager."""646647 def foo(bar: str, callbacks: CallbackManagerForToolRun | None = None) -> str: # noqa: D417648 """Docstring.649650 Args:651 bar: str.652 """653 assert callbacks is not None654 return "foo" + bar655656 handler = FakeCallbackHandler()657 tool = Tool.from_function(foo, name="foo", description="Docstring")658659 assert tool.run(tool_input={"bar": "bar"}, run_manager=[handler]) == "foobar"660 assert tool.run("baz", run_manager=[handler]) == "foobaz"661662663def test_structured_tool_from_function_with_run_manager() -> None:664 """Test args and schema of structured tool when using callbacks."""665666 def foo( # noqa: D417667 bar: int, baz: str, callbacks: CallbackManagerForToolRun | None = None668 ) -> str:669 """Docstring.670671 Args:672 bar: int673 baz: str674 """675 assert callbacks is not None676 return str(bar) + baz677678 handler = FakeCallbackHandler()679 structured_tool = StructuredTool.from_function(foo)680681 assert structured_tool.args == {682 "bar": {"title": "Bar", "type": "integer"},683 "baz": {"title": "Baz", "type": "string"},684 }685686 assert _schema(structured_tool.args_schema) == {687 "properties": {688 "bar": {"title": "Bar", "type": "integer"},689 "baz": {"title": "Baz", "type": "string"},690 },691 "description": inspect.getdoc(foo),692 "title": "foo",693 "type": "object",694 "required": ["bar", "baz"],695 }696697 assert (698 structured_tool.run(699 tool_input={"bar": "10", "baz": "baz"}, run_manger=[handler]700 )701 == "10baz"702 )703704705def test_structured_tool_from_parameterless_function() -> None:706 """Test parameterless function of structured tool."""707708 def foo() -> str:709 """Docstring."""710 return "invoke foo"711712 structured_tool = StructuredTool.from_function(foo)713714 assert structured_tool.run({}) == "invoke foo"715 assert structured_tool.run("") == "invoke foo"716717718def test_named_tool_decorator() -> None:719 """Test functionality when arguments are provided as input to decorator."""720721 @tool("search")722 def search_api(query: str) -> str:723 """Search the API for the query."""724 assert isinstance(query, str)725 return f"API result - {query}"726727 assert isinstance(search_api, BaseTool)728 assert search_api.name == "search"729 assert not search_api.return_direct730 assert search_api.run({"query": "foo"}) == "API result - foo"731732733def test_named_tool_decorator_return_direct() -> None:734 """Test functionality when arguments and return direct are provided as input."""735736 @tool("search", return_direct=True)737 def search_api(query: str, *args: Any) -> str:738 """Search the API for the query."""739 return "API result"740741 assert isinstance(search_api, BaseTool)742 assert search_api.name == "search"743 assert search_api.return_direct744 assert search_api.run({"query": "foo"}) == "API result"745746747def test_unnamed_tool_decorator_return_direct() -> None:748 """Test functionality when only return direct is provided."""749750 @tool(return_direct=True)751 def search_api(query: str) -> str:752 """Search the API for the query."""753 assert isinstance(query, str)754 return "API result"755756 assert isinstance(search_api, BaseTool)757 assert search_api.name == "search_api"758 assert search_api.return_direct759 assert search_api.run({"query": "foo"}) == "API result"760761762def test_tool_with_kwargs() -> None:763 """Test functionality when only return direct is provided."""764765 @tool(return_direct=True)766 def search_api(767 arg_0: str,768 arg_1: float = 4.3,769 ping: str = "hi",770 ) -> str:771 """Search the API for the query."""772 return f"arg_0={arg_0}, arg_1={arg_1}, ping={ping}"773774 assert isinstance(search_api, BaseTool)775 result = search_api.run(776 tool_input={777 "arg_0": "foo",778 "arg_1": 3.2,779 "ping": "pong",780 }781 )782 assert result == "arg_0=foo, arg_1=3.2, ping=pong"783784 result = search_api.run(785 tool_input={786 "arg_0": "foo",787 }788 )789 assert result == "arg_0=foo, arg_1=4.3, ping=hi"790 # For backwards compatibility, we still accept a single str arg791 result = search_api.run("foobar")792 assert result == "arg_0=foobar, arg_1=4.3, ping=hi"793794795def test_missing_docstring() -> None:796 """Test error is raised when docstring is missing."""797 # expect to throw a value error if there's no docstring798 with pytest.raises(ValueError, match="Function must have a docstring"):799800 @tool801 def search_api(query: str) -> str:802 return "API result"803804 @tool805 class MyTool(BaseModel):806 foo: str807808 assert not MyTool.description # type: ignore[attr-defined]809810811def test_create_tool_positional_args() -> None:812 """Test that positional arguments are allowed."""813 test_tool = Tool("test_name", lambda x: x, "test_description")814 assert test_tool.invoke("foo") == "foo"815 assert test_tool.name == "test_name"816 assert test_tool.description == "test_description"817 assert test_tool.is_single_input818819820def test_create_tool_keyword_args() -> None:821 """Test that keyword arguments are allowed."""822 test_tool = Tool(name="test_name", func=lambda x: x, description="test_description")823 assert test_tool.is_single_input824 assert test_tool.invoke("foo") == "foo"825 assert test_tool.name == "test_name"826 assert test_tool.description == "test_description"827828829async def test_create_async_tool() -> None:830 """Test that async tools are allowed."""831832 async def _test_func(x: str) -> str:833 return x834835 test_tool = Tool(836 name="test_name",837 func=lambda x: x,838 description="test_description",839 coroutine=_test_func,840 )841 assert test_tool.is_single_input842 assert test_tool.invoke("foo") == "foo"843 assert test_tool.name == "test_name"844 assert test_tool.description == "test_description"845 assert test_tool.coroutine is not None846 assert await test_tool.arun("foo") == "foo"847848849class _FakeExceptionTool(BaseTool):850 name: str = "exception"851 description: str = "an exception-throwing tool"852 exception: Exception = ToolException()853854 def _run(self) -> str:855 raise self.exception856857 async def _arun(self) -> str:858 raise self.exception859860861def test_exception_handling_bool() -> None:862 tool_ = _FakeExceptionTool(handle_tool_error=True)863 expected = "Tool execution error"864 actual = tool_.run({})865 assert expected == actual866867868def test_exception_handling_str() -> None:869 expected = "foo bar"870 tool_ = _FakeExceptionTool(handle_tool_error=expected)871 actual = tool_.run({})872 assert expected == actual873874875def test_exception_handling_callable() -> None:876 expected = "foo bar"877878 def handling(e: ToolException) -> str:879 return expected880881 tool_ = _FakeExceptionTool(handle_tool_error=handling)882 actual = tool_.run({})883 assert expected == actual884885886def test_exception_handling_callable_message_content_blocks() -> None:887 expected: list[dict[str, Any]] = [{"type": "text", "text": "handled error"}]888889 def handling(e: ToolException) -> list[dict[str, Any]]:890 return expected891892 tool_ = _FakeExceptionTool(handle_tool_error=handling)893 actual = tool_.invoke(894 {895 "type": "tool_call",896 "args": {},897 "name": "exception",898 "id": "call_1",899 }900 )901902 assert isinstance(actual, ToolMessage)903 assert actual.content == expected904 assert actual.status == "error"905 assert actual.tool_call_id == "call_1"906907908def test_exception_handling_callable_message_content_blocks_sequence() -> None:909 content = ({"type": "text", "text": "handled error"},)910911 def handling(e: ToolException) -> tuple[dict[str, Any], ...]:912 return content913914 tool_ = _FakeExceptionTool(handle_tool_error=handling)915 actual = tool_.invoke(916 {917 "type": "tool_call",918 "args": {},919 "name": "exception",920 "id": "call_1",921 }922 )923924 assert isinstance(actual, ToolMessage)925 assert actual.content == list(content)926 assert actual.status == "error"927 assert actual.tool_call_id == "call_1"928929930def test_exception_handling_callable_invalid_blocks_stringified() -> None:931 # A sequence whose elements are not valid content blocks is not message932 # content, so it falls back to a JSON-stringified ToolMessage.933 def handling(e: ToolException) -> list[dict[str, Any]]:934 return [{"text": "foo"}] # missing 'type' -> not a valid block935936 tool_ = _FakeExceptionTool(handle_tool_error=handling)937 actual = tool_.invoke(938 {939 "type": "tool_call",940 "args": {},941 "name": "exception",942 "id": "call_1",943 }944 )945946 assert isinstance(actual, ToolMessage)947 assert actual.content == '[{"text": "foo"}]'948 assert actual.status == "error"949 assert actual.tool_call_id == "call_1"950951952def test_exception_handling_non_tool_exception() -> None:953 tool_ = _FakeExceptionTool(exception=ValueError("some error"))954 with pytest.raises(ValueError, match="some error"):955 tool_.run({})956957958async def test_async_exception_handling_bool() -> None:959 tool_ = _FakeExceptionTool(handle_tool_error=True)960 expected = "Tool execution error"961 actual = await tool_.arun({})962 assert expected == actual963964965async def test_async_exception_handling_str() -> None:966 expected = "foo bar"967 tool_ = _FakeExceptionTool(handle_tool_error=expected)968 actual = await tool_.arun({})969 assert expected == actual970971972async def test_async_exception_handling_callable() -> None:973 expected = "foo bar"974975 def handling(e: ToolException) -> str:976 return expected977978 tool_ = _FakeExceptionTool(handle_tool_error=handling)979 actual = await tool_.arun({})980 assert expected == actual981982983async def test_async_exception_handling_callable_message_content_blocks() -> None:984 expected: list[dict[str, Any]] = [{"type": "text", "text": "handled error"}]985986 def handling(e: ToolException) -> list[dict[str, Any]]:987 return expected988989 tool_ = _FakeExceptionTool(handle_tool_error=handling)990 actual = await tool_.ainvoke(991 {992 "type": "tool_call",993 "args": {},994 "name": "exception",995 "id": "call_1",996 }997 )998999 assert isinstance(actual, ToolMessage)1000 assert actual.content == expected1001 assert actual.status == "error"1002 assert actual.tool_call_id == "call_1"100310041005async def test_async_exception_handling_callable_message_content_blocks_sequence() -> (1006 None1007):1008 content = ({"type": "text", "text": "handled error"},)10091010 def handling(e: ToolException) -> tuple[dict[str, Any], ...]:1011 return content10121013 tool_ = _FakeExceptionTool(handle_tool_error=handling)1014 actual = await tool_.ainvoke(1015 {1016 "type": "tool_call",1017 "args": {},1018 "name": "exception",1019 "id": "call_1",1020 }1021 )10221023 assert isinstance(actual, ToolMessage)1024 assert actual.content == list(content)1025 assert actual.status == "error"1026 assert actual.tool_call_id == "call_1"102710281029async def test_async_exception_handling_non_tool_exception() -> None:1030 tool_ = _FakeExceptionTool(exception=ValueError("some error"))1031 with pytest.raises(ValueError, match="some error"):1032 await tool_.arun({})103310341035def test_structured_tool_from_function() -> None:1036 """Test that structured tools can be created from functions."""10371038 def foo(bar: int, baz: str) -> str:1039 """Docstring thing.10401041 Args:1042 bar: the bar value1043 baz: the baz value1044 """1045 raise NotImplementedError10461047 structured_tool = StructuredTool.from_function(foo)1048 assert structured_tool.name == "foo"1049 assert structured_tool.args == {1050 "bar": {"title": "Bar", "type": "integer"},1051 "baz": {"title": "Baz", "type": "string"},1052 }10531054 assert _schema(structured_tool.args_schema) == {1055 "title": "foo",1056 "type": "object",1057 "description": inspect.getdoc(foo),1058 "properties": {1059 "bar": {"title": "Bar", "type": "integer"},1060 "baz": {"title": "Baz", "type": "string"},1061 },1062 "required": ["bar", "baz"],1063 }10641065 assert foo.__doc__ is not None1066 assert structured_tool.description == textwrap.dedent(foo.__doc__.strip())106710681069def test_validation_error_handling_bool() -> None:1070 """Test that validation errors are handled correctly."""1071 expected = "Tool input validation error"1072 tool_ = _MockStructuredTool(handle_validation_error=True)1073 actual = tool_.run({})1074 assert expected == actual107510761077def test_validation_error_handling_str() -> None:1078 """Test that validation errors are handled correctly."""1079 expected = "foo bar"1080 tool_ = _MockStructuredTool(handle_validation_error=expected)1081 actual = tool_.run({})1082 assert expected == actual108310841085def test_validation_error_handling_callable() -> None:1086 """Test that validation errors are handled correctly."""1087 expected = "foo bar"10881089 def handling(e: ValidationError | ValidationErrorV1) -> str:1090 return expected10911092 tool_ = _MockStructuredTool(handle_validation_error=handling)1093 actual = tool_.run({})1094 assert expected == actual109510961097@pytest.mark.parametrize(1098 "handler",1099 [1100 True,1101 "foo bar",1102 lambda _: "foo bar",1103 ],1104)1105def test_validation_error_handling_non_validation_error(1106 *,1107 handler: bool | str | Callable[[ValidationError | ValidationErrorV1], str],1108) -> None:1109 """Test that validation errors are handled correctly."""11101111 class _RaiseNonValidationErrorTool(BaseTool):1112 name: str = "raise_non_validation_error_tool"1113 description: str = "A tool that raises a non-validation error"11141115 def _parse_input(1116 self,1117 tool_input: str | dict[str, Any],1118 tool_call_id: str | None,1119 ) -> str | dict[str, Any]:1120 raise NotImplementedError11211122 @override1123 def _run(self) -> str:1124 return "dummy"11251126 @override1127 async def _arun(self) -> str:1128 return "dummy"11291130 tool_ = _RaiseNonValidationErrorTool(handle_validation_error=handler)1131 with pytest.raises(NotImplementedError):1132 tool_.run({})113311341135async def test_async_validation_error_handling_bool() -> None:1136 """Test that validation errors are handled correctly."""1137 expected = "Tool input validation error"1138 tool_ = _MockStructuredTool(handle_validation_error=True)1139 actual = await tool_.arun({})1140 assert expected == actual114111421143async def test_async_validation_error_handling_str() -> None:1144 """Test that validation errors are handled correctly."""1145 expected = "foo bar"1146 tool_ = _MockStructuredTool(handle_validation_error=expected)1147 actual = await tool_.arun({})1148 assert expected == actual114911501151async def test_async_validation_error_handling_callable() -> None:1152 """Test that validation errors are handled correctly."""1153 expected = "foo bar"11541155 def handling(e: ValidationError | ValidationErrorV1) -> str:1156 return expected11571158 tool_ = _MockStructuredTool(handle_validation_error=handling)1159 actual = await tool_.arun({})1160 assert expected == actual116111621163@pytest.mark.skipif(1164 sys.version_info >= (3, 14),1165 reason="pydantic.v1 namespace not supported with Python 3.14+",1166)1167async def test_async_validation_error_handling_pydantic_v1_schema() -> None:1168 """Test async validation error handling for Pydantic V1 schemas."""11691170 class Args(BaseModelV1):1171 x: int11721173 def foo(x: int) -> str:1174 """Return x as text."""1175 return str(x)11761177 tool_ = StructuredTool.from_function(1178 foo,1179 args_schema=cast("ArgsSchema", Args),1180 handle_validation_error=True,1181 )11821183 assert tool_.run({"x": "not-an-integer"}) == "Tool input validation error"1184 assert await tool_.arun({"x": "not-an-integer"}) == "Tool input validation error"118511861187@pytest.mark.parametrize(1188 "handler",1189 [1190 True,1191 "foo bar",1192 lambda _: "foo bar",1193 ],1194)1195async def test_async_validation_error_handling_non_validation_error(1196 *,1197 handler: bool | str | Callable[[ValidationError | ValidationErrorV1], str],1198) -> None:1199 """Test that validation errors are handled correctly."""12001201 class _RaiseNonValidationErrorTool(BaseTool):1202 name: str = "raise_non_validation_error_tool"1203 description: str = "A tool that raises a non-validation error"12041205 def _parse_input(1206 self,1207 tool_input: str | dict[str, Any],1208 tool_call_id: str | None,1209 ) -> str | dict[str, Any]:1210 raise NotImplementedError12111212 @override1213 def _run(self) -> str:1214 return "dummy"12151216 @override1217 async def _arun(self) -> str:1218 return "dummy"12191220 tool_ = _RaiseNonValidationErrorTool(handle_validation_error=handler)1221 with pytest.raises(NotImplementedError):1222 await tool_.arun({})122312241225class _ToolErrorCaptureHandler(BaseCallbackHandler):1226 """Callback handler that captures errors passed to `on_tool_error`."""12271228 def __init__(self) -> None:1229 self.tool_errors: list[BaseException] = []12301231 @override1232 def on_tool_error(1233 self,1234 error: BaseException,1235 *,1236 run_id: Any,1237 parent_run_id: Any | None = None,1238 **kwargs: Any,1239 ) -> Any:1240 self.tool_errors.append(error)124112421243def test_tool_base_exception_calls_on_tool_error() -> None:1244 """A `BaseException` raised by a sync tool ends the tool run with an error."""12451246 @tool1247 def cancelled_tool() -> str:1248 """Raise `CancelledError`."""1249 raise asyncio.CancelledError12501251 handler = _ToolErrorCaptureHandler()1252 with pytest.raises(asyncio.CancelledError):1253 cancelled_tool.invoke({}, config={"callbacks": [handler]})12541255 assert len(handler.tool_errors) == 11256 assert isinstance(handler.tool_errors[0], asyncio.CancelledError)125712581259async def test_async_tool_cancellation_calls_on_tool_error() -> None:1260 """Cancelling an async tool ends the tool run and still cancels the caller."""1261 started = asyncio.Event()12621263 @tool1264 async def slow_tool() -> str:1265 """Wait until cancelled."""1266 started.set()1267 await asyncio.Event().wait()1268 return "unreachable"12691270 handler = _ToolErrorCaptureHandler()1271 task = asyncio.create_task(slow_tool.ainvoke({}, config={"callbacks": [handler]}))1272 await started.wait()1273 task.cancel()1274 with pytest.raises(asyncio.CancelledError):1275 await task12761277 assert len(handler.tool_errors) == 11278 assert isinstance(handler.tool_errors[0], asyncio.CancelledError)127912801281def test_optional_subset_model_rewrite() -> None:1282 class MyModel(BaseModel):1283 a: str | None = None1284 b: str1285 c: list[str | None] | None = None12861287 model2 = _create_subset_model("model2", MyModel, ["a", "b", "c"])12881289 assert set(_schema(model2)["required"]) == {"b"}129012911292@pytest.mark.parametrize(1293 ("inputs", "expected"),1294 [1295 # Check not required1296 ({"bar": "bar"}, {"bar": "bar", "baz": 3, "buzz": "buzz"}),1297 # Check overwritten1298 (1299 {"bar": "bar", "baz": 4, "buzz": "not-buzz"},1300 {"bar": "bar", "baz": 4, "buzz": "not-buzz"},1301 ),1302 # Check validation error when missing1303 ({}, None),1304 # Check validation error when wrong type1305 ({"bar": "bar", "baz": "not-an-int"}, None),1306 # Check OK when None explicitly passed1307 ({"bar": "bar", "baz": None}, {"bar": "bar", "baz": None, "buzz": "buzz"}),1308 ],1309)1310def test_tool_invoke_optional_args(1311 inputs: dict[str, Any], expected: dict[str, Any] | None1312) -> None:1313 @tool1314 def foo(bar: str, baz: int | None = 3, buzz: str | None = "buzz") -> dict[str, Any]:1315 """The foo."""1316 return {1317 "bar": bar,1318 "baz": baz,1319 "buzz": buzz,1320 }13211322 if expected is not None:1323 assert foo.invoke(inputs) == expected1324 else:1325 with pytest.raises(ValidationError):1326 foo.invoke(inputs)132713281329def test_tool_pass_context() -> None:1330 @tool1331 def foo(bar: str) -> str:1332 """The foo."""1333 config = ensure_config()1334 assert config["configurable"]["foo"] == "not-bar"1335 assert bar == "baz"1336 return bar13371338 assert foo.invoke({"bar": "baz"}, {"configurable": {"foo": "not-bar"}}) == "baz"133913401341async def test_async_tool_pass_context() -> None:1342 @tool1343 async def foo(bar: str) -> str:1344 """The foo."""1345 config = ensure_config()1346 assert config["configurable"]["foo"] == "not-bar"1347 assert bar == "baz"1348 return bar13491350 assert (1351 await foo.ainvoke({"bar": "baz"}, {"configurable": {"foo": "not-bar"}}) == "baz"1352 )135313541355def assert_bar(bar: Any, bar_config: RunnableConfig) -> Any:1356 assert bar_config["configurable"]["foo"] == "not-bar"1357 assert bar == "baz"1358 return bar135913601361@tool1362def foo(bar: Any, bar_config: RunnableConfig) -> Any:1363 """The foo."""1364 return assert_bar(bar, bar_config)136513661367@tool1368async def afoo(bar: Any, bar_config: RunnableConfig) -> Any:1369 """The foo."""1370 return assert_bar(bar, bar_config)137113721373@tool(infer_schema=False)1374def simple_foo(bar: Any, bar_config: RunnableConfig) -> Any:1375 """The foo."""1376 return assert_bar(bar, bar_config)137713781379@tool(infer_schema=False)1380async def asimple_foo(bar: Any, bar_config: RunnableConfig) -> Any:1381 """The foo."""1382 return assert_bar(bar, bar_config)138313841385class FooBase(BaseTool):1386 name: str = "Foo"1387 description: str = "Foo"13881389 @override1390 def _run(self, bar: Any, bar_config: RunnableConfig, **kwargs: Any) -> Any:1391 return assert_bar(bar, bar_config)139213931394class AFooBase(FooBase):1395 @override1396 async def _arun(self, bar: Any, bar_config: RunnableConfig, **kwargs: Any) -> Any:1397 return assert_bar(bar, bar_config)139813991400@pytest.mark.parametrize("tool", [foo, simple_foo, FooBase(), AFooBase()])1401def test_tool_pass_config(tool: BaseTool) -> None:1402 assert tool.invoke({"bar": "baz"}, {"configurable": {"foo": "not-bar"}}) == "baz"14031404 # Test we don't mutate tool calls1405 tool_call = {1406 "name": tool.name,1407 "args": {"bar": "baz"},1408 "id": "abc123",1409 "type": "tool_call",1410 }1411 _ = tool.invoke(tool_call, {"configurable": {"foo": "not-bar"}})1412 assert tool_call["args"] == {"bar": "baz"}141314141415class FooBaseNonPickleable(FooBase):1416 @override1417 def _run(self, bar: Any, bar_config: RunnableConfig, **kwargs: Any) -> Any:1418 return True141914201421def test_tool_pass_config_non_pickleable() -> None:1422 tool = FooBaseNonPickleable()14231424 args = {"bar": threading.Lock()}1425 tool_call = {1426 "name": tool.name,1427 "args": args,1428 "id": "abc123",1429 "type": "tool_call",1430 }1431 _ = tool.invoke(tool_call, {"configurable": {"foo": "not-bar"}})1432 assert tool_call["args"] == args143314341435@pytest.mark.parametrize(1436 "tool", [foo, afoo, simple_foo, asimple_foo, FooBase(), AFooBase()]1437)1438async def test_async_tool_pass_config(tool: BaseTool) -> None:1439 assert (1440 await tool.ainvoke({"bar": "baz"}, {"configurable": {"foo": "not-bar"}})1441 == "baz"1442 )144314441445def test_tool_description() -> None:1446 def foo(bar: str) -> str:1447 """The foo."""1448 return bar14491450 foo1 = tool(foo)1451 assert foo1.description == "The foo."14521453 foo2 = StructuredTool.from_function(foo)1454 assert foo2.description == "The foo."145514561457def test_tool_arg_descriptions() -> None:1458 def foo(bar: str, baz: int) -> str:1459 """The foo.14601461 Args:1462 bar: The bar.1463 baz: The baz.1464 """1465 return bar14661467 foo1 = tool(foo)1468 args_schema = _schema(foo1.args_schema)1469 assert args_schema == {1470 "title": "foo",1471 "type": "object",1472 "description": inspect.getdoc(foo),1473 "properties": {1474 "bar": {"title": "Bar", "type": "string"},1475 "baz": {"title": "Baz", "type": "integer"},1476 },1477 "required": ["bar", "baz"],1478 }14791480 # Test parses docstring1481 foo2 = tool(foo, parse_docstring=True)1482 args_schema = _schema(foo2.args_schema)1483 expected = {1484 "title": "foo",1485 "description": "The foo.",1486 "type": "object",1487 "properties": {1488 "bar": {"title": "Bar", "description": "The bar.", "type": "string"},1489 "baz": {"title": "Baz", "description": "The baz.", "type": "integer"},1490 },1491 "required": ["bar", "baz"],1492 }1493 assert args_schema == expected14941495 # Test parsing with run_manager does not raise error1496 def foo3( # noqa: D4171497 bar: str, baz: int, run_manager: CallbackManagerForToolRun | None = None1498 ) -> str:1499 """The foo.15001501 Args:1502 bar: The bar.1503 baz: The baz.1504 """1505 return bar15061507 as_tool = tool(foo3, parse_docstring=True)1508 args_schema = _schema(as_tool.args_schema)1509 assert args_schema["description"] == expected["description"]1510 assert args_schema["properties"] == expected["properties"]15111512 # Test parsing with runtime does not raise error1513 def foo3_runtime(bar: str, baz: int, runtime: Any) -> str: # noqa: D4171514 """The foo.15151516 Args:1517 bar: The bar.1518 baz: The baz.1519 """1520 return bar15211522 _ = tool(foo3_runtime, parse_docstring=True)15231524 # Test parameterless tool does not raise error for missing Args section1525 # in docstring.1526 def foo4() -> str:1527 """The foo."""1528 return "bar"15291530 as_tool = tool(foo4, parse_docstring=True)1531 args_schema = _schema(as_tool.args_schema)1532 assert args_schema["description"] == expected["description"]15331534 def foo5(run_manager: CallbackManagerForToolRun | None = None) -> str:1535 """The foo."""1536 return "bar"15371538 as_tool = tool(foo5, parse_docstring=True)1539 args_schema = _schema(as_tool.args_schema)1540 assert args_schema["description"] == expected["description"]154115421543def test_docstring_parsing() -> None:1544 expected = {1545 "title": "foo",1546 "description": "The foo.",1547 "type": "object",1548 "properties": {1549 "bar": {"title": "Bar", "description": "The bar.", "type": "string"},1550 "baz": {"title": "Baz", "description": "The baz.", "type": "integer"},1551 },1552 "required": ["bar", "baz"],1553 }15541555 # Simple case1556 def foo(bar: str, baz: int) -> str:1557 """The foo.15581559 Args:1560 bar: The bar.1561 baz: The baz.1562 """1563 return bar15641565 as_tool = tool(foo, parse_docstring=True)1566 args_schema = _schema(as_tool.args_schema)1567 assert args_schema["description"] == "The foo."1568 assert args_schema["properties"] == expected["properties"]15691570 # Multi-line description1571 def foo2(bar: str, baz: int) -> str:1572 """The foo.15731574 Additional description here.15751576 Args:1577 bar: The bar.1578 baz: The baz.1579 """1580 return bar15811582 as_tool = tool(foo2, parse_docstring=True)1583 args_schema2 = _schema(as_tool.args_schema)1584 assert args_schema2["description"] == "The foo. Additional description here."1585 assert args_schema2["properties"] == expected["properties"]15861587 # Multi-line with Returns block1588 def foo3(bar: str, baz: int) -> str:1589 """The foo.15901591 Additional description here.15921593 Args:1594 bar: The bar.1595 baz: The baz.15961597 Returns:1598 description of returned value.1599 """1600 return bar16011602 as_tool = tool(foo3, parse_docstring=True)1603 args_schema3 = _schema(as_tool.args_schema)1604 args_schema3["title"] = "foo2"1605 assert args_schema2 == args_schema316061607 # Single argument1608 def foo4(bar: str) -> str:1609 """The foo.16101611 Args:1612 bar: The bar.1613 """1614 return bar16151616 as_tool = tool(foo4, parse_docstring=True)1617 args_schema4 = _schema(as_tool.args_schema)1618 assert args_schema4["description"] == "The foo."1619 assert args_schema4["properties"] == {1620 "bar": {"description": "The bar.", "title": "Bar", "type": "string"}1621 }162216231624def test_tool_invalid_docstrings() -> None:1625 """Test invalid docstrings."""16261627 def foo3(bar: str, baz: int) -> str:1628 """The foo."""1629 return bar16301631 def foo4(bar: str, baz: int) -> str:1632 """The foo.1633 Args:1634 bar: The bar.1635 baz: The baz.1636 """ # noqa: D205,D411 # We're intentionally testing bad formatting.1637 return bar16381639 for func in {foo3, foo4}:1640 with pytest.raises(ValueError, match="Found invalid Google-Style docstring"):1641 _ = tool(func, parse_docstring=True)16421643 def foo5(bar: str, baz: int) -> str: # noqa: D4171644 """The foo.16451646 Args:1647 banana: The bar.1648 monkey: The baz.1649 """1650 return bar16511652 with pytest.raises(1653 ValueError, match="Arg banana in docstring not found in function signature"1654 ):1655 _ = tool(foo5, parse_docstring=True)165616571658def test_tool_annotated_descriptions() -> None:1659 def foo(1660 bar: Annotated[str, "this is the bar"], baz: Annotated[int, "this is the baz"]1661 ) -> str:1662 """The foo.16631664 Returns:1665 The bar only.1666 """1667 return bar16681669 foo1 = tool(foo)1670 args_schema = _schema(foo1.args_schema)1671 assert args_schema == {1672 "title": "foo",1673 "type": "object",1674 "description": inspect.getdoc(foo),1675 "properties": {1676 "bar": {"title": "Bar", "type": "string", "description": "this is the bar"},1677 "baz": {1678 "title": "Baz",1679 "type": "integer",1680 "description": "this is the baz",1681 },1682 },1683 "required": ["bar", "baz"],1684 }168516861687def test_tool_field_description_preserved() -> None:1688 """Test that `Field(description=...)` is preserved in `@tool` decorator."""16891690 @tool1691 def my_tool(1692 topic: Annotated[str, Field(description="The research topic")],1693 depth: Annotated[int, Field(description="Search depth level")] = 3,1694 ) -> str:1695 """A tool for research."""1696 return f"{topic} at depth {depth}"16971698 args_schema = _schema(my_tool.args_schema)1699 assert args_schema == {1700 "title": "my_tool",1701 "type": "object",1702 "description": "A tool for research.",1703 "properties": {1704 "topic": {1705 "title": "Topic",1706 "type": "string",1707 "description": "The research topic",1708 },1709 "depth": {1710 "title": "Depth",1711 "type": "integer",1712 "description": "Search depth level",1713 "default": 3,1714 },1715 },1716 "required": ["topic"],1717 }171817191720def test_tool_call_input_tool_message_output() -> None:1721 tool_call = {1722 "name": "structured_api",1723 "args": {"arg1": 1, "arg2": True, "arg3": {"img": "base64string..."}},1724 "id": "123",1725 "type": "tool_call",1726 }1727 tool = _MockStructuredTool()1728 expected = ToolMessage(1729 "1 True {'img': 'base64string...'}", tool_call_id="123", name="structured_api"1730 )1731 actual = tool.invoke(tool_call)1732 assert actual == expected17331734 tool_call.pop("type")1735 with pytest.raises(ValidationError):1736 tool.invoke(tool_call)173717381739@pytest.mark.parametrize("block_type", [*TOOL_MESSAGE_BLOCK_TYPES, "bad"])1740def test_tool_content_block_output(block_type: str) -> None:1741 @tool1742 def my_tool(query: str) -> list[dict[str, Any]]:1743 """Test tool."""1744 return [{"type": block_type, "foo": "bar"}]17451746 tool_call = {1747 "type": "tool_call",1748 "name": "my_tool",1749 "args": {"query": "baz"},1750 "id": "call_abc123",1751 }17521753 result = my_tool.invoke(tool_call)1754 assert isinstance(result, ToolMessage)17551756 if block_type in TOOL_MESSAGE_BLOCK_TYPES:1757 assert result.content == [{"type": block_type, "foo": "bar"}]1758 else:1759 assert result.content == '[{"type": "bad", "foo": "bar"}]'176017611762class _MockStructuredToolWithRawOutput(BaseTool):1763 name: str = "structured_api"1764 args_schema: type[BaseModel] = _MockSchema1765 description: str = "A Structured Tool"1766 response_format: Literal["content_and_artifact"] = "content_and_artifact"17671768 @override1769 def _run(1770 self,1771 arg1: int,1772 arg2: bool,1773 arg3: dict[str, Any] | None = None,1774 ) -> tuple[str, dict[str, Any]]:1775 return f"{arg1} {arg2}", {"arg1": arg1, "arg2": arg2, "arg3": arg3}177617771778@tool("structured_api", response_format="content_and_artifact")1779def _mock_structured_tool_with_artifact(1780 *, arg1: int, arg2: bool, arg3: dict[str, str] | None = None1781) -> tuple[str, dict[str, Any]]:1782 """A Structured Tool."""1783 return f"{arg1} {arg2}", {"arg1": arg1, "arg2": arg2, "arg3": arg3}178417851786@pytest.mark.parametrize(1787 "tool", [_MockStructuredToolWithRawOutput(), _mock_structured_tool_with_artifact]1788)1789def test_tool_call_input_tool_message_with_artifact(tool: BaseTool) -> None:1790 tool_call: dict[str, Any] = {1791 "name": "structured_api",1792 "args": {"arg1": 1, "arg2": True, "arg3": {"img": "base64string..."}},1793 "id": "123",1794 "type": "tool_call",1795 }1796 expected = ToolMessage(1797 "1 True", artifact=tool_call["args"], tool_call_id="123", name="structured_api"1798 )1799 actual = tool.invoke(tool_call)1800 assert actual == expected18011802 tool_call.pop("type")1803 with pytest.raises(ValidationError):1804 tool.invoke(tool_call)18051806 actual_content = tool.invoke(tool_call["args"])1807 assert actual_content == expected.content180818091810def test_convert_from_runnable_dict() -> None:1811 # Test with typed dict input1812 class Args(TypedDict):1813 a: int1814 b: list[int]18151816 def f(x: Args) -> str:1817 return str(x["a"] * max(x["b"]))18181819 runnable = RunnableLambda(f)1820 as_tool = runnable.as_tool()1821 args_schema = as_tool.args_schema1822 assert args_schema is not None1823 assert _schema(args_schema) == {1824 "title": "f",1825 "type": "object",1826 "properties": {1827 "a": {"title": "A", "type": "integer"},1828 "b": {"title": "B", "type": "array", "items": {"type": "integer"}},1829 },1830 "required": ["a", "b"],1831 }1832 assert as_tool.description1833 result = as_tool.invoke({"a": 3, "b": [1, 2]})1834 assert result == "6"18351836 as_tool = runnable.as_tool(name="my tool", description="test description")1837 assert as_tool.name == "my tool"1838 assert as_tool.description == "test description"18391840 # Dict without typed input-- must supply schema1841 def g(x: dict[str, Any]) -> str:1842 return str(x["a"] * max(x["b"]))18431844 # Specify via args_schema:1845 class GSchema(BaseModel):1846 """Apply a function to an integer and list of integers."""18471848 a: int = Field(..., description="Integer")1849 b: list[int] = Field(..., description="List of ints")18501851 runnable2 = RunnableLambda(g)1852 as_tool2 = runnable2.as_tool(GSchema)1853 as_tool2.invoke({"a": 3, "b": [1, 2]})18541855 # Specify via arg_types:1856 runnable3 = RunnableLambda(g)1857 as_tool3 = runnable3.as_tool(arg_types={"a": int, "b": list[int]})1858 result = as_tool3.invoke({"a": 3, "b": [1, 2]})1859 assert result == "6"18601861 # Test with config1862 def h(x: dict[str, Any]) -> str:1863 config = ensure_config()1864 assert config["configurable"]["foo"] == "not-bar"1865 return str(x["a"] * max(x["b"]))18661867 runnable4 = RunnableLambda(h)1868 as_tool4 = runnable4.as_tool(arg_types={"a": int, "b": list[int]})1869 result = as_tool4.invoke(1870 {"a": 3, "b": [1, 2]}, config={"configurable": {"foo": "not-bar"}}1871 )1872 assert result == "6"187318741875def test_convert_from_runnable_root_model_input_schema() -> None:1876 """`as_tool` should not advertise a `TypedDict` input nested under `root`.18771878 Some `Runnable`s (e.g. a compiled `langgraph` `StateGraph`) expose a1879 `pydantic.RootModel` as `input_schema` even though `get_input_jsonschema`1880 reports a flat object schema. See:1881 """18821883 class Args(TypedDict):1884 foo: str1885 bar: str18861887 class _RootModelInputRunnable(RunnableLambda[Args, str]):1888 @override1889 def get_input_schema(1890 self, config: RunnableConfig | None = None1891 ) -> TypeBaseModel:1892 return RootModel[Args]18931894 @override1895 def get_input_jsonschema(1896 self, config: RunnableConfig | None = None1897 ) -> dict[str, Any]:1898 return {1899 "type": "object",1900 "properties": {1901 "foo": {"type": "string"},1902 "bar": {"type": "string"},1903 },1904 "required": ["foo", "bar"],1905 }19061907 def f(x: Args) -> str:1908 return f"{x['foo']} {x['bar']}"19091910 runnable = _RootModelInputRunnable(f)1911 as_tool = runnable.as_tool(name="my_tool", description="Example tool.")19121913 assert as_tool.args_schema is not None1914 assert isinstance(as_tool.args_schema, type)1915 assert not issubclass(as_tool.args_schema, RootModel)19161917 oai_schema = convert_to_openai_tool(as_tool)1918 parameters = oai_schema["function"]["parameters"]1919 assert parameters["properties"].keys() == {"foo", "bar"}1920 assert "root" not in parameters["properties"]19211922 result = as_tool.invoke({"foo": "hello", "bar": "world"})1923 assert result == "hello world"192419251926def test_convert_from_runnable_other() -> None:1927 # String input1928 def f(x: str) -> str:1929 return x + "a"19301931 def g(x: str) -> str:1932 return x + "z"19331934 runnable = RunnableLambda(f) | g1935 as_tool = runnable.as_tool()1936 args_schema = as_tool.args_schema1937 assert args_schema is None1938 assert as_tool.description19391940 result = as_tool.invoke("b")1941 assert result == "baz"19421943 # Test with config1944 def h(x: str) -> str:1945 config = ensure_config()1946 assert config["configurable"]["foo"] == "not-bar"1947 return x + "a"19481949 runnable2 = RunnableLambda(h)1950 as_tool2 = runnable2.as_tool()1951 result2 = as_tool2.invoke("b", config={"configurable": {"foo": "not-bar"}})1952 assert result2 == "ba"195319541955@tool("foo", parse_docstring=True)1956def injected_tool(x: int, y: Annotated[str, InjectedToolArg]) -> str:1957 """Foo.19581959 Args:1960 x: abc1961 y: 1231962 """1963 return y196419651966class InjectedTool(BaseTool):1967 name: str = "foo"1968 description: str = "foo."19691970 @override1971 def _run(self, x: int, y: Annotated[str, InjectedToolArg]) -> Any:1972 """Foo.19731974 Args:1975 x: abc1976 y: 1231977 """1978 return y197919801981class fooSchema(BaseModel): # noqa: N8011982 """foo."""19831984 x: int = Field(..., description="abc")1985 y: Annotated[str, "foobar comment", InjectedToolArg()] = Field(1986 ..., description="123"1987 )198819891990class InjectedToolWithSchema(BaseTool):1991 name: str = "foo"1992 description: str = "foo."1993 args_schema: type[BaseModel] = fooSchema19941995 @override1996 def _run(self, x: int, y: str) -> Any:1997 return y199819992000@tool("foo", args_schema=fooSchema)
Findings
✓ No findings reported for this file.