如何从工具返回工件
先决条件
本指南假设您熟悉以下概念
工具是可以被模型调用的实用程序,其输出旨在反馈给模型。然而,有时,我们希望工具执行的结果能够被链或代理中的下游组件访问,但不希望将其暴露给模型本身。例如,如果一个工具返回一个自定义对象、一个数据帧或一个图像,我们可能希望将一些关于此输出的元数据传递给模型,而不传递实际输出给模型。同时,我们可能希望在其他地方访问这个完整输出,例如在下游工具中。
Tool 和 ToolMessage 接口使得区分工具输出中哪些部分是用于模型的(这是 ToolMessage.content),哪些部分是用于模型外部的(ToolMessage.artifact)成为可能。
需要
langchain-core >= 0.2.19
此功能在 langchain-core == 0.2.19
中添加。请确保您的软件包是最新的。
定义工具
如果我们希望工具区分消息内容和其他工件,我们需要在定义工具时指定 response_format="content_and_artifact"
,并确保我们返回一个 (内容, 工件) 的元组
%pip install -qU "langchain-core>=0.2.19"
import random
from typing import List, Tuple
from langchain_core.tools import tool
@tool(response_format="content_and_artifact")
def generate_random_ints(min: int, max: int, size: int) -> Tuple[str, List[int]]:
"""Generate size random ints in the range [min, max]."""
array = [random.randint(min, max) for _ in range(size)]
content = f"Successfully generated array of {size} random ints in [{min}, {max}]."
return content, array
API 参考:tool
使用 ToolCall 调用工具
如果我们直接使用工具参数调用工具,你会注意到我们只会得到工具输出的内容部分
generate_random_ints.invoke({"min": 0, "max": 9, "size": 10})
'Successfully generated array of 10 random ints in [0, 9].'
Failed to batch ingest runs: LangSmithRateLimitError('Rate limit exceeded for https://api.smith.langchain.com/runs/batch. HTTPError(\'429 Client Error: Too Many Requests for url: https://api.smith.langchain.com/runs/batch\', \'{"detail":"Monthly unique traces usage limit exceeded"}\')')
为了同时获得内容和工件,我们需要使用 ToolCall(它只是一个带有 "name"、"args"、"id" 和 "type" 键的字典)调用我们的模型,它具有生成 ToolMessage 所需的额外信息,例如工具调用 ID
generate_random_ints.invoke(
{
"name": "generate_random_ints",
"args": {"min": 0, "max": 9, "size": 10},
"id": "123", # required
"type": "tool_call", # required
}
)
ToolMessage(content='Successfully generated array of 10 random ints in [0, 9].', name='generate_random_ints', tool_call_id='123', artifact=[2, 8, 0, 6, 0, 0, 1, 5, 0, 0])
与模型一起使用
使用支持工具调用的模型,我们可以轻松地使用模型来调用我们的工具并生成 ToolMessages
选择 聊天模型
pip install -qU langchain-openai
import getpass
import os
if not os.environ.get("OPENAI_API_KEY"):
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter API key for OpenAI: ")
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o-mini")
llm_with_tools = llm.bind_tools([generate_random_ints])
ai_msg = llm_with_tools.invoke("generate 6 positive ints less than 25")
ai_msg.tool_calls
[{'name': 'generate_random_ints',
'args': {'min': 1, 'max': 24, 'size': 6},
'id': 'toolu_01EtALY3Wz1DVYhv1TLvZGvE',
'type': 'tool_call'}]
generate_random_ints.invoke(ai_msg.tool_calls[0])
ToolMessage(content='Successfully generated array of 6 random ints in [1, 24].', name='generate_random_ints', tool_call_id='toolu_01EtALY3Wz1DVYhv1TLvZGvE', artifact=[2, 20, 23, 8, 1, 15])
如果我们只传入工具调用参数,我们将只得到内容
generate_random_ints.invoke(ai_msg.tool_calls[0]["args"])
'Successfully generated array of 6 random ints in [1, 24].'
如果我们想声明式地创建一个链,我们可以这样做
from operator import attrgetter
chain = llm_with_tools | attrgetter("tool_calls") | generate_random_ints.map()
chain.invoke("give me a random number between 1 and 5")
[ToolMessage(content='Successfully generated array of 1 random ints in [1, 5].', name='generate_random_ints', tool_call_id='toolu_01FwYhnkwDPJPbKdGq4ng6uD', artifact=[5])]
从 BaseTool 类创建
如果您想直接创建 BaseTool 对象,而不是使用 @tool
装饰器装饰函数,您可以这样做
from langchain_core.tools import BaseTool
class GenerateRandomFloats(BaseTool):
name: str = "generate_random_floats"
description: str = "Generate size random floats in the range [min, max]."
response_format: str = "content_and_artifact"
ndigits: int = 2
def _run(self, min: float, max: float, size: int) -> Tuple[str, List[float]]:
range_ = max - min
array = [
round(min + (range_ * random.random()), ndigits=self.ndigits)
for _ in range(size)
]
content = f"Generated {size} floats in [{min}, {max}], rounded to {self.ndigits} decimals."
return content, array
# Optionally define an equivalent async method
# async def _arun(self, min: float, max: float, size: int) -> Tuple[str, List[float]]:
# ...
API 参考:BaseTool
rand_gen = GenerateRandomFloats(ndigits=4)
rand_gen.invoke({"min": 0.1, "max": 3.3333, "size": 3})
'Generated 3 floats in [0.1, 3.3333], rounded to 4 decimals.'
rand_gen.invoke(
{
"name": "generate_random_floats",
"args": {"min": 0.1, "max": 3.3333, "size": 3},
"id": "123",
"type": "tool_call",
}
)
ToolMessage(content='Generated 3 floats in [0.1, 3.3333], rounded to 4 decimals.', name='generate_random_floats', tool_call_id='123', artifact=[1.5789, 2.464, 2.2719])