Langchain Dev Utils

https://tbice123123.github.io/langchain-dev-utils/zh
Admin
Langchain Dev Utils is a lightweight utility library designed to enhance the development experience...
Tokens:85,395
Snippets:551
Trust Score:8.3
Update:13 hours ago
Show doc for...
Tokens:
Raw
### Clone the example repository

Source: https://tbice123123.github.io/langchain-dev-utils/zh/resource/example-project/

Clone the langchain-dev-utils-example repository and navigate into the project directory.

```bash
git clone https://github.com/TBice123123/langchain-dev-utils-example.git  
cd langchain-dev-utils-example
```

--------------------------------

### PlanMiddleware instantiation example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Shows how to create a PlanMiddleware instance with default settings.

```python
plan_middleware = PlanMiddleware()
```

--------------------------------

### Install dependencies with uv

Source: https://tbice123123.github.io/langchain-dev-utils/zh/resource/example-project/

Use uv to synchronize and install project dependencies.

```bash
uv sync
```

--------------------------------

### LLMToolEmulator instantiation example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Shows how to create an LLMToolEmulator with a model and a list of tools.

```python
llm_tool_emulator = LLMToolEmulator(model="vllm:qwen2.5-7b", tools=[get_current_time])
```

--------------------------------

### FormatPromptMiddleware instantiation example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Creates an instance of FormatPromptMiddleware with template_format set to 'jinja2'.

```python
format_prompt_middleware = FormatPromptMiddleware(template_format="jinja2")
```

--------------------------------

### wrap_agent_as_tool usage example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Example of wrapping a single agent as a tool.

```python
tool = wrap_agent_as_tool(agent)
```

--------------------------------

### Start the project with langgraph dev

Source: https://tbice123123.github.io/langchain-dev-utils/zh/resource/example-project/

Launch the project using the langgraph development server.

```bash
langgraph dev
```

--------------------------------

### ModelFallbackMiddleware instantiation example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Shows how to create a ModelFallbackMiddleware with a primary model and a fallback model.

```python
model_fallback_middleware = ModelFallbackMiddleware(
    "vllm:qwen2.5-7b",
    "vllm:qwen2.5-3b"
)
```

--------------------------------

### wrap_all_agents_as_tool usage example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Example of wrapping multiple agents as a single tool. Requires at least two agents, each with a unique name.

```python
tool = wrap_all_agents_as_tool([time_agent, weather_agent])
```

--------------------------------

### HandoffAgentMiddleware usage example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Shows how to instantiate HandoffAgentMiddleware with a configuration dictionary for two agents, including model, prompt, tools, and handoffs.

```python
handoffs_agent_middleware = HandoffsAgentMiddleware({
    "time_agent":{
        "model":"vllm:qwen2.5-7b",
        "prompt":"你是一个时间智能体，负责回答时间相关的问题。",
        "tools":[get_current_time, transfer_to_default_agent],
        "handoffs":["default_agent"]
    },
    "default_agent":{
        "model":"vllm:qwen2.5-3b",
        "prompt":"你是一个复杂任务智能体，负责回答复杂任务相关的问题。",
        "default":True,
        "handoffs":["time_agent"]
    }
})
```

--------------------------------

### ToolCallRepairMiddleware instantiation example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Creates an instance of ToolCallRepairMiddleware.

```python
tool_call_repair_middleware = ToolCallRepairMiddleware()
```

--------------------------------

### SummarizationMiddleware usage example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Instantiates SummarizationMiddleware with a vLLM-hosted Qwen2.5-7B model identifier.

```python
summarization_middleware = SummarizationMiddleware(model="vllm:qwen2.5-7b")
```

--------------------------------

### ModelRouterMiddleware usage example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Shows how to instantiate ModelRouterMiddleware with a router model and a list of model dictionaries, each containing model_name and model_description.

```python
model_router_middleware = ModelRouterMiddleware(
    router_model="vllm:qwen2.5-7b",
    model_list=[
        {
            "model_name": "vllm:qwen2.5-7b",
            "model_description": "适合普通任务，如对话、文本生成等"
        },
        {
            "model_name": "vllm:qwen3-4b",
            "model_description": "适合复杂任务，如代码生成、数据分析等",
        },
    ]
)
```

--------------------------------

### LLMToolSelectorMiddleware usage example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Instantiates LLMToolSelectorMiddleware with a vLLM-hosted Qwen2.5-7B model identifier.

```python
llm_tool_selector_middleware = LLMToolSelectorMiddleware(model="vllm:qwen2.5-7b")
```

--------------------------------

### create_openai_compatible_model usage example

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/chat_model/

Example of creating a chat model class for the vLLM provider using create_openai_compatible_model. It sets the provider to 'vllm', the base URL to 'http://localhost:8000/v1', and names the class 'ChatVLLM'.

```python
ChatVLLM = create_openai_compatible_model(
    model_provider="vllm",
    base_url="http://localhost:8000/v1",
    chat_model_cls_name="ChatVLLM",
)
```

--------------------------------

### Define provider-wide model profiles with create_openai_compatible_model

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/openai-compatible/chat/

Shows how to create a model class for a provider (vLLM) with a dictionary of model profiles. The profiles are passed to create_openai_compatible_model and then used when instantiating the model. The example includes a profile for qwen2.5-7b.

```python
from langchain_dev_utils.chat_models.adapters import create_openai_compatible_model

model_profiles = {
    "qwen2.5-7b": {
        "max_input_tokens": 131072,
        "max_output_tokens": 8192,
        "image_inputs": False,
        "audio_inputs": False,
        "video_inputs": False,
        "image_outputs": False,
        "audio_outputs": False,
        "video_outputs": False,
        "reasoning_output": False,
        "tool_calling": True
    },
    # 此处可添加更多 model profile
}

ChatVLLM = create_openai_compatible_model(
    model_provider="vllm",
    base_url="http://localhost:8000/v1",
    model_profiles=model_profiles,
)

model = ChatVLLM(
    model="qwen2.5-7b",
)
print(model.profile)
```

--------------------------------

### Enable Responses API with use_responses_api=True

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/openai-compatible/chat/

Shows how to enable the OpenAI Responses API by passing use_responses_api=True to the model constructor. The example uses vLLM and invokes the model with a HumanMessage.

```python
from langchain_core.messages import HumanMessage

model = ChatVLLM(model="qwen2.5-7b", use_responses_api=True)
response = model.invoke([HumanMessage(content="你好")])
print(response)
```

--------------------------------

### Create .env file

Source: https://tbice123123.github.io/langchain-dev-utils/zh/resource/example-project/

Copy the .env.example file to create a new .env file for configuration.

```bash
cp .env.example .env
```

--------------------------------

### 创建 OpenAI 兼容的 vLLM 模型类 (create_openai_compatible_model)

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/graph/

使用 create_openai_compatible_model 创建与 OpenAI 兼容的模型类，用于接入本地 vLLM 部署的 qwen2.5-7b。需指定 model_provider='vllm' 和 base_url。

```python
from langchain_dev_utils.chat_models.adapters import create_openai_compatible_model

ChatVLLM = create_openai_compatible_model(
    model_provider="vllm",
    base_url="http://localhost:8000/v1",
    chat_model_cls_name="ChatVLLM",
)
```

--------------------------------

### 使用 wrap_all_agents_as_tool 封装多个智能体

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/multi-agent/

将多个智能体实例作为列表传入 wrap_all_agents_as_tool，生成统一工具 call_subagent，并创建主智能体。tool_name 和 tool_description 为可选参数，省略时默认值分别为 'task' 和 'Launch an ephemeral subagent for a task.\nAvailable agents:\n {available_agents}'。建议显式设置描述以帮助主智能体识别。

```python
call_subagent_tool = wrap_all_agents_as_tool(
    [calendar_agent, email_agent],
    tool_name="call_subagent",
    tool_description=(
        "调用子智能体执行任务。"
        "可以使用的智能体有："
        "- calendar_agent：用于安排日历事件"
        "- email_agent：用于发送电子邮件"
    ),
)

MAIN_AGENT_PROMPT = (
    "你是一个有用的个人助手。"
    "你可以使用**call_subagent**工具调用子智能体执行任务。"
    "将用户请求分解为适当的工具调用，并协调结果。"
    "当请求涉及多个操作时，请使用多个工具按顺序操作。"
)

main_agent = create_agent(
    "vllm:qwen2.5-7b",
    tools=[call_subagent_tool],
    system_prompt=MAIN_AGENT_PROMPT,
)
```

--------------------------------

### 使用 PlanMiddleware 创建 agent 并调用

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/middleware/plan/

示例展示了如何导入 PlanMiddleware，将其作为 middleware 传入 create_agent，并配置自定义工具描述和 use_read_plan_tool 参数。最后通过 agent.invoke 发送消息并打印响应。

```python
from langchain_dev_utils.agents.middleware import PlanMiddleware

agent = create_agent(
    model="openai:gpt-4o",
    middleware=[
        PlanMiddleware(
            custom_plan_tool_descriptions={
                "write_plan": "用于写计划，将任务拆解为多个有序的子任务。",
                "finish_sub_plan": "用于完成子任务，更新子任务状态为已完成。",
                "read_plan": "用于查询当前的任务规划列表。"
            },
            use_read_plan_tool=True,  # 如果不使用读计划工具，可以设置此参数为 False
        )
    ],
)

response = agent.invoke(
    {"messages": [HumanMessage(content="我要去New York玩几天，帮我规划行程")]}
)
print(response)
```

--------------------------------

### SummarizationMiddleware.__init__

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Initializes a SummarizationMiddleware instance for summarizing agent context. It accepts a model identifier and optional parameters for triggering summarization, keeping context, token counting, and prompt customization.

```APIDOC
## SummarizationMiddleware.__init__

### Description
Initializes a SummarizationMiddleware instance for summarizing agent context.

### Method
Constructor

### Signature
```python
class SummarizationMiddleware(_SummarizationMiddleware):
    def __init__(
        self,
        model: str,
        *,
        trigger: ContextSize | list[ContextSize] | None = None,
        keep: ContextSize = ("messages", _DEFAULT_MESSAGES_TO_KEEP),
        token_counter: TokenCounter = count_tokens_approximately,
        summary_prompt: str = DEFAULT_SUMMARY_PROMPT,
        trim_tokens_to_summarize: int | None = _DEFAULT_TRIM_TOKEN_LIMIT,
        **deprecated_kwargs: Any,
    ) -> None
```

### Parameters
- **model** (str) - Required - Model identifier string loadable by `load_chat_model`. Can be specified as "provider:model-name" format.
- **trigger** (ContextSize | list[ContextSize] | None) - Optional - Default: None - Context size that triggers summarization.
- **keep** (ContextSize) - Optional - Default: ("messages", _DEFAULT_MESSAGES_TO_KEEP) - Context size to keep.
- **token_counter** (TokenCounter) - Optional - Default: count_tokens_approximately - Token counter function.
- **summary_prompt** (str) - Optional - Default: DEFAULT_SUMMARY_PROMPT - Prompt used for summarization.
- **trim_tokens_to_summarize** (int | None) - Optional - Default: _DEFAULT_TRIM_TOKEN_LIMIT - Number of tokens to trim before summarization.

### Example
```python
summarization_middleware = SummarizationMiddleware(model="vllm:qwen2.5-7b")
```
```

--------------------------------

### Pass custom profile at model instantiation

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/openai-compatible/chat/

Shows how to pass a custom profile dictionary to the ChatVLLM constructor. The profile is accessible via model.profile. The example includes a partial profile with max_input_tokens, tool_calling, and structured_output.

```python
from langchain_core.messages import HumanMessage

custom_profile = {
    "max_input_tokens": 131072,
    "tool_calling": True,
    "structured_output": True,
    # ...
}
model = ChatVLLM(model="qwen2.5-7b", profile=custom_profile)
print(model.profile)
```

--------------------------------

### 使用 format_prompt 同时从 state 和 context 获取变量

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/middleware/format/

混合使用 state 和 context 的数据。{name} 从 state 获取，{user} 从 context 获取。调用时需为 state 提供 'name'，为 context 提供 'user'。

```python
from dataclasses import dataclass

@dataclass
class Context:
    user: str

agent = create_agent(
    model="vllm:qwen2.5-7b",
    # {name} 将从 state 获取，{user} 将从 context 获取
    system_prompt="你是一个智能助手，你的名字叫做{name}。你的使用者叫做{user}。",
    middleware=[format_prompt],
    state_schema=AssistantState,
    context_schema=Context,
)

# 调用时，为 state 提供 'name'，为 context 提供 'user'
response = agent.invoke(
    {
        "messages": [HumanMessage(content="我要去New York玩几天，帮我规划行程")],
        "name": "assistant",
    },
    context=Context(user="张三"),
)
print(response)
```

--------------------------------

### 使用 FormatPromptMiddleware 实现 Jinja2 条件逻辑

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/middleware/format/

使用 Jinja2 语法根据条件动态生成提示词。需手动实例化 FormatPromptMiddleware 并指定 template_format="jinja2"。注意：启用后 system_prompt 会被编译为 Template 对象，务必将提示词主干硬编码在代码中，不要将用户输入直接作为 system_prompt 传入。

```python
from langchain_dev_utils.agents.middleware import FormatPromptMiddleware
from dataclasses import dataclass
from typing import Optional

@dataclass
class Context:
    user_role: Optional[str] = None  # 用户角色，例如 "VIP", "Admin"

# 手动实例化中间件，指定格式为 jinja2
jinja2_formatter = FormatPromptMiddleware(template_format="jinja2")

agent = create_agent(
    model="vllm:qwen2.5-7b",
    # 使用 {{ }} 语法
    system_prompt=(
        "你是一个智能助手。\n"
        "{% if user_role == 'VIP' %}"
        "请务必提供尊贵、周到的服务。\n"
        "{% elif user_role == 'Admin' %}"
        "请展示系统管理员的权限和严谨性。\n"
        "{% else %}"
        "请提供标准的用户服务。\n"
        "{% endif %}"
    ),
    middleware=[jinja2_formatter],
    context_schema=Context,
)

# 示例 1：普通用户
response = agent.invoke(
    {"messages": [HumanMessage(content="你好")]},
    context=Context(user_role="Guest"),
)

# 示例 2：VIP 用户
# 系统提示词将包含 "请务必提供尊贵、周到的服务"
response = agent.invoke(
    {"messages": [HumanMessage(content="你好")]},
    context=Context(user_role="VIP"),
)
```

--------------------------------

### 设置 VLLM_API_KEY 环境变量

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/openai-compatible/embedding/

导出环境变量 VLLM_API_KEY，因为嵌入模型类初始化时需要传入 API Key，即使 vLLM 本身不要求。

```bash
export VLLM_API_KEY=vllm_api_key
```

--------------------------------

### vLLM 部署 Qwen2.5-VL-7B 模型

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/openai-compatible/overview/

部署 Qwen2.5-VL-7B-Instruct 模型，启用信任远程代码，监听 0.0.0.0:8000，服务模型名为 qwen2.5-vl-7b。

```bash
vllm serve Qwen/Qwen2.5-VL-7B-Instruct \
--trust-remote-code \
--host 0.0.0.0 --port 8000 \
--served-model-name qwen2.5-vl-7b
```

--------------------------------

### LLMToolSelectorMiddleware.__init__

Source: https://tbice123123.github.io/langchain-dev-utils/zh/api-reference/agent/

Initializes an LLMToolSelectorMiddleware instance for selecting tools via an LLM. It accepts a model identifier and optional parameters for system prompt, maximum tools, and tools to always include.

```APIDOC
## LLMToolSelectorMiddleware.__init__

### Description
Initializes an LLMToolSelectorMiddleware instance for selecting tools via an LLM.

### Method
Constructor

### Signature
```python
class LLMToolSelectorMiddleware(_LLMToolSelectorMiddleware):
    def __init__(
        self,
        *,
        model: str,
        system_prompt: Optional[str] = None,
        max_tools: Optional[int] = None,
        always_include: Optional[list[str]] = None,
    ) -> None
```

### Parameters
- **model** (str) - Required - Model identifier string loadable by `load_chat_model`. Can be specified as "provider:model-name" format.
- **system_prompt** (Optional[str]) - Optional - Default: None - System prompt for the LLM.
- **max_tools** (Optional[int]) - Optional - Default: None - Maximum number of tools to select.
- **always_include** (Optional[list[str]]) - Optional - Default: None - List of tool names to always include.

### Example
```python
llm_tool_selector_middleware = LLMToolSelectorMiddleware(model="vllm:qwen2.5-7b")
```
```

--------------------------------

### 创建 supervisor_agent 并调用封装工具

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/multi-agent/

创建 supervisor_agent，使用 schedule_event 和 manage_email 工具，并演示如何调用。注意这里从 langchain_dev_utils.agents 导入 create_agent，而非 langchain.agents。

```python
SUPERVISOR_PROMPT = (
    "你是一个有用的个人助手。"
    "你可以安排日历事件并发送电子邮件。"
    "将用户请求分解为适当的工具调用，并协调结果。"
    "当请求涉及多个操作时，请使用多个工具按顺序操作。"
)


supervisor_agent = create_agent(
    "vllm:qwen2.5-7b",
    tools=[schedule_event, manage_email],
    system_prompt=SUPERVISOR_PROMPT,
)

print(
    supervisor_agent.invoke({"messages": [HumanMessage(content="查询明天的空闲时间")]})
)
print(
    supervisor_agent.invoke(
        {"messages": [HumanMessage(content="给test@123.com发送邮件会议提醒")]}
    )
)
```

--------------------------------

### 使用 uv 安装完整功能版

Source: https://tbice123123.github.io/langchain-dev-utils/zh/getting-started-guide/installation/

使用 uv 添加 langchain-dev-utils 的 standard 版本。

```bash
uv add langchain-dev-utils[standard]
```

--------------------------------

### vLLM 部署 Qwen2.5-7B 模型

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/openai-compatible/overview/

部署 Qwen2.5-7B-Instruct 模型，启用自动工具调用和 hermes 工具调用解析器，监听 0.0.0.0:8000，服务模型名为 qwen2.5-7b。

```bash
vllm serve Qwen/Qwen2.5-7B-Instruct \
--enable-auto-tool-choice --tool-call-parser hermes \
--host 0.0.0.0 --port 8000 \
--served-model-name qwen2.5-7b
```

--------------------------------

### 使用 uv 安装基础版

Source: https://tbice123123.github.io/langchain-dev-utils/zh/getting-started-guide/installation/

使用 uv 添加 langchain-dev-utils 基础版本。

```bash
uv add langchain-dev-utils
```

--------------------------------

### 使用 format_prompt 从 state 获取变量

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/middleware/format/

最基础的用法，所有占位符变量均由 state 提供。调用时必须为 state 提供 'name' 的值。

```python
from langchain_dev_utils.agents.middleware import format_prompt
from langchain.agents import AgentState

class AssistantState(AgentState):
    name: str

agent = create_agent(
    model="vllm:qwen2.5-7b",
    system_prompt="你是一个智能助手，你的名字叫做{name}。",
    middleware=[format_prompt],
    state_schema=AssistantState,
)

# 调用时，必须为 state 提供 'name' 的值
response = agent.invoke(
    {"messages": [HumanMessage(content="你好啊")], "name": "assistant"}
)
print(response)
```

--------------------------------

### 强制工具调用 tool_choice 配置

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/openai-compatible/chat/

通过 compatibility_options 配置 supported_tool_choice 以支持 tool_choice 的 required 等取值。

```python
from langchain_dev_utils.chat_models.adapters import create_openai_compatible_model

ChatVLLM = create_openai_compatible_model(
    model_provider="vllm",
    chat_model_cls_name="ChatVLLM",
    compatibility_options={
        "supported_tool_choice": ["auto", "required", "none", "specific"]
    },
)

model = ChatVLLM(model="qwen2.5-7b").bind_tools(
    [get_current_weather], tool_choice="required"
)
```

--------------------------------

### 定义模型列表 (model_list)

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/middleware/router/

定义模型列表，每个模型配置包含 model_name、model_description、tools、model_kwargs、model_system_prompt 和 model_instance 等字段。model_name 使用 provider:model-name 格式，model_instance 提供时直接使用实例，否则根据 model_name 和 model_kwargs 加载模型。

```python
from langchain_dev_utils.agents.middleware.model_router import ModelDict

model_list: list[ModelDict] = [
    {
        "model_name": "vllm:qwen2.5-7b",
        "model_description": "适合普通任务，如对话、文本生成等",
        "model_kwargs": {
            "temperature": 0.7,
            "extra_body": {"chat_template_kwargs": {"enable_thinking": False}},
        },
        "model_system_prompt": "你是一个助手，擅长处理普通任务，如对话、文本生成等。",
    },
    {
        "model_name": "vllm:qwen2.5-vl-7b",
        "model_description": "适合视觉任务",
        "tools": [],  # 如果该模型不需要任何工具，请将此字段设置为空列表 []
    },
    {
        "model_name": "vllm:glm-4.7-flash",
        "model_description": "适合代码生成任务",
        "tools": [run_python_code],  # 仅允许使用 run_python_code 工具
    },
    {
        "model_name": "openai:gpt-4o",
        "model_description": "适合综合类高难度任务",
        "model_system_prompt": "你是一个助手，擅长处理综合类的高难度任务",
        "model_instance": ChatOpenAI(
            model="gpt-4o"
        ),  # 直接传入实例，此时 model_name 仅作标识，model_kwargs 被忽略
    },
]

```

--------------------------------

### 从 langchain_dev_utils.agents 导入 create_agent

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/middleware/overview/

从 langchain_dev_utils.agents 导入 create_agent 函数，该函数与官方 create_agent 功能相同，但支持通过字符串指定模型，可直接使用注册的模型提供商。

```python
from langchain_dev_utils.agents import create_agent
```

--------------------------------

### 使用 SummarizationMiddleware 并注册模型提供者

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/middleware/official/

导入 SummarizationMiddleware 和 register_model_provider，注册 vllm 提供者，然后创建 agent 并指定模型为 'vllm:qwen2.5-7b'。中间件配置了触发条件（tokens 达到 50）和保留消息数（1）。

```python
from langchain_core.messages import AIMessage
from langchain_dev_utils.agents.middleware import SummarizationMiddleware
from langchain_dev_utils.chat_models import register_model_provider

# 必须先通过 register_model_provider 注册模型
register_model_provider(
    provider_name="vllm",
    chat_model="openai-compatible",
    base_url="http://localhost:8000/v1",
)

agent = create_agent(
    model="vllm:qwen2.5-7b",
    middleware=[
        SummarizationMiddleware(
            model="vllm:qwen2.5-7b",
            trigger=("tokens", 50),
            keep=("messages", 1),
        )
    ],
    system_prompt="你是一个智能的AI助手，可以解决用户的问题",
)
response = agent.invoke({"messages": messages})
print(response)
```

--------------------------------

### 使用 HandoffAgentMiddleware 创建 Agent

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/middleware/handoffs/

将 agent_config 传递给 HandoffAgentMiddleware 并创建 agent，然后调用 invoke 进行测试。注意使用中间件后，create_agent 的 tools 和 system_prompt 参数会被忽略。

```python
from langchain_dev_utils.agents.middleware import HandoffAgentMiddleware

agent = create_agent(
    model="vllm:qwen2.5-7b",
    middleware=[HandoffAgentMiddleware(agents_config=agent_config)],
)

response = agent.invoke({"messages": [HumanMessage(content="当前时间是多少？")]})
print(response)
```

--------------------------------

### 使用 create_parallel_graph 创建并行子图

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/graph/

通过 create_parallel_graph 函数创建并行子图，传入子智能体节点列表、状态模式和 branches_fn 参数（route_to_agents），实现根据条件动态并行执行。

```python
from langchain_dev_utils.graph import create_parallel_graph

router_graph = create_parallel_graph(
    nodes=[
        order,
        product,
        refund,
    ],
    state_schema=RouterState,
    branches_fn=route_to_agents, # 核心逻辑：由函数决定运行哪些分支
)
```

--------------------------------

### 加载官方提供商模型

Source: https://tbice123123.github.io/langchain-dev-utils/zh/getting-started-guide/chat/

`load_chat_model` 未命中全局注册字典时，会通过 `init_chat_model` 初始化，因此 LangChain 官方支持的提供商（如 openai）可直接调用，无需注册。

```python
model = load_chat_model("openai:gpt-4o-mini")
# 或
model = load_chat_model("gpt-4o-mini", model_provider="openai")
```

--------------------------------

### 创建 vLLM 推理模型并获取推理内容

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/openai-compatible/chat/

使用 create_openai_compatible_model 创建 ChatVLLM 类，指定 reasoning_field_name 为 'reasoning' 以适配新版 vLLM 返回的推理字段。调用模型后，从 response.content_blocks 中提取 reasoning 类型的内容并打印。

```python
from langchain_dev_utils.chat_models.adapters import create_openai_compatible_model
from langchain_core.messages import HumanMessage

ChatVLLM = create_openai_compatible_model(
    model_provider="vllm",
    base_url="http://localhost:8000/v1",
    chat_model_cls_name="ChatVLLM",
    compatibility_options={
        "reasoning_field_name": "reasoning",
    },
)

model = ChatVLLM(model="qwen3-4b")
response = model.invoke("为什么鹦鹉的羽毛如此鲜艳？")
reasoning_steps = [b for b in response.content_blocks if b["type"] == "reasoning"]
print(" ".join(step["reasoning"] for step in reasoning_steps))
```

--------------------------------

### 定义库存、订单、支付、发货工具

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/graph/

使用 @tool 装饰器定义四个工具函数：check_inventory、create_order、pay_order、confirm_delivery，分别用于查询库存、创建订单、支付和确认发货。

```python
from langchain_core.tools import tool

@tool
def check_inventory(product_name: str) -> dict:
    """查询库存"""
    return {"product_name": product_name, "in_stock": True, "available": 42}

@tool
def create_order(product_name: str, quantity: int) -> str:
    """创建订单"""
    return f"已创建订单 ORD-10001，商品：{product_name}，数量：{quantity}。"

@tool
def pay_order(order_id: str) -> str:
    """支付订单"""
    return f"订单 {order_id} 支付成功。"

@tool
def confirm_delivery(order_id: str, address: str) -> str:
    """确认发货"""
    return f"订单 {order_id} 已安排发货，收货地址：{address}。"
```

--------------------------------

### 定义并行工作流的工具（Python）

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/graph/

定义四个工具函数：get_product_detail、check_inventory、calculate_promotions 和 estimate_shipping，用于商品详情、库存、优惠和运费查询。

```python
@tool
def get_product_detail(product_name: str) -> dict:
    """查询商品详情"""
    return {
        "product_name": product_name,
        "sku": "SKU-10001",
        "price": 299,
        "highlights": ["主动降噪", "蓝牙5.3", "30小时续航"],
    }

@tool
def check_inventory(product_name: str) -> dict:
    """查询库存"""
    return {"product_name": product_name, "in_stock": True, "available": 42}

@tool
def calculate_promotions(product_name: str, quantity: int) -> dict:
    """计算优惠"""
    return {
        "product_name": product_name,
        "quantity": quantity,
        "discounts": ["满300减30", "会员95折"],
        "estimated_discount": 45,
    }

@tool
def estimate_shipping(address: str) -> dict:
    """估算运费和时效"""
    return {
        "address": address,
        "fee": 12,
        "eta_days": 2,
    }
```

--------------------------------

### 兼容官方提供商

Source: https://tbice123123.github.io/langchain-dev-utils/zh/getting-started-guide/embedding/

load_embeddings 依据 provider 参数查找全局注册字典：命中则使用该字典对应的模型类实例化，未命中则通过 init_embeddings 初始化。LangChain 官方支持的提供商（如 openai）可直接调用，无需注册。

```python
model = load_embeddings("openai:text-embedding-3-large")
# 或
model = load_embeddings("text-embedding-3-large", provider="openai")
```

--------------------------------

### 安装 langchain-dev-utils

Source: https://tbice123123.github.io/langchain-dev-utils/zh/

使用 pip 安装 langchain-dev-utils 的 standard 版本，该版本是使用 OpenAI-Compatible API 功能的必需版本。

```bash
pip install -U "langchain-dev-utils[standard]"
```

--------------------------------

### 注册已有 LangChain 对话模型类

Source: https://tbice123123.github.io/langchain-dev-utils/zh/getting-started-guide/chat/

当模型提供商已有现成的 LangChain 集成时，将集成对话模型类作为 `chat_model` 参数传入。`provider_name` 用于后续在 `load_chat_model` 中引用，必须以字母或数字开头，只能包含字母、数字和下划线，长度不超过 20 个字符。FakeChatModel 仅用于测试，实际使用中必须传入具备真实功能的 ChatModel 类。

```python
from langchain_core.language_models.fake_chat_models import FakeChatModel
from langchain_dev_utils.chat_models import register_model_provider

register_model_provider(
    provider_name="fake_provider",
    chat_model=FakeChatModel,
)

# FakeChatModel 仅用于测试，实际使用中必须传入具备真实功能的 ChatModel 类。
```

--------------------------------

### AgentConfig 配置字典

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/middleware/handoffs/

每个智能体的配置字典，包含 model、prompt、tools、default、handoffs 等字段。

```APIDOC
## AgentConfig

### Description
每个智能体的配置字典，包含 model、prompt、tools、default、handoffs 等字段。

### Fields
- **model** (str | BaseChatModel) - Optional - 指定该智能体使用的模型；若不传，则沿用 create_agent 的 model 参数对应的模型。支持字符串（须为 provider:model-name 格式，如 vllm:qwen2.5-7b）或 BaseChatModel 实例。
- **prompt** (str | SystemMessage) - Required - 智能体的系统提示词。
- **tools** (list[BaseTool]) - Optional - 智能体可调用的工具列表；若不传，该智能体仅拥有相关的交接工具。
- **default** (bool) - Optional - 是否设为默认智能体；缺省为 False。全部配置中必须且只能有一个智能体设为 True。
- **handoffs** (list[str] | str) - Required - 该智能体可交接给的其它智能体名称列表。若设为 "all"，则表示该智能体可交接给所有其它智能体。

### Usage Example
```python
from langchain_dev_utils.agents.middleware.handoffs import AgentConfig

agent_config: dict[str, AgentConfig] = {
    "time_agent": {
        "prompt": "你是一个时间助手",
        "tools": [get_current_time],
        "handoffs": ["default_agent"],
    },
    "weather_agent": {
        "prompt": "你是一个天气助手",
        "tools": [get_current_weather, get_current_city],
        "handoffs": ["default_agent"],
    },
    "code_agent": {
        "model": load_chat_model("vllm:glm-4.7-flash"),
        "prompt": "你是一个代码助手",
        "tools": [run_code],
        "handoffs": ["default_agent"],
    },
    "default_agent": {
        "model": "openai:gpt-4o-mini",
        "prompt": "你是一个助手",
        "default": True,
        "handoffs": "all",
    },
}
```
```

--------------------------------

### 注册 vllm 模型提供商

Source: https://tbice123123.github.io/langchain-dev-utils/zh/adavance-guide/middleware/overview/

使用 register_model_provider 注册 vllm 模型提供商，指定为 openai-compatible 类型，并设置 base_url 为本地服务地址。这是运行后续示例的前提条件。

```python
register_model_provider(
    "vllm",
    "openai-compatible",
    base_url="http://localhost:8000/v1",
)
```
Tokens:
Raw