【LangChain】langchain_core.tools.render_text_description() 函数：将工具列表的名称和描述渲染为纯文本格式-CSDN博客

本文链接：https://blog.csdn.net/u013172930/article/details/148029023

`langchain_core.tools.render_text_description` 详解

langchain_core.tools.render_text_description 是 LangChain 框架中一个辅助函数，用于将工具列表的名称和描述渲染为纯文本格式，以便在提示模板中向语言模型提供工具信息。本文详细介绍其功能、参数、使用方法、实际应用及注意事项，确保内容条理清晰、易于理解。

1. 概述

1.1 什么是 `render_text_description`？

render_text_description 是 langchain_core.tools.render 模块中的函数，旨在从一组 BaseTool 对象的 name 和 description 属性生成纯文本字符串。输出的格式为每行一个工具，显示为“名称：描述”，例如：

search: This tool is used for search
calculator: This tool is used for math

该函数的主要用途是将工具信息以简洁的方式呈现，包含在语言模型的提示模板中，帮助模型理解可用工具及其功能。它在 langchain-core 0.2.14 版本中引入，广泛应用于代理系统和提示工程场景。

1.2 与其他组件的关系

与 BaseTool： BaseTool 是所有工具的基类，render_text_description 依赖其 name 和 description 属性。
与 StructuredTool：StructuredTool 是 BaseTool 的子类，其描述也可被渲染。
与 @tool 装饰器：@tool 装饰器创建的工具是 BaseTool 实例，描述可通过该函数渲染。
与 InjectedToolArg 和 InjectedToolCallId：这些注解用于工具参数，但不直接影响描述渲染。
与 chain 装饰器：结合 langchain_core.runnables.chain，可在工具调用链中动态生成提示，包含渲染的描述。

1.3 核心功能

工具描述渲染：从工具列表提取 name 和 description，生成纯文本。
标准格式输出：每行一个工具，格式为“名称：描述”，使用换行符分隔。
提示集成：输出字符串适合嵌入提示模板，指导模型选择工具。
简单高效：无需额外配置，直接处理 BaseTool 对象的属性。
版本要求：需 langchain-core>=0.2.14，具体功能可能依赖最新版本。

2. 定义与参数

2.1 函数签名

def render_text_description(tools: list[BaseTool]) -> str

2.2 参数详解

参数	类型	默认值	描述
`tools`	`list[BaseTool]`	无默认	工具列表，每个工具必须是 `BaseTool` 的实例，包含 `name` 和 `description` 属性。

2.3 返回值

类型：str
描述：渲染后的纯文本字符串，每行一个工具，格式为“名称：描述”，工具间以换行符分隔。若工具列表为空，返回空字符串。

3. 使用方法

使用 render_text_description 非常简单，只需提供包含 BaseTool 实例的列表。以下是具体使用方式：

3.1 基本用法

渲染简单工具列表的描述：

from langchain_core.tools import render_text_description, BaseTool

class SearchTool(BaseTool):
    name = "search"
    description = "This tool is used for search"

class CalculatorTool(BaseTool):
    name = "calculator"
    description = "This tool is used for math"

tools = [SearchTool(), CalculatorTool()]
description = render_text_description(tools)
print(description)

输出：

search: This tool is used for search
calculator: This tool is used for math

3.2 结合提示模板

将渲染的描述嵌入提示模板，用于代理系统：

from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_template(
    "可用工具:\n{tools_description}\n\n用户: {input}\n助手:"
)
tools_description = render_text_description(tools)
formatted_prompt = prompt.format(tools_description=tools_description, input="计算 2+2")
print(formatted_prompt)

输出：

可用工具:
search: This tool is used for search
calculator: This tool is used for math

用户: 计算 2+2
助手:

3.3 结合 `StructuredTool`

使用 StructuredTool 创建工具并渲染描述：

from langchain_core.tools import StructuredTool
from pydantic import BaseModel, Field

class AddInput(BaseModel):
    a: int = Field(description="第一个数字")
    b: int = Field(description="第二个数字")

tool = StructuredTool.from_function(
    func=lambda a, b: a + b,
    name="add",
    description="Add two numbers"
)
description = render_text_description([tool])
print(description)

输出：

add: Add two numbers

3.4 结合代理系统

在代理中动态生成工具描述：

from langchain.agents import AgentExecutor, create_structured_chat_agent
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

prompt = ChatPromptTemplate.from_template(
    "可用工具:\n{tools_description}\n\n用户: {input}\n助手:"
)
tools_description = render_text_description(tools)
agent = create_structured_chat_agent(
    llm=ChatOpenAI(),
    tools=tools,
    prompt=prompt.partial(tools_description=tools_description)
)
executor = AgentExecutor(agent=agent, tools=tools)
result = executor.invoke({"input": "计算 2+2"})

说明：代理根据提示中的工具描述选择 calculator 工具执行任务。

4. 实际应用

render_text_description 在以下场景中广泛使用：

代理系统：为代理提供工具描述，嵌入提示模板，帮助模型决定何时调用哪个工具。例如，在 ReAct 或 StructuredChat 代理中，模型根据描述输出行动。
提示工程：动态生成工具信息，增强模型的工具调用能力，特别是在临时（ad-hoc）工具调用场景中。
调试与日志：将工具描述渲染为文本，便于记录可用工具列表，辅助调试。
用户界面：在交互式应用中，将工具描述呈现给用户，说明可用功能。

5. 最佳实践

清晰描述：确保每个工具的 description 详细，包含少样本示例，增强模型理解。例如：
```
description = "Search for information. 示例：输入 'LangChain' 返回相关文档。"
```
完整工具列表：确保 tools 列表包含所有可用工具，避免遗漏。
描述格式：避免描述中包含换行或特殊字符，可能影响提示格式，必要时预处理描述。
版本检查：通过 pip install -qU langchain 确保安装 langchain-core>=0.2.14。
调试工具：使用 LangSmith 跟踪提示生成和工具调用，调试复杂代理或链。

6. 注意事项与限制

工具属性依赖：函数依赖工具的 name 和 description 属性，若缺失可能导致输出不完整或格式错误。
描述格式：描述中的换行符或特殊字符可能破坏输出格式，需确保描述为单行文本或进行预处理。
空列表处理：若 tools 列表为空，函数返回空字符串，需在提示模板中处理此情况。
模块路径：确保正确导入 langchain_core.tools.render_text_description。
版本依赖：功能可能受版本限制，需确保兼容最新版本。

7. 与相关函数的对比

与 render_text_description_and_args：render_text_description 仅渲染名称和描述，而 render_text_description_and_args 额外包含参数信息（如 args_schema），适合需要详细工具签名的场景。
与 create_schema_from_function：前文讨论的 create_schema_from_function 生成 Pydantic 模式，render_text_description 则专注于文本渲染，两者用途不同但可结合使用。

8. 结论

langchain_core.tools.render_text_description 是一个简单而高效的函数，通过将工具列表的名称和描述渲染为纯文本格式，支持代理系统和提示工程。其输出格式标准，易于嵌入提示模板，指导语言模型选择和调用工具。结合 BaseTool、StructuredTool 和代理框架，开发者可以构建强大的工具调用能力。遵循最佳实践并注意版本要求，将有助于充分发挥其功能。