Source code for langchain_core.tools
""" **工具** 是Agent用来与世界互动的类。
每个工具都有一个 **描述** 。Agent使用描述来选择合适的工具来完成工作。
**类层次结构:**
.. code-block::
RunnableSerializable --> BaseTool --> <name>Tool # 例如: AIPluginTool, BaseGraphQLTool
<name> # 例如: BraveSearch, HumanInputRun
**主要辅助工具:**
.. code-block::
CallbackManagerForToolRun, AsyncCallbackManagerForToolRun
""" # noqa: E501
from __future__ import annotations
import asyncio
import inspect
import textwrap
import uuid
import warnings
from abc import ABC, abstractmethod
from contextvars import copy_context
from functools import partial
from inspect import signature
from typing import Any, Awaitable, Callable, Dict, List, Optional, Tuple, Type, Union
from langchain_core._api import deprecated
from langchain_core.callbacks import (
AsyncCallbackManager,
AsyncCallbackManagerForToolRun,
BaseCallbackManager,
CallbackManager,
CallbackManagerForToolRun,
)
from langchain_core.callbacks.manager import (
Callbacks,
)
from langchain_core.load.serializable import Serializable
from langchain_core.prompts import (
BasePromptTemplate,
PromptTemplate,
aformat_document,
format_document,
)
from langchain_core.pydantic_v1 import (
BaseModel,
Extra,
Field,
ValidationError,
create_model,
root_validator,
validate_arguments,
)
from langchain_core.retrievers import BaseRetriever
from langchain_core.runnables import (
Runnable,
RunnableConfig,
RunnableSerializable,
ensure_config,
)
from langchain_core.runnables.config import (
patch_config,
run_in_executor,
var_child_runnable_config,
)
from langchain_core.runnables.utils import accepts_context
def _create_subset_model(
name: str, model: Type[BaseModel], field_names: list
) -> Type[BaseModel]:
"""创建一个仅包含模型字段子集的pydantic模型。"""
fields = {}
for field_name in field_names:
field = model.__fields__[field_name]
t = (
# this isn't perfect but should work for most functions
field.outer_type_
if field.required and not field.allow_none
else Optional[field.outer_type_]
)
fields[field_name] = (t, field.field_info)
rtn = create_model(name, **fields) # type: ignore
return rtn
def _get_filtered_args(
inferred_model: Type[BaseModel],
func: Callable,
) -> dict:
"""从函数的签名中获取参数。"""
schema = inferred_model.schema()["properties"]
valid_keys = signature(func).parameters
return {k: schema[k] for k in valid_keys if k not in ("run_manager", "callbacks")}
class _SchemaConfig:
"""用于pydantic模型的配置。"""
extra: Any = Extra.forbid
arbitrary_types_allowed: bool = True
[docs]def create_schema_from_function(
model_name: str,
func: Callable,
) -> Type[BaseModel]:
"""从函数的签名创建一个pydantic模式。
参数：
model_name：分配给生成的pydandic模式的名称
func：要从中生成模式的函数
返回：
一个具有与函数相同参数的pydantic模型
"""
# https://docs.pydantic.dev/latest/usage/validation_decorator/
validated = validate_arguments(func, config=_SchemaConfig) # type: ignore
inferred_model = validated.model # type: ignore
if "run_manager" in inferred_model.__fields__:
del inferred_model.__fields__["run_manager"]
if "callbacks" in inferred_model.__fields__:
del inferred_model.__fields__["callbacks"]
# Pydantic adds placeholder virtual fields we need to strip
valid_properties = _get_filtered_args(inferred_model, func)
return _create_subset_model(
f"{model_name}Schema", inferred_model, list(valid_properties)
)
[docs]class ToolException(Exception):
"""当执行错误发生时工具抛出的可选异常。
当抛出此异常时，代理程序不会停止工作，而是根据工具的handle_tool_error变量处理异常，并将处理结果作为观察返回给代理程序，并在控制台上以红色打印。
"""
pass
[docs]class BaseTool(RunnableSerializable[Union[str, Dict], Any]):
"""LangChain工具必须实现的接口。"""
def __init_subclass__(cls, **kwargs: Any) -> None:
"""创建新工具类的定义。"""
super().__init_subclass__(**kwargs)
args_schema_type = cls.__annotations__.get("args_schema", None)
if args_schema_type is not None and args_schema_type == BaseModel:
# Throw errors for common mis-annotations.
# TODO: Use get_args / get_origin and fully
# specify valid annotations.
typehint_mandate = """
class ChildTool(BaseTool):
...
args_schema: Type[BaseModel] = SchemaClass
..."""
name = cls.__name__
raise SchemaAnnotationError(
f"Tool definition for {name} must include valid type annotations"
f" for argument 'args_schema' to behave as expected.\n"
f"Expected annotation of 'Type[BaseModel]'"
f" but got '{args_schema_type}'.\n"
f"Expected class looks like:\n"
f"{typehint_mandate}"
)
name: str
"""工具的唯一名称，清晰地传达其目的。"""
description: str
"""用于告诉模型如何/何时/为什么使用该工具。
您可以在描述中提供少量示例。"""
args_schema: Optional[Type[BaseModel]] = None
"""Pydantic模型类，用于验证和解析工具的输入参数。"""
return_direct: bool = False
"""是否直接返回工具的输出。将其设置为True意味着在调用工具后，AgentExecutor将停止循环。"""
verbose: bool = False
"""工具的进度是否记录。"""
callbacks: Callbacks = Field(default=None, exclude=True)
"""在工具执行期间要调用的回调函数。"""
callback_manager: Optional[BaseCallbackManager] = Field(default=None, exclude=True)
"""已弃用。请改用回调函数。"""
tags: Optional[List[str]] = None
"""可选的工具相关标签列表。默认为None
这些标签将与对该工具的每次调用相关联，并作为参数传递给`callbacks`中定义的处理程序。
您可以使用这些标签来识别工具的特定实例及其用例。"""
metadata: Optional[Dict[str, Any]] = None
"""与工具相关的可选元数据。默认为None
此元数据将与对该工具的每次调用相关联，并作为参数传递给在`callbacks`中定义的处理程序。您可以使用这些元数据来识别工具的特定实例及其用例。"""
handle_tool_error: Optional[
Union[bool, str, Callable[[ToolException], str]]
] = False
"""处理抛出的ToolException的内容。"""
handle_validation_error: Optional[
Union[bool, str, Callable[[ValidationError], str]]
] = False
"""处理抛出的ValidationError的内容。"""
class Config(Serializable.Config):
"""这个pydantic对象的配置。"""
arbitrary_types_allowed = True
@property
def is_single_input(self) -> bool:
"""工具是否只接受单个输入。"""
keys = {k for k in self.args if k != "kwargs"}
return len(keys) == 1
@property
def args(self) -> dict:
if self.args_schema is not None:
return self.args_schema.schema()["properties"]
else:
schema = create_schema_from_function(self.name, self._run)
return schema.schema()["properties"]
# --- Runnable ---
[docs] def get_input_schema(
self, config: Optional[RunnableConfig] = None
) -> Type[BaseModel]:
"""工具的输入模式。"""
if self.args_schema is not None:
return self.args_schema
else:
return create_schema_from_function(self.name, self._run)
[docs] def invoke(
self,
input: Union[str, Dict],
config: Optional[RunnableConfig] = None,
**kwargs: Any,
) -> Any:
config = ensure_config(config)
return self.run(
input,
callbacks=config.get("callbacks"),
tags=config.get("tags"),
metadata=config.get("metadata"),
run_name=config.get("run_name"),
run_id=config.pop("run_id", None),
config=config,
**kwargs,
)
[docs] async def ainvoke(
self,
input: Union[str, Dict],
config: Optional[RunnableConfig] = None,
**kwargs: Any,
) -> Any:
config = ensure_config(config)
return await self.arun(
input,
callbacks=config.get("callbacks"),
tags=config.get("tags"),
metadata=config.get("metadata"),
run_name=config.get("run_name"),
run_id=config.pop("run_id", None),
config=config,
**kwargs,
)
# --- Tool ---
def _parse_input(
self,
tool_input: Union[str, Dict],
) -> Union[str, Dict[str, Any]]:
"""将工具输入转换为pydantic模型。"""
input_args = self.args_schema
if isinstance(tool_input, str):
if input_args is not None:
key_ = next(iter(input_args.__fields__.keys()))
input_args.validate({key_: tool_input})
return tool_input
else:
if input_args is not None:
result = input_args.parse_obj(tool_input)
return {
k: getattr(result, k)
for k, v in result.dict().items()
if k in tool_input
}
return tool_input
@root_validator()
def raise_deprecation(cls, values: Dict) -> Dict:
"""如果使用callback_manager，则发出弃用警告。"""
if values.get("callback_manager") is not None:
warnings.warn(
"callback_manager is deprecated. Please use callbacks instead.",
DeprecationWarning,
)
values["callbacks"] = values.pop("callback_manager", None)
return values
@abstractmethod
def _run(
self,
*args: Any,
**kwargs: Any,
) -> Any:
"""使用该工具。
在子实现中添加 run_manager: Optional[CallbackManagerForToolRun] = None
以启用跟踪。
"""
async def _arun(
self,
*args: Any,
**kwargs: Any,
) -> Any:
"""使用工具进行异步操作。
在子实现中添加 run_manager: Optional[AsyncCallbackManagerForToolRun] = None
以启用跟踪功能。
"""
return await run_in_executor(None, self._run, *args, **kwargs)
def _to_args_and_kwargs(self, tool_input: Union[str, Dict]) -> Tuple[Tuple, Dict]:
# For backwards compatibility, if run_input is a string,
# pass as a positional argument.
if isinstance(tool_input, str):
return (tool_input,), {}
else:
return (), tool_input
[docs] def run(
self,
tool_input: Union[str, Dict[str, Any]],
verbose: Optional[bool] = None,
start_color: Optional[str] = "green",
color: Optional[str] = "green",
callbacks: Callbacks = None,
*,
tags: Optional[List[str]] = None,
metadata: Optional[Dict[str, Any]] = None,
run_name: Optional[str] = None,
run_id: Optional[uuid.UUID] = None,
config: Optional[RunnableConfig] = None,
**kwargs: Any,
) -> Any:
"""运行工具。"""
if not self.verbose and verbose is not None:
verbose_ = verbose
else:
verbose_ = self.verbose
callback_manager = CallbackManager.configure(
callbacks,
self.callbacks,
verbose_,
tags,
self.tags,
metadata,
self.metadata,
)
# TODO: maybe also pass through run_manager is _run supports kwargs
new_arg_supported = signature(self._run).parameters.get("run_manager")
run_manager = callback_manager.on_tool_start(
{"name": self.name, "description": self.description},
tool_input if isinstance(tool_input, str) else str(tool_input),
color=start_color,
name=run_name,
run_id=run_id,
# Inputs by definition should always be dicts.
# For now, it's unclear whether this assumption is ever violated,
# but if it is we will send a `None` value to the callback instead
# And will need to address issue via a patch.
inputs=None if isinstance(tool_input, str) else tool_input,
**kwargs,
)
try:
child_config = patch_config(
config,
callbacks=run_manager.get_child(),
)
context = copy_context()
context.run(var_child_runnable_config.set, child_config)
parsed_input = self._parse_input(tool_input)
tool_args, tool_kwargs = self._to_args_and_kwargs(parsed_input)
observation = (
context.run(
self._run, *tool_args, run_manager=run_manager, **tool_kwargs
)
if new_arg_supported
else context.run(self._run, *tool_args, **tool_kwargs)
)
except ValidationError as e:
if not self.handle_validation_error:
raise e
elif isinstance(self.handle_validation_error, bool):
observation = "Tool input validation error"
elif isinstance(self.handle_validation_error, str):
observation = self.handle_validation_error
elif callable(self.handle_validation_error):
observation = self.handle_validation_error(e)
else:
raise ValueError(
f"Got unexpected type of `handle_validation_error`. Expected bool, "
f"str or callable. Received: {self.handle_validation_error}"
)
return observation
except ToolException as e:
if not self.handle_tool_error:
run_manager.on_tool_error(e)
raise e
elif isinstance(self.handle_tool_error, bool):
if e.args:
observation = e.args[0]
else:
observation = "Tool execution error"
elif isinstance(self.handle_tool_error, str):
observation = self.handle_tool_error
elif callable(self.handle_tool_error):
observation = self.handle_tool_error(e)
else:
raise ValueError(
f"Got unexpected type of `handle_tool_error`. Expected bool, str "
f"or callable. Received: {self.handle_tool_error}"
)
run_manager.on_tool_end(observation, color="red", name=self.name, **kwargs)
return observation
except (Exception, KeyboardInterrupt) as e:
run_manager.on_tool_error(e)
raise e
else:
run_manager.on_tool_end(observation, color=color, name=self.name, **kwargs)
return observation
[docs] async def arun(
self,
tool_input: Union[str, Dict],
verbose: Optional[bool] = None,
start_color: Optional[str] = "green",
color: Optional[str] = "green",
callbacks: Callbacks = None,
*,
tags: Optional[List[str]] = None,
metadata: Optional[Dict[str, Any]] = None,
run_name: Optional[str] = None,
run_id: Optional[uuid.UUID] = None,
config: Optional[RunnableConfig] = None,
**kwargs: Any,
) -> Any:
"""以异步方式运行工具。"""
if not self.verbose and verbose is not None:
verbose_ = verbose
else:
verbose_ = self.verbose
callback_manager = AsyncCallbackManager.configure(
callbacks,
self.callbacks,
verbose_,
tags,
self.tags,
metadata,
self.metadata,
)
new_arg_supported = signature(self._arun).parameters.get("run_manager")
run_manager = await callback_manager.on_tool_start(
{"name": self.name, "description": self.description},
tool_input if isinstance(tool_input, str) else str(tool_input),
color=start_color,
name=run_name,
inputs=tool_input,
run_id=run_id,
**kwargs,
)
try:
parsed_input = self._parse_input(tool_input)
# We then call the tool on the tool input to get an observation
tool_args, tool_kwargs = self._to_args_and_kwargs(parsed_input)
child_config = patch_config(
config,
callbacks=run_manager.get_child(),
)
context = copy_context()
context.run(var_child_runnable_config.set, child_config)
coro = (
context.run(
self._arun, *tool_args, run_manager=run_manager, **tool_kwargs
)
if new_arg_supported
else context.run(self._arun, *tool_args, **tool_kwargs)
)
if accepts_context(asyncio.create_task):
observation = await asyncio.create_task(coro, context=context) # type: ignore
else:
observation = await coro
except ValidationError as e:
if not self.handle_validation_error:
raise e
elif isinstance(self.handle_validation_error, bool):
observation = "Tool input validation error"
elif isinstance(self.handle_validation_error, str):
observation = self.handle_validation_error
elif callable(self.handle_validation_error):
observation = self.handle_validation_error(e)
else:
raise ValueError(
f"Got unexpected type of `handle_validation_error`. Expected bool, "
f"str or callable. Received: {self.handle_validation_error}"
)
return observation
except ToolException as e:
if not self.handle_tool_error:
await run_manager.on_tool_error(e)
raise e
elif isinstance(self.handle_tool_error, bool):
if e.args:
observation = e.args[0]
else:
observation = "Tool execution error"
elif isinstance(self.handle_tool_error, str):
observation = self.handle_tool_error
elif callable(self.handle_tool_error):
observation = self.handle_tool_error(e)
else:
raise ValueError(
f"Got unexpected type of `handle_tool_error`. Expected bool, str "
f"or callable. Received: {self.handle_tool_error}"
)
await run_manager.on_tool_end(
observation, color="red", name=self.name, **kwargs
)
return observation
except (Exception, KeyboardInterrupt) as e:
await run_manager.on_tool_error(e)
raise e
else:
await run_manager.on_tool_end(
observation, color=color, name=self.name, **kwargs
)
return observation
[docs] @deprecated("0.1.47", alternative="invoke", removal="0.3.0")
def __call__(self, tool_input: str, callbacks: Callbacks = None) -> str:
"""使工具可被调用。"""
return self.run(tool_input, callbacks=callbacks)
class Tool(BaseTool):
"""直接接收函数或协程的工具。"""
description: str = ""
func: Optional[Callable[..., str]]
"""当调用工具时要运行的函数。"""
coroutine: Optional[Callable[..., Awaitable[str]]] = None
"""函数的异步版本。"""
# --- Runnable ---
async def ainvoke(
self,
input: Union[str, Dict],
config: Optional[RunnableConfig] = None,
**kwargs: Any,
) -> Any:
if not self.coroutine:
# If the tool does not implement async, fall back to default implementation
return await run_in_executor(config, self.invoke, input, config, **kwargs)
return await super().ainvoke(input, config, **kwargs)
# --- Tool ---
@property
def args(self) -> dict:
"""工具的输入参数。"""
if self.args_schema is not None:
return self.args_schema.schema()["properties"]
# For backwards compatibility, if the function signature is ambiguous,
# assume it takes a single string input.
return {"tool_input": {"type": "string"}}
def _to_args_and_kwargs(self, tool_input: Union[str, Dict]) -> Tuple[Tuple, Dict]:
"""将工具输入转换为pydantic模型。"""
args, kwargs = super()._to_args_and_kwargs(tool_input)
# For backwards compatibility. The tool must be run with a single input
all_args = list(args) + list(kwargs.values())
if len(all_args) != 1:
raise ToolException(
f"""Too many arguments to single-input tool {self.name}.
Consider using StructuredTool instead."""
f" Args: {all_args}"
)
return tuple(all_args), {}
def _run(
self,
*args: Any,
run_manager: Optional[CallbackManagerForToolRun] = None,
**kwargs: Any,
) -> Any:
"""使用这个工具。"""
if self.func:
new_argument_supported = signature(self.func).parameters.get("callbacks")
return (
self.func(
*args,
callbacks=run_manager.get_child() if run_manager else None,
**kwargs,
)
if new_argument_supported
else self.func(*args, **kwargs)
)
raise NotImplementedError("Tool does not support sync")
async def _arun(
self,
*args: Any,
run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
**kwargs: Any,
) -> Any:
"""使用异步工具。"""
if self.coroutine:
new_argument_supported = signature(self.coroutine).parameters.get(
"callbacks"
)
return (
await self.coroutine(
*args,
callbacks=run_manager.get_child() if run_manager else None,
**kwargs,
)
if new_argument_supported
else await self.coroutine(*args, **kwargs)
)
else:
return await run_in_executor(
None,
self._run,
run_manager=run_manager.get_sync() if run_manager else None,
*args,
**kwargs,
)
# TODO: this is for backwards compatibility, remove in future
def __init__(
self, name: str, func: Optional[Callable], description: str, **kwargs: Any
) -> None:
"""初始化工具。"""
super(Tool, self).__init__( # type: ignore[call-arg]
name=name, func=func, description=description, **kwargs
)
@classmethod
def from_function(
cls,
func: Optional[Callable],
name: str, # We keep these required to support backwards compatibility
description: str,
return_direct: bool = False,
args_schema: Optional[Type[BaseModel]] = None,
coroutine: Optional[
Callable[..., Awaitable[Any]]
] = None, # This is last for compatibility, but should be after func
**kwargs: Any,
) -> Tool:
"""从一个函数初始化工具。"""
if func is None and coroutine is None:
raise ValueError("Function and/or coroutine must be provided")
return cls(
name=name,
func=func,
coroutine=coroutine,
description=description,
return_direct=return_direct,
args_schema=args_schema,
**kwargs,
)
[docs]class StructuredTool(BaseTool):
"""可以操作任意数量输入的工具。"""
description: str = ""
args_schema: Type[BaseModel] = Field(..., description="The tool schema.")
"""输入参数的模式。"""
func: Optional[Callable[..., Any]]
"""当调用工具时要运行的函数。"""
coroutine: Optional[Callable[..., Awaitable[Any]]] = None
"""函数的异步版本。"""
# --- Runnable ---
[docs] async def ainvoke(
self,
input: Union[str, Dict],
config: Optional[RunnableConfig] = None,
**kwargs: Any,
) -> Any:
if not self.coroutine:
# If the tool does not implement async, fall back to default implementation
return await run_in_executor(config, self.invoke, input, config, **kwargs)
return await super().ainvoke(input, config, **kwargs)
# --- Tool ---
@property
def args(self) -> dict:
"""工具的输入参数。"""
return self.args_schema.schema()["properties"]
def _run(
self,
*args: Any,
run_manager: Optional[CallbackManagerForToolRun] = None,
**kwargs: Any,
) -> Any:
"""使用这个工具。"""
if self.func:
new_argument_supported = signature(self.func).parameters.get("callbacks")
return (
self.func(
*args,
callbacks=run_manager.get_child() if run_manager else None,
**kwargs,
)
if new_argument_supported
else self.func(*args, **kwargs)
)
raise NotImplementedError("Tool does not support sync")
async def _arun(
self,
*args: Any,
run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
**kwargs: Any,
) -> str:
"""使用异步工具。"""
if self.coroutine:
new_argument_supported = signature(self.coroutine).parameters.get(
"callbacks"
)
return (
await self.coroutine(
*args,
callbacks=run_manager.get_child() if run_manager else None,
**kwargs,
)
if new_argument_supported
else await self.coroutine(*args, **kwargs)
)
return await run_in_executor(
None,
self._run,
run_manager=run_manager.get_sync() if run_manager else None,
*args,
**kwargs,
)
[docs] @classmethod
def from_function(
cls,
func: Optional[Callable] = None,
coroutine: Optional[Callable[..., Awaitable[Any]]] = None,
name: Optional[str] = None,
description: Optional[str] = None,
return_direct: bool = False,
args_schema: Optional[Type[BaseModel]] = None,
infer_schema: bool = True,
**kwargs: Any,
) -> StructuredTool:
"""从给定函数创建工具。
一个类方法，帮助从函数创建工具。
参数：
func：要创建工具的函数
coroutine：要创建工具的异步函数
name：工具的名称。默认为函数名称
description：工具的描述。默认为函数的文档字符串
return_direct：是否直接返回结果还是作为回调
args_schema：工具输入参数的模式
infer_schema：是否从函数的签名推断模式
**kwargs：传递给工具的其他参数
返回：
工具
示例：
.. code-block:: python
def add(a: int, b: int) -> int:
\"\"\"Add two numbers\"\"\"
return a + b
tool = StructuredTool.from_function(add)
tool.run(1, 2) # 3
"""
if func is not None:
source_function = func
elif coroutine is not None:
source_function = coroutine
else:
raise ValueError("Function and/or coroutine must be provided")
name = name or source_function.__name__
description_ = description or source_function.__doc__
if description_ is None:
raise ValueError(
"Function must have a docstring if description not provided."
)
if description is None:
# Only apply if using the function's docstring
description_ = textwrap.dedent(description_).strip()
# Description example:
# search_api(query: str) - Searches the API for the query.
description_ = f"{description_.strip()}"
_args_schema = args_schema
if _args_schema is None and infer_schema:
# schema name is appended within function
_args_schema = create_schema_from_function(name, source_function)
return cls(
name=name,
func=func,
coroutine=coroutine,
args_schema=_args_schema, # type: ignore[arg-type]
description=description_,
return_direct=return_direct,
**kwargs,
)
[docs]def tool(
*args: Union[str, Callable, Runnable],
return_direct: bool = False,
args_schema: Optional[Type[BaseModel]] = None,
infer_schema: bool = True,
) -> Callable:
"""将函数制作成工具，可以带参数或不带参数使用。
参数：
*args: 工具的参数。
return_direct: 是否直接从工具返回，而不是继续代理循环。
args_schema: 用户指定的可选参数模式。
infer_schema: 是否从函数的签名推断参数的模式。这还使得生成的工具接受一个字典输入到其`run()`函数。
要求：
- 函数必须是类型为 (str) -> str
- 函数必须有文档字符串
示例：
.. code-block:: python
@tool
def search_api(query: str) -> str:
# 搜索API以获取查询结果。
return
@tool("search", return_direct=True)
def search_api(query: str) -> str:
# 搜索API以获取查询结果。
return
"""
def _make_with_name(tool_name: str) -> Callable:
def _make_tool(dec_func: Union[Callable, Runnable]) -> BaseTool:
if isinstance(dec_func, Runnable):
runnable = dec_func
if runnable.input_schema.schema().get("type") != "object":
raise ValueError("Runnable must have an object schema.")
async def ainvoke_wrapper(
callbacks: Optional[Callbacks] = None, **kwargs: Any
) -> Any:
return await runnable.ainvoke(kwargs, {"callbacks": callbacks})
def invoke_wrapper(
callbacks: Optional[Callbacks] = None, **kwargs: Any
) -> Any:
return runnable.invoke(kwargs, {"callbacks": callbacks})
coroutine = ainvoke_wrapper
func = invoke_wrapper
schema: Optional[Type[BaseModel]] = runnable.input_schema
description = repr(runnable)
elif inspect.iscoroutinefunction(dec_func):
coroutine = dec_func
func = None
schema = args_schema
description = None
else:
coroutine = None
func = dec_func
schema = args_schema
description = None
if infer_schema or args_schema is not None:
return StructuredTool.from_function(
func,
coroutine,
name=tool_name,
description=description,
return_direct=return_direct,
args_schema=schema,
infer_schema=infer_schema,
)
# If someone doesn't want a schema applied, we must treat it as
# a simple string->string function
if func.__doc__ is None:
raise ValueError(
"Function must have a docstring if "
"description not provided and infer_schema is False."
)
return Tool(
name=tool_name,
func=func,
description=f"{tool_name} tool",
return_direct=return_direct,
coroutine=coroutine,
)
return _make_tool
if len(args) == 2 and isinstance(args[0], str) and isinstance(args[1], Runnable):
return _make_with_name(args[0])(args[1])
elif len(args) == 1 and isinstance(args[0], str):
# if the argument is a string, then we use the string as the tool name
# Example usage: @tool("search", return_direct=True)
return _make_with_name(args[0])
elif len(args) == 1 and callable(args[0]):
# if the argument is a function, then we use the function name as the tool name
# Example usage: @tool
return _make_with_name(args[0].__name__)(args[0])
elif len(args) == 0:
# if there are no arguments, then we use the function name as the tool name
# Example usage: @tool(return_direct=True)
def _partial(func: Callable[[str], str]) -> BaseTool:
return _make_with_name(func.__name__)(func)
return _partial
else:
raise ValueError("Too many arguments for tool decorator")
[docs]class RetrieverInput(BaseModel):
"""检索器的输入。"""
query: str = Field(description="query to look up in retriever")
def _get_relevant_documents(
query: str,
retriever: BaseRetriever,
document_prompt: BasePromptTemplate,
document_separator: str,
callbacks: Callbacks = None,
) -> str:
docs = retriever.invoke(query, config={"callbacks": callbacks})
return document_separator.join(
format_document(doc, document_prompt) for doc in docs
)
async def _aget_relevant_documents(
query: str,
retriever: BaseRetriever,
document_prompt: BasePromptTemplate,
document_separator: str,
callbacks: Callbacks = None,
) -> str:
docs = await retriever.ainvoke(query, config={"callbacks": callbacks})
return document_separator.join(
[await aformat_document(doc, document_prompt) for doc in docs]
)
[docs]def create_retriever_tool(
retriever: BaseRetriever,
name: str,
description: str,
*,
document_prompt: Optional[BasePromptTemplate] = None,
document_separator: str = "\n\n",
) -> Tool:
"""创建一个工具来检索文档。
参数：
retriever: 用于检索的检索器
name: 工具的名称。这将传递给语言模型，因此应该是唯一且有些描述性的。
description: 工具的描述。这将传递给语言模型，因此应该是描述性的。
返回：
传递给代理的工具类
"""
document_prompt = document_prompt or PromptTemplate.from_template("{page_content}")
func = partial(
_get_relevant_documents,
retriever=retriever,
document_prompt=document_prompt,
document_separator=document_separator,
)
afunc = partial(
_aget_relevant_documents,
retriever=retriever,
document_prompt=document_prompt,
document_separator=document_separator,
)
return Tool(
name=name,
description=description,
func=func,
coroutine=afunc,
args_schema=RetrieverInput,
)
ToolsRenderer = Callable[[List[BaseTool]], str]
[docs]def render_text_description(tools: List[BaseTool]) -> str:
"""以纯文本形式呈现工具名称和描述。
输出格式如下：
.. code-block:: markdown
search: This tool is used for search
calculator: This tool is used for math
"""
descriptions = []
for tool in tools:
if hasattr(tool, "func") and tool.func:
sig = signature(tool.func)
description = f"{tool.name}{sig} - {tool.description}"
else:
description = f"{tool.name} - {tool.description}"
descriptions.append(description)
return "\n".join(descriptions)
[docs]def render_text_description_and_args(tools: List[BaseTool]) -> str:
"""以纯文本形式呈现工具名称、描述和参数。
输出格式如下：
.. code-block:: markdown
search: This tool is used for search, args: {"query": {"type": "string"}}
calculator: This tool is used for math, args: {"expression": {"type": "string"}}
"""
tool_strings = []
for tool in tools:
args_schema = str(tool.args)
if hasattr(tool, "func") and tool.func:
sig = signature(tool.func)
description = f"{tool.name}{sig} - {tool.description}"
else:
description = f"{tool.name} - {tool.description}"
tool_strings.append(f"{description}, args: {args_schema}")
return "\n".join(tool_strings)