集成测试

通过组织测试、管理密钥、处理不稳定性以及控制成本，使用真实的 LLM API 测试智能体。

集成测试用于验证您的智能体能否与模型 API 和外部服务正确协同工作。与使用模拟和桩的单元测试不同，集成测试会进行实际的网络调用，以确认组件能协同工作、凭证有效且延迟在可接受范围内。

由于 LLM 的响应具有不确定性，集成测试需要采用与传统软件测试不同的策略。本指南将介绍如何为您的智能体组织、编写和运行集成测试。关于为 LangChain 本身贡献代码时的一般测试基础设施，请参阅代码贡献指南。

分离单元测试和集成测试

集成测试速度较慢且需要 API 凭证，因此请将其与单元测试分开。这样您可以在每次更改时运行快速的单元测试，而将集成测试保留给 CI 或部署前检查。

使用 pytest 标记来标注集成测试：

import pytest

@pytest.mark.integration
def test_agent_with_real_model():
    agent = create_agent("claude-sonnet-4-6", tools=[get_weather])
    result = agent.invoke({
        "messages": [HumanMessage(content="What's the weather in SF?")]
    })
    assert len(result["messages"]) > 1

配置 pytest 以识别该标记，并在默认运行中排除集成测试：

pytest.ini

[pytest]
markers =
    integration: tests that call real LLM APIs
addopts = -m "not integration"

显式运行集成测试：

pytest -m integration

管理 API 密钥

集成测试需要真实的 API 凭证。请从环境变量中加载它们，以确保密钥不会进入源代码管理。

使用 conftest.py 中的 fixture 来验证所需的密钥是否可用：

import os
import pytest

@pytest.fixture(autouse=True)
def check_api_keys():
    if not os.environ.get("OPENAI_API_KEY"):
        pytest.skip("OPENAI_API_KEY not set")

对于本地开发，将密钥存储在 .env 文件中，并使用 python-dotenv 加载：

.env

OPENAI_API_KEY=sk-...

conftest.py

from dotenv import load_dotenv

load_dotenv()

将 .env 添加到您的 .gitignore 文件中，以避免提交凭证。在 CI 中，通过您提供商（例如 GitHub Actions secrets）的密钥管理功能注入密钥。

断言结构，而非内容

LLM 的响应在不同运行之间会有所变化。与其断言确切的输出字符串，不如验证响应的结构属性：消息类型、工具调用名称、参数形状和消息数量。

def test_agent_calls_weather_tool():
    agent = create_agent("claude-sonnet-4-6", tools=[get_weather])
    result = agent.invoke({
        "messages": [HumanMessage(content="What's the weather in SF?")]
    })

    messages = result["messages"]
    tool_calls = [
        tc
        for msg in messages
        if hasattr(msg, "tool_calls")
        for tc in (msg.tool_calls or [])
    ]

    assert any(tc["name"] == "get_weather" for tc in tool_calls)
    assert isinstance(messages[-1], AIMessage)
    assert len(messages[-1].content) > 0

要进行更严格的轨迹断言，请使用 AgentEvals 评估器，它支持 unordered 和 superset 等模糊匹配模式。

降低成本和延迟

调用 LLM API 的集成测试会产生实际成本。以下几种做法有助于保持测试套件的快速和负担得起：

• 使用较小的模型：对于仅需验证工具调用和响应结构的测试，使用 gemini-3.1-flash-lite-preview 或等效模型。
• 设置 maxTokens：限制响应长度，避免冗长且昂贵的补全。
• 限制测试范围：每个测试只测试一种行为。当单轮测试足够时，避免使用需要多次 LLM 调用的端到端场景。
• 选择性运行：利用上文的测试分离，仅在 CI 或部署前运行集成测试，而不是每次保存文件时都运行。

agent = create_agent(
    "gemini-3.1-flash-lite-preview",
    tools=[get_weather],
    model_kwargs={"max_tokens": 256},
)

记录和重放 HTTP 调用

对于在 CI 中频繁运行的测试，您可以在第一次运行时记录 HTTP 交互，并在后续运行时重放它们，而无需进行真实的 API 调用。这消除了初始记录后的成本和延迟。

vcrpy 将 HTTP 请求/响应对记录到 YAML “cassette” 文件中。pytest-recording 插件将其与 pytest 集成。

在 conftest.py 中设置以过滤 cassette 文件中的敏感信息：

conftest.py

import pytest

@pytest.fixture(scope="session")
def vcr_config():
    return {
        "filter_headers": [
            ("authorization", "XXXX"),
            ("x-api-key", "XXXX"),
        ],
        "filter_query_parameters": [
            ("api_key", "XXXX"),
            ("key", "XXXX"),
        ],
    }

配置您的项目以识别 vcr 标记：

pytest.ini

[pytest]
markers =
    vcr: record/replay HTTP via VCR
addopts = --record-mode=once

--record-mode=once 选项会在第一次运行时记录 HTTP 交互，并在后续运行时重放它们。

使用 vcr 标记装饰您的测试：

@pytest.mark.vcr()
def test_agent_trajectory():
    agent = create_agent("claude-sonnet-4-6", tools=[get_weather])
    result = agent.invoke({
        "messages": [HumanMessage(content="What's the weather in SF?")]
    })
    assert any(
        tc["name"] == "get_weather"
        for msg in result["messages"]
        if hasattr(msg, "tool_calls")
        for tc in (msg.tool_calls or [])
    )

第一次运行会进行真实的网络调用，并在 tests/cassettes/ 目录下生成一个 cassette 文件。后续运行将重放记录的响应。

当您修改提示、添加新工具或更改预期轨迹时，您保存的 cassette 文件将变得过时，您现有的测试将会失败。删除相应的 cassette 文件并重新运行测试以记录新的交互。

后续步骤

了解如何使用确定性匹配或 LLM-as-judge 评估器在 Evals 中评估智能体轨迹。

---

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.