tool#

langchain_core.tools.convert.tool(
*,
description: str | None = None,
return_direct: bool = False,
args_schema: type[BaseModel] | dict[str, Any] | None = None,
infer_schema: bool = True,
response_format: Literal['content', 'content_and_artifact'] = 'content',
parse_docstring: bool = False,
error_on_invalid_docstring: bool = True,
) → Callable[[Callable | Runnable], BaseTool][source]#
langchain_core.tools.convert.tool(
name_or_callable: str,
runnable: Runnable,
*,
description: str | None = None,
return_direct: bool = False,
args_schema: type[BaseModel] | dict[str, Any] | None = None,
infer_schema: bool = True,
response_format: Literal['content', 'content_and_artifact'] = 'content',
parse_docstring: bool = False,
error_on_invalid_docstring: bool = True,
) → BaseTool
langchain_core.tools.convert.tool(
name_or_callable: Callable,
*,
description: str | None = None,
return_direct: bool = False,
args_schema: type[BaseModel] | dict[str, Any] | None = None,
infer_schema: bool = True,
response_format: Literal['content', 'content_and_artifact'] = 'content',
parse_docstring: bool = False,
error_on_invalid_docstring: bool = True,
) → BaseTool
langchain_core.tools.convert.tool(
name_or_callable: str,
*,
description: str | None = None,
return_direct: bool = False,
args_schema: type[BaseModel] | dict[str, Any] | None = None,
infer_schema: bool = True,
response_format: Literal['content', 'content_and_artifact'] = 'content',
parse_docstring: bool = False,
error_on_invalid_docstring: bool = True,
) → Callable[[Callable | Runnable], BaseTool]

Make tools out of functions, can be used with or without arguments.

Parameters:

  • name_or_callable – Optional name of the tool or the callable to be converted to a tool. Must be provided as a positional argument.

  • runnable – Optional runnable to convert to a tool. Must be provided as a positional argument.

  • description –

    Optional description for the tool. Precedence for the tool description value is as follows:

    • description argument

      (used even if docstring and/or args_schema are provided)

    • tool function docstring

      (used even if args_schema is provided)

    • args_schema description

      (used only if description / docstring are not provided)

  • *args – Extra positional arguments. Must be empty.

  • return_direct – Whether to return directly from the tool rather than continuing the agent loop. Defaults to False.

  • args_schema – optional argument schema for user to specify. Defaults to None.

  • infer_schema – Whether to infer the schema of the arguments from the function’s signature. This also makes the resultant tool accept a dictionary input to its run() function. Defaults to True.

  • response_format – The tool response format. If “content” then the output of the tool is interpreted as the contents of a ToolMessage. If “content_and_artifact” then the output is expected to be a two-tuple corresponding to the (content, artifact) of a ToolMessage. Defaults to “content”.

  • parse_docstring – if infer_schema and parse_docstring, will attempt to parse parameter descriptions from Google Style function docstrings. Defaults to False.

  • error_on_invalid_docstring – if parse_docstring is provided, configure whether to raise ValueError on invalid Google Style docstrings. Defaults to True.

Raises:

  • ValueError – If too many positional arguments are provided.

  • ValueError – If a runnable is provided without a string name.

  • ValueError – If the first argument is not a string or callable with a __name__ attribute.

  • ValueError – If the function does not have a docstring and description is not provided and infer_schema is False.

  • ValueError – If parse_docstring is True and the function has an invalid Google-style docstring and error_on_invalid_docstring is True.

  • ValueError – If a Runnable is provided that does not have an object schema.

Returns:

The tool.

Requires:

  • Function must be of type (str) -> str

  • Function must have a docstring

Examples

@tool
def search_api(query: str) -> str:
    # Searches the API for the query.
    return


@tool("search", return_direct=True)
def search_api(query: str) -> str:
    # Searches the API for the query.
    return


@tool(response_format="content_and_artifact")
def search_api(query: str) -> tuple[str, dict]:
    return "partial json of results", {"full": "object of results"}

Added in version 0.2.14: Parse Google-style docstrings:

@tool(parse_docstring=True)
def foo(bar: str, baz: int) -> str:
    """The foo.

    Args:
        bar: The bar.
        baz: The baz.
    """
    return bar

foo.args_schema.model_json_schema()

{
    "title": "foo",
    "description": "The foo.",
    "type": "object",
    "properties": {
        "bar": {
            "title": "Bar",
            "description": "The bar.",
            "type": "string",
        },
        "baz": {
            "title": "Baz",
            "description": "The baz.",
            "type": "integer",
        },
    },
    "required": ["bar", "baz"],
}

Note that parsing by default will raise ValueError if the docstring is considered invalid. A docstring is considered invalid if it contains arguments not in the function signature, or is unable to be parsed into a summary and “Args:” blocks. Examples below:

# No args section
def invalid_docstring_1(bar: str, baz: int) -> str:
    """The foo."""
    return bar

# Improper whitespace between summary and args section
def invalid_docstring_2(bar: str, baz: int) -> str:
    """The foo.
    Args:
        bar: The bar.
        baz: The baz.
    """
    return bar

# Documented args absent from function signature
def invalid_docstring_3(bar: str, baz: int) -> str:
    """The foo.

    Args:
        banana: The bar.
        monkey: The baz.
    """
    return bar

Examples using tool

On this page