Jean's Blog

一个专注软件测试开发技术的个人博客

0%

LangChain内置中间件案例

发表于 分类于
学习LangChain学习笔记第六讲

LangChain提供了一些内置的中间件提供使用，避免重复造轮子，主要介绍官方提供中间件的介绍与使用。提供的中间件以功能进行区分，有以下几类

官方地址：https://docs.langchain.com/oss/python/langchain/middleware/built-in

对话管理与优化

Summarization（对话总结）

当对话内容接近令牌（token）限制时，会自动对之前的对话历史进行总结，以便在有限的令牌范围内继续进行有效沟通。

功能

  • 自动总结对话历史：当对话接近令牌限制时，会自动对之前的对话内容进行总结。这里的“令牌限制”通常是指在某些语言模型中，输入和输出的文本长度是有限制的，以“令牌”（token）来衡量，当对话内容接近这个限制时，就需要对之前的对话进行压缩和总结，以便为后续的对话内容腾出空间。
  • 保留近期消息并压缩旧的上下文：在进行总结时，会优先保留最近的几条消息，因为这些消息通常包含了对话的最新进展和关键信息，而对较早的对话内容进行压缩，提取其中的核心要点，从而在不丢失重要信息的前提下，减少对话历史所占用的令牌数量。

用途

  • 长时间的对话：对于持续时间较长的对话，很容易就会超出语言模型的上下文窗口限制。通过自动总结功能，可以将之前的对话内容进行精简，使得对话能够继续进行，而不会因为超出上下文窗口而丢失之前的对话信息或者导致语言模型无法正常理解和生成后续的对话内容。
  • 多轮对话且历史记录丰富：在一些复杂的多轮对话场景中，对话双方可能会进行很多轮的交流，积累了大量的对话历史。这种情况下，自动总结功能可以帮助语言模型更好地管理和利用这些丰富的历史记录，避免因为历史记录过多而导致模型处理困难或者生成质量下降。
  • 需要完整保留对话上下文的应用：在某些应用场景中，对话的完整上下文是非常重要的，比如一些需要根据之前的对话内容来进行推理、决策或者生成连贯的长文本的任务。自动总结功能可以在不丢失关键信息的前提下，对对话历史进行优化处理，从而满足这些应用对完整对话上下文的需求。

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware


agent = create_agent(
    model=model,
    tools=[weather_tool, calculator_tool],
    middleware=[
        SummarizationMiddleware(
            model="gpt-4o-mini",
            max_tokens_before_summary=4000,  # Trigger summarization at 4000 tokens
            messages_to_keep=20,  # Keep last 20 messages after summary
            summary_prompt="Custom prompt for summarization...",  # Optional
        ),
    ],
)

参数说明

参数名 类型 默认值 是否必填 说明
model 字符串 无 必填 用于执行摘要的模型。通常选择比主模型更便宜的模型，如 gpt-4o-mini
max_tokens_before_summary 数字 无 可选 当累计上下文超过该令牌数时触发摘要
messages_to_keep 数字 "20" 可选 摘要后保留的最近消息数量
token_counter 函数 默认基于字符 可选 自定义令牌计数函数，用于替换系统默认的（简单字符长度统计）
summary_prompt 字符串 无 可选 自定义摘要提示词，不填则使用 LangChain 内置的摘要提示模板
summary_prefix 字符串 "## Previous conversation summary:" 可选 摘要消息放入历史前时的前缀内容

Context editing（上下文编辑）

通过修剪或清除工具的使用情况来管理对话上下文，确保对话的连贯性和有效性。

功能

  • 管理对话上下文：通过清除较旧的工具调用输出来管理对话上下文，同时保留最近的结果。
  • 触发条件：当达到令牌限制时，会触发上下文编辑操作。
  • 保持最新结果：在进行上下文编辑时，会保留最近的N个工具调用结果，确保这些最近的结果不会被清除。

用途

  • 长对话中的工具调用过多：在长对话中，如果进行了大量的工具调用，可能会导致上下文窗口超出令牌限制。上下文编辑可以帮助管理这种情况，避免上下文窗口过大。
  • 降低令牌成本：通过移除不再相关的较旧工具输出，可以减少令牌的使用量，从而降低成本。
  • 保持上下文中的最新工具结果：确保上下文中只保留最近的N个工具调用结果，这样可以保持上下文的简洁性和相关性，便于模型更好地理解和处理当前的对话内容。

总的来说，上下文编辑是一种用于优化对话上下文管理的机制，它通过在达到令牌限制时清除较旧的工具调用输出，同时保留最近的结果，从而帮助保持上下文窗口的可管理性，降低令牌成本，并确保上下文中的工具结果保持最新。

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from langchain.agents import create_agent
from langchain.agents.middleware import ContextEditingMiddleware, ClearToolUsesEdit

agent = create_agent(
    model="gpt-4o",
    tools=[...],
    middleware=[
        ContextEditingMiddleware(
            edits=[
                ClearToolUsesEdit(max_tokens=1000),  # Clear old tool uses
            ],
        ),
    ],
)

配置选项

ContextEditingMiddleware

参数名 类型 默认值 说明
edits list[ContextEdit] [ClearToolUsesEdit()] 上下文编辑策略列表
token_count_method string "approximate" approximate / model

ClearToolUsesEdit

参数名 类型 默认值 说明
trigger number 100000 触发上下文编辑的 token 数
clear_at_least number 0 至少要清除多少 token
keep number 3 保留最新的工具调用数量
clear_tool_inputs bool False 是否清除工具输入参数
exclude_tools list[string] () 排除不清除的工具
placeholder string “[cleared]” 清除内容替换文本

人工干预与控制

Human-in-the-loop（人工在环）

在工具调用执行过程中暂停，等待人工审批，确保工具调用的准确性和合规性。

该中间件的功能是在工具调用执行之前，暂停智能体（agent）的执行流程，以便让人类介入，对即将执行的工具调用进行审批、编辑或者拒绝。

适用场景

  • 高风险操作需要人工审批：对于一些高风险的操作，例如对数据库进行写入操作、进行金融交易等，这些操作可能会对系统或用户的资产等产生重大影响。在这种情况下，使用人机协作循环中间件可以让人类在工具调用执行之前进行审批，确保操作的准确性和安全性，避免因智能体的错误决策而导致不可挽回的后果。
  • 合规工作流程需要人工监督：在一些需要遵守特定法规或合规要求的工作流程中，法规可能明确规定必须有人类对某些操作或决策进行监督和审核。人机协作循环中间件能够满足这种需求，确保智能体的行为符合合规要求，让人类在关键环节进行把控，避免因智能体的自主行为而违反相关规定。
  • 长期对话中需要人工引导智能体：在一些持续时间较长的对话场景中，智能体可能需要根据人类的反馈来调整其行为和决策。通过人机协作循环中间件，人类可以在对话过程中随时对智能体即将执行的工具调用进行干预，提供指导和反馈，从而更好地引导智能体完成任务，使其能够更好地适应复杂多变的对话需求和用户的期望。

中间件定义了人类响应中断的三种内置方式

决策类型 描述 示例用例
✅ approve 操作按原样批准并执行，不进行任何更改。 按原样发送电子邮件草稿
✏️ edit 工具调用在修改后执行。 在发送电子邮件前更改收件人
❌ reject 工具调用被拒绝，并在对话中添加解释。 拒绝电子邮件草稿并解释如何重写

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="gpt-4o",
    tools=[read_email_tool, send_email_tool],
    checkpointer=InMemorySaver(),
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                # Require approval, editing, or rejection for sending emails
                "send_email_tool": {
                    "allowed_decisions": ["approve", "edit", "reject"],
                },
                # Auto-approve reading emails
                "read_email_tool": False,
            }
        ),
    ],
)

参数说明：

HumanInTheLoopMiddleware

参数名 类型 默认值 说明
interrupt_on dict 必填 工具名称 → 中断配置。 True=使用默认配置、False=跳过审批、dict=自定义 InterruptOnConfig

InterruptOnConfig

参数名 类型 默认值 说明
allowed_decisions list[str] 可选 可选：”approve”、”edit”、”reject”
description string 或 callable None 人类审批时显示的提示说明
description_prefix string "Tool execution requires approval" 前缀文字

成本与性能管理

Model call limit（模型调用限制）

限制模型调用的次数，以避免产生过高的成本。

用途

主要有以下三个方面：

  1. 防止失控的代理进行过多的API调用
    • 在一些情况下，代理（agent）可能会因为某些逻辑错误或其他问题而陷入无限循环，不断地调用模型接口。例如，代理可能在处理某些复杂任务时，错误地重复执行相同的操作，导致不断触发模型调用。通过设置模型调用限制，可以有效地避免这种情况，防止代理过度占用资源和产生不必要的费用。
  2. 在生产部署中强制执行成本控制
    • 在实际的生产环境中，使用模型调用通常会产生一定的成本，比如根据调用次数、数据量等因素计费。通过限制模型调用的次数，可以根据预算来控制成本，确保不会因为过多的调用而导致费用超出预期。这有助于更好地管理资源和预算，保证系统的经济性和可持续性。
  3. 在特定的调用预算内测试代理行为
    • 当开发和测试代理时，可能需要在一定的调用次数限制下观察代理的行为和性能。这样可以更好地了解代理在有限资源下的表现，评估其在实际应用场景中的可行性和效率。例如，在测试阶段，可以设置一个调用预算，模拟真实环境下的使用情况，以便对代理进行优化和调整，确保其在实际部署后能够稳定、高效地运行。

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from langchain.agents import create_agent
from langchain.agents.middleware import ModelCallLimitMiddleware


agent = create_agent(
    model="gpt-4o",
    tools=[...],
    middleware=[
        ModelCallLimitMiddleware(
            thread_limit=10,  # Max 10 calls per thread (across runs)
            run_limit=5,  # Max 5 calls per run (single invocation)
            exit_behavior="end",  # Or "error" to raise exception
        ),
    ],
)

参数说明

参数名 类型 默认值 说明
thread_limit number 无 单线程所有运行的模型调用上限
run_limit number 无 单次执行中的模型调用上限
exit_behavior "end" / "error" "end" 达到限制时的行为

Tool call limit（工具调用限制）

通过限制工具调用的次数来控制工具的执行，防止资源过度消耗。

“工具调用限制”中间件可以控制智能代理（agent）的行为，通过限制工具调用的次数来实现。这种限制可以是全局性的，即对所有工具都生效；也可以是针对特定工具的，即只对某些指定的工具进行限制。

功能

  • 防止过度调用昂贵的外部API：有些外部API的调用成本较高，如果智能代理频繁调用这些API，可能会导致成本急剧上升。通过设置工具调用限制，可以避免这种情况的发生，从而控制成本。
  • 限制网页搜索或数据库查询：在某些应用场景中，可能需要限制智能代理进行网页搜索或数据库查询的次数。例如，在一个需要保护数据隐私的系统中，可能希望限制对敏感数据库的查询次数，以防止数据泄露或滥用。
  • 强制执行特定工具的使用速率限制：某些工具可能有使用速率限制，即在一定时间内只能调用一定次数。通过工具调用限制中间件，可以确保智能代理遵守这些限制，避免因超出限制而导致的错误或异常。
  • 防止智能代理失控循环：在某些情况下，智能代理可能会陷入无限循环，不断地调用某个工具。这种失控的循环可能会导致系统资源耗尽或出现其他问题。工具调用限制中间件可以防止这种情况的发生，确保智能代理的行为在可控范围内。

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from langchain.agents import create_agent
from langchain.agents.middleware import ToolCallLimitMiddleware

# Limit all tool calls
global_limiter = ToolCallLimitMiddleware(thread_limit=20, run_limit=10)

# Limit specific tool
search_limiter = ToolCallLimitMiddleware(
    tool_name="search",
    thread_limit=5,
    run_limit=3,
)

agent = create_agent(
    model="gpt-4o",
    tools=[...],
    middleware=[global_limiter, search_limiter],
)

配置选项

参数名 类型 默认值 说明
tool_name string None 限制指定工具（None=全部工具）
thread_limit number 无 多次运行间的累计上限
run_limit number 无 单次执行的调用上限

可靠性与容错

Model fallback（模型回退）

当主模型失败时，自动切换到备用模型，确保服务的持续性。

当主模型（primary model）出现故障或无法正常工作时，会自动切换到其他备用模型（alternative models）。这种机制可以确保系统的稳定性和连续性，即使主模型出现问题，也不会导致整个系统瘫痪，而是通过备用模型继续提供服务。

功能

  • 构建具有弹性的代理（Building resilient agents）：通过模型回退功能，可以创建出能够应对模型故障的代理。当主模型由于各种原因（如网络问题、模型内部错误等）无法正常运行时，代理可以无缝切换到备用模型，从而保证服务的可用性，提高系统的整体可靠性。
  • 成本优化（Cost optimization）：在某些情况下，备用模型可能比主模型成本更低。当主模型出现故障时，切换到这些更经济的备用模型，可以在不影响服务质量的前提下，降低系统的运行成本。这有助于在保证系统稳定性的基础上，实现成本效益的最大化。
  • 供应商冗余（Provider redundancy）：在使用多个语言模型供应商（如OpenAI、Anthropic等）的情况下，模型回退功能可以实现供应商之间的冗余。如果主模型来自某个供应商并且出现问题，系统可以自动切换到其他供应商提供的备用模型。这样可以避免因单一供应商的服务中断而导致整个系统无法运行，提高系统的抗风险能力，确保服务的持续性。

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
from langchain.agents import create_agent
from langchain.agents.middleware import ModelFallbackMiddleware

agent = create_agent(
    model="gpt-4o",  # Primary model
    tools=[...],
    middleware=[
        ModelFallbackMiddleware(
            "gpt-4o-mini",  # Try first on error
            "claude-3-5-sonnet-20241022",  # Then this
        ),
    ],
)

配置选项

参数名 类型 默认值 说明
first_model string/BaseChatModel 必填 主模型失败时的第一回退
additional_models string/BaseChatModel 可选 额外回退模型

Tool retry（工具重试）

工具调用失败时，自动以指数退避的方式重试，提高工具调用的成功率。

功能

  • 自动重试失败的工具调用：当某个工具调用失败时，该中间件会自动进行重试，无需人工干预，从而提高工具调用的成功率。
  • 可配置的指数退避策略：重试的过程采用指数退避的方式，即每次重试的等待时间会根据一定的指数规律逐渐增加。这种策略可以有效避免因短时间内频繁重试而导致的网络拥堵或其他问题。同时，指数退避的相关参数（如初始延迟时间、退避因子等）是可以根据具体需求进行配置的，以适应不同的应用场景和网络环境。

用途

  • 处理外部API调用中的瞬态故障：在与外部API进行交互时，可能会因为网络波动、服务器短暂故障等原因导致调用失败。通过使用工具重试中间件，可以在遇到这类瞬态故障时自动进行重试，从而增加调用成功的可能性，减少因临时问题而导致的业务中断。
  • 提高依赖网络的工具的可靠性：对于那些依赖网络进行操作的工具，如数据查询工具、信息检索工具等，网络的不稳定可能会导致工具执行失败。利用工具重试中间件，可以增强这些工具在网络环境不佳时的可靠性，确保工具能够在合理的范围内成功完成任务。
  • 构建能够优雅处理临时错误的弹性代理：在复杂的系统中，各种临时错误是难以完全避免的。工具重试中间件可以帮助构建更加弹性的代理，使其在面对临时错误时能够自动进行重试，而不是直接失败或抛出异常。这样可以提高整个系统的稳定性和用户体验，减少因临时问题而导致的业务流程中断

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from langchain.agents import create_agent
from langchain.agents.middleware import ToolRetryMiddleware

agent = create_agent(
    model="gpt-4o",
    tools=[search_tool, database_tool],
    middleware=[
        ToolRetryMiddleware(
            max_retries=3,  # Retry up to 3 times
            backoff_factor=2.0,  # Exponential backoff multiplier
            initial_delay=1.0,  # Start with 1 second delay
            max_delay=60.0,  # Cap delays at 60 seconds
            jitter=True,  # Add random jitter to avoid thundering herd
        ),
    ],
)

配置选项

参数名 类型 默认值 说明
max_retries number 2 最大重试次数
tools list None 限定某些工具重试
retry_on tuple / callable (Exception,) 触发重试的异常
on_failure string/callable “return_message” 重试用尽时的行为
backoff_factor number 2.0 指数退避系数
initial_delay number 1.0 初始延迟
max_delay number 60 最大延迟
jitter bool true 是否添加抖动

Model retry（模型重试）

模型调用失败时，自动以指数退避的方式重试，增强模型调用的可靠性。

功能

  • 处理模型API调用中的瞬态故障。瞬态故障是指那些短暂出现且可能会自行恢复的错误，比如网络抖动、服务器短暂过载等情况导致的模型调用失败。通过模型重试机制，可以在这些瞬态故障发生后自动尝试重新调用模型，从而提高模型调用的成功率，避免因为短暂的故障而导致整个应用或任务的失败。
  • 提高依赖网络的模型请求的可靠性。许多模型调用是通过网络进行的，网络的不稳定因素可能会导致模型请求失败。模型重试机制可以在网络请求失败后自动进行重试，从而减少因网络问题导致的模型请求失败次数，增强整个系统的稳定性和可靠性，确保模型请求能够在网络条件允许的情况下成功完成。
  • 构建能够优雅地处理临时模型错误的弹性代理（或智能体）。在一些复杂的应用场景中，可能会涉及到多个模型调用或者连续的模型交互过程。模型重试机制可以帮助这些代理在遇到临时的模型错误时，不会直接崩溃或者停止工作，而是通过自动重试来尝试解决问题，从而使代理能够更加稳定、可靠地运行，提高系统的整体弹性和容错能力。

代码示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from langchain.agents import create_agent
from langchain.agents.middleware import ModelRetryMiddleware

agent = create_agent(
    model="gpt-4o",
    tools=[search_tool, database_tool],
    middleware=[
        ModelRetryMiddleware(
            max_retries=3,
            backoff_factor=2.0,
            initial_delay=1.0,
        ),
    ],
)

配置选项

参数名 类型 默认值 说明
max_retries number 2 最大重试次数
retry_on tuple / callable (Exception,) 触发重试的异常
on_failure string/callable “return_message” 重试用尽时的行为
backoff_factor number 2.0 指数退避系数
initial_delay number 1.0 初始延迟
max_delay number 60 最大延迟
jitter bool true 是否添加抖动

安全与隐私保护

PII detection（个人身份信息检测）

检测并处理个人身份信息（PII），保护用户的隐私和安全。

功能

  • 检测和处理PII：该中间件能够在对话中识别出个人身份信息（PII），并根据配置的策略对其进行处理。PII是指可以用于识别个人身份的信息，如姓名、身份证号、电话号码、电子邮件地址、信用卡号等。
  • 配置策略：用户可以根据自己的需求配置不同的处理策略，例如对PII进行脱敏处理（如部分隐藏、替换为特定标记等），或者直接阻止包含PII的信息被进一步处理。

用途

  • 合规要求的医疗和金融应用：在医疗和金融领域，很多应用都受到严格的合规要求，需要确保用户数据的隐私和安全。例如，医疗应用可能涉及患者的个人信息和健康数据，金融应用可能涉及客户的财务信息和交易记录。使用PII检测中间件可以帮助这些应用在处理对话时自动识别和保护PII，避免违反相关法规。
  • 需要清理日志的客服代理：客服代理在与客户交流过程中会生成大量的对话日志，其中可能包含客户的敏感信息。为了保护客户隐私，同时满足数据管理和审计的要求，客服系统需要对这些日志进行清理和脱敏处理。PII检测中间件可以自动检测日志中的PII，并按照预设的策略进行处理，确保日志中不包含敏感信息。
  • 处理敏感用户数据的任何应用：除了医疗和金融领域，许多其他类型的应用也会处理用户的敏感信息。例如，社交媒体应用可能涉及用户的个人资料和社交关系，电商应用可能涉及用户的购物习惯和支付信息等。这些应用都可以利用PII检测中间件来增强数据隐私保护，防止用户信息泄露。

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware

agent = create_agent(
    model="gpt-4o",
    tools=[...],
    middleware=[
        # Redact emails in user input
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        # Mask credit cards (show last 4 digits)
        PIIMiddleware("credit_card", strategy="mask", apply_to_input=True),
        # Custom PII type with regex
        PIIMiddleware(
            "api_key",
            detector=r"sk-[a-zA-Z0-9]{32}",
            strategy="block",  # Raise error if detected
        ),
    ],
)

配置选项

参数名 类型 默认值 说明
pii_type string 必填 email/credit_card/ip/mac/url 或自定义名称
strategy string "redact" block / redact / mask / hash block=严格最强、mask/redact=脱敏 hash 是进行哈希处理
detector regex / callable None 自定义检测器
apply_to_input bool True 检查用户输入
apply_to_output bool False 检查模型输出
apply_to_tool_results bool False 检查工具输出

还可以自定义PII类型，具体可想看官方文档：https://docs.langchain.com/oss/python/langchain/middleware/built-in#pii-detection

任务与工具管理

To-do list（待办事项列表）

为代理提供任务规划和跟踪的能力，帮助更好地管理和执行任务。

功能

“待办事项列表”中间件为智能代理（agents）配备了任务规划和跟踪能力，使其能够处理复杂的多步骤任务。具体来说，它为代理提供了以下能力：

  • 任务规划：代理可以将复杂的任务分解为多个子任务，并制定相应的执行计划。例如，一个需要先查询信息、再进行数据分析、最后生成报告的多步骤任务，代理可以将其规划为三个子任务，并确定每个子任务的执行顺序。
  • 任务跟踪：代理可以实时跟踪任务的执行进度，了解哪些子任务已经完成、哪些正在进行、哪些尚未开始。这有助于代理及时调整任务计划，确保整个任务能够顺利推进。

适用场景

这种中间件在以下场景中特别有用：

  • 需要跨多个工具协调的复杂多步骤任务：当一个任务涉及多个不同的工具或系统时，例如在软件开发中，需要先使用代码编辑器编写代码，然后使用版本控制系统提交代码，接着使用测试工具进行测试，最后使用部署工具将代码部署到服务器。这种情况下，待办事项列表可以帮助代理协调各个工具的使用，确保任务的每个步骤都能按照预定计划顺利进行。
  • 长时间运行且需要可见进度的操作：对于一些耗时较长的任务，如大规模数据处理、复杂的机器学习模型训练等，用户需要能够随时了解任务的进展情况。待办事项列表可以为用户提供清晰的任务进度视图，让用户知道任务已经完成了多少、预计还需要多长时间完成，从而提高用户对任务执行过程的掌控感。

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
from langchain.agents import create_agent
from langchain.agents.middleware import TodoListMiddleware
from langchain.messages import HumanMessage

agent = create_agent(
    model="gpt-4o",
    tools=[...],
    middleware=[TodoListMiddleware()],
)

result = agent.invoke({"messages": [HumanMessage("Help me refactor my codebase")]})
print(result["todos"])  # Array of todo items with status tracking

配置选项

参数名 类型 默认值 说明
system_prompt string 内置 自定义规划指令
tool_description string 内置 修改 write_todos 描述

LLM tool selector（LLM工具选择器）

使用LLM来选择与主模型调用相关的工具，提高工具选择的准确性和效率。

功能

  • 使用一个LLM（大型语言模型）来智能地选择与当前查询最相关的工具，然后再调用主模型。也就是说，在正式使用主模型进行任务处理之前，先通过一个LLM来筛选出适合的工具，从而为后续的处理提供更精准的工具支持。

用途

  • 多工具场景：当一个代理（agent）拥有10个以上的工具，而每次查询时大多数工具都不相关时，LLM工具选择器就显得非常有用。它能够从众多工具中筛选出与当前查询最相关的工具，避免了对大量不相关工具的无效调用。
  • 减少token使用：通过过滤掉不相关的工具，可以有效减少token的使用量。因为每次调用工具都需要消耗一定的token，如果调用了大量无关的工具，就会浪费很多token，而LLM工具选择器能够避免这种情况，从而降低token的使用成本。
  • 提高模型专注度和准确性：当工具选择更加精准时，主模型在处理任务时能够更加专注于与当前查询相关的工具和信息，从而提高模型的处理准确性和效率。它可以帮助模型更好地理解任务需求，避免被无关工具引入的噪声信息干扰，进而提升整体的性能表现。

代码示例

1
2
3
4
5
6
7
8
9
10
11
agent = create_agent(
    model="gpt-4o",
    tools=[tool1, tool2, tool3, tool4, tool5, ...],  # Many tools
    middleware=[
        LLMToolSelectorMiddleware(
            model="gpt-4o-mini",  # Use cheaper model for selection
            max_tools=3,  # Limit to 3 most relevant tools
            always_include=["search"],  # Always include certain tools
        ),
    ],
)

配置选项

参数名 类型 默认值 说明
model string/BaseModel 主模型 用于过滤工具的小模型
system_prompt string 内置 工具筛选提示词
max_tools number 无限 限制最多多少工具参与
always_include list[str] None 永远包含的工具

LLM tool emulator（LLM工具模拟器）

使用LLM模拟工具的执行，用于测试目的，确保工具在实际使用中的表现符合预期。

使用LLM（大型语言模型）来模拟工具的执行，用于测试目的，用AI生成的响应来替代实际的工具调用。在测试阶段，不需要真正调用外部工具，而是通过LLM生成模拟的响应来测试代理（agent）的行为。这样可以避免实际工具调用可能带来的问题，如外部依赖、成本或不可用性。例如，在开发一个需要调用天气API的代理时，可以通过LLM工具模拟器生成模拟的天气数据，而不是真正调用天气API，从而测试代理对天气数据的处理逻辑。

用途

  • 在不执行实际工具的情况下测试代理的行为。可以快速验证代理的逻辑是否正确，而不必担心实际工具的执行结果。这有助于在开发初期快速迭代和调试代理的逻辑。假设代理需要调用一个支付API来完成交易，但在测试阶段，可以使用LLM工具模拟器生成模拟的支付结果，从而测试代理对支付成功的处理逻辑。
  • 当外部工具不可用或成本过高时，用于开发代理。在开发过程中，如果某些外部工具无法使用（如API限制、成本过高或开发环境限制），LLM工具模拟器可以提供替代方案，使开发工作能够继续进行。如果一个代理需要调用一个昂贵的图像识别API，但在开发阶段无法承担API费用，可以使用LLM工具模拟器生成模拟的图像识别结果，从而继续开发代理的其他功能。
  • 在实现实际工具之前，用于原型设计代理的工作流程。在设计阶段，可以快速构建代理的工作流程，验证其逻辑和功能，而不需要立即实现实际的工具调用。这有助于在早期发现潜在问题，减少开发成本和时间。在设计一个需要调用多个外部API的复杂代理时，可以先使用LLM工具模拟器构建整个工作流程，验证代理的逻辑是否符合预期，然后再逐步实现实际的工具调用。

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from langchain.agents import create_agent
from langchain.agents.middleware import LLMToolEmulator

agent = create_agent(
    model="gpt-4o",
    tools=[get_weather, search_database, send_email],
    middleware=[
        # Emulate all tools by default
        LLMToolEmulator(),

        # Emulate specific tools
        # LLMToolEmulator(tools=["get_weather", "search_database"]),

        # Use custom model
        # LLMToolEmulator(model="claude-sonnet-4-5-20250929"),
    ],
)

配置选项

参数名 类型 默认值 说明
tools list None 要模拟的工具（None=全部）
model string/BaseModel anthropic:claude-3-5-sonnet-latest 用于模拟的模型

系统与文件操作

Shell tool（Shell工具）

为代理提供一个持久的Shell会话，用于执行命令，方便进行系统级的操作。

用途

  • 需要执行系统命令的代理。例如，一个代理可能需要运行系统命令来获取系统信息、管理服务或执行脚本。
  • 开发和部署自动化任务。在软件开发和部署过程中，经常需要执行一系列命令来编译代码、运行测试、部署应用程序等。Shell工具中间件可以帮助自动化这些任务。
  • 测试和验证工作流。在测试环境中，代理可能需要运行各种命令来验证系统的行为或执行测试脚本。
  • 文件系统操作和脚本执行。代理可以使用Shell工具中间件来执行文件系统操作，如创建文件、删除文件、移动文件等，以及运行各种脚本语言编写的脚本，如Python脚本、Shell脚本等。

注意：在安全方面，要根据你的部署的安全需求，使用合适的执行策略（HostExecutionPolicy、DockerExecutionPolicy 或者 CodexSandboxExecutionPolicy）。

  • HostExecutionPolicy（主机执行策略）：一种执行策略，可能与在主机上直接运行程序或任务相关，适用于不需要容器化等隔离环境的场景，直接利用主机的资源和环境进行操作，但可能面临主机层面的安全风险，需要严格控制访问权限等安全措施。
  • DockerExecutionPolicy（Docker 执行策略）：与 Docker 容器相关的执行策略，利用 Docker 容器的隔离特性，将应用程序或任务运行在独立的容器环境中，可以有效限制应用程序对主机系统的访问和影响，降低安全风险，适合需要隔离和便于部署的应用场景。
  • CodexSandboxExecutionPolicy（Codex 沙箱执行策略）：一种沙箱执行策略，可能用于在更严格的隔离环境中运行代码或任务，类似于沙箱技术，为代码提供一个受限的运行环境，防止恶意代码对系统造成危害，适用于运行来自不可信来源的代码或需要高度安全隔离的场景。

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from langchain.agents import create_agent
from langchain.agents.middleware import (
    ShellToolMiddleware,
    HostExecutionPolicy,
)

agent = create_agent(
    model="gpt-4o",
    tools=[search_tool],
    middleware=[
        ShellToolMiddleware(
            workspace_root="/workspace",
            execution_policy=HostExecutionPolicy(),
        ),
    ],
)

配置选项

参数名 类型 默认值 说明
workspace_root str/Path/None Shell会话的根目录。如果省略，当代理启动时会创建一个临时目录，代理结束时会删除该目录。
startup_commands tuple[str, …]/ list[str] /str/None 会话开始后依次执行的可选命令。
execution_policy BaseExecutionPolicy/None 控制超时、输出限制和资源配置的执行策略。(上述有详细介绍)
redaction_rules tuple[RedactionRule, …] /list[RedactionRule]/None 可选的脱敏规则，用于在将命令输出返回给模型之前对其进行清理。
tool_description str/None 注册的shell工具描述的可选覆盖。
shell_command Sequence[str] /str/None 用于启动持久会话的可选shell可执行文件（字符串）或参数序列。默认为/bin/bash。
env Mapping[str, Any] /None 提供给shell会话的可选环境变量。在命令执行前，值会被转换为字符串。

File search（文件搜索）

提供基于Glob和Grep的文件搜索工具，方便在文件系统中查找文件。

  • Glob：是一种基于模式匹配的文件查找工具。它使用特定的模式（如通配符）来匹配文件名，从而快速找到符合模式的文件。例如，模式“*/.py”可以匹配当前目录及其子目录下所有的 Python 文件。
  • Grep：是一种基于正则表达式的文本搜索工具。它可以在文件内容中搜索符合特定正则表达式的文本。例如，使用 Grep 搜索“async def”，可以找到包含该代码片段的 Python 文件。
  • 文件系统：指的是计算机中用于组织和存储文件和目录的结构。这里的文件搜索工具可以在文件系统中进行操作，帮助用户查找和分析文件。

用途

  • Code exploration and analysis（代码探索和分析）：在开发过程中，开发者可能需要探索代码库，了解代码的结构、功能和依赖关系。文件搜索工具可以帮助开发者快速找到特定的代码文件或代码片段，从而进行更高效的代码分析。例如，通过搜索特定的函数名或类名，可以快速定位到相关的代码位置，便于理解代码的实现逻辑和进行调试。
  • Finding files by name patterns（按文件名模式查找文件）：有时用户需要根据文件名的特定模式来查找文件，例如查找所有以“config”开头的配置文件，或者查找所有扩展名为“.txt”的文本文件。Glob 搜索工具可以根据用户提供的模式，快速匹配并列出符合条件的文件，方便用户进行后续的操作，如批量处理或查看文件内容。
  • Searching code content with regex（使用正则表达式搜索代码内容）：在代码中，可能需要查找特定的代码模式或文本内容，例如查找所有使用了某个特定变量的代码行，或者查找符合某种代码风格的代码片段。Grep 搜索工具通过正则表达式匹配，可以在代码文件中精确地搜索到用户需要的内容，这对于代码审查、重构和维护等工作非常有帮助。
  • Large codebases where file discovery is needed（需要文件发现的大型代码库）：在大型代码库中，文件数量众多且结构复杂，手动查找文件会非常耗时且容易出错。文件搜索中间件可以帮助开发者快速发现和定位所需的文件，提高开发效率。例如，在一个包含数千个文件的大型项目中，通过文件搜索工具可以快速找到特定模块的代码文件，或者查找与某个功能相关的所有文件，从而更好地进行代码管理和开发工作。

代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
from langchain.agents import create_agent
from langchain.agents.middleware import FilesystemFileSearchMiddleware

agent = create_agent(
    model="gpt-4o",
    tools=[],
    middleware=[
        FilesystemFileSearchMiddleware(
            root_path="/workspace",
            use_ripgrep=True,
        ),
    ],
)

配置选项

参数名 类型 默认值 说明
root_path str 必填 根目录用于搜索。所有文件操作都相对于这个路径。
use_ripgrep bool True 是否使用ripgrep进行搜索。如果ripgrep不可用，则回退到Python正则表达式。
max_file_size_mb int 10 搜索的最大文件大小，单位为MB。大于此大小的文件将被跳过。