27 KiB
| search | ||
|---|---|---|
|
测试
SDK 为智能体工作流、沙箱会话、实时会话和语音管线提供确定性、与提供商无关的测试工具。这些工具在内存中运行,不会向模型、沙箱提供商或 Realtime API 发出请求,并会记录由 SDK 管理的标准化交互。下方的可运行方案会为每次运行禁用追踪,以免配置 OpenAI API 密钥后,默认追踪处理器上传测试活动。
使用这些工具测试由应用程序和 SDK 管理的编排:工具执行、任务转移、安全防护措施、重试、流式传输、会话行为、沙箱功能、实时事件处理以及语音管线组合。对于由外部模型、网络协议、沙箱提供商或音频系统管理的行为,请使用真实的提供商适配器或集成环境。
方案查找
| 我的目标 | 使用 | 前往 |
|---|---|---|
| 返回固定的最终答案 | 带有 assistant_message() 的 ScriptedModel |
返回固定响应 |
| 执行多轮工具循环 | function_call(),后接智能体响应 |
测试工具工作流 |
| 根据请求选择响应 | ModelStep.respond() 或 responder 映射 |
根据请求生成响应 |
| 断言运行器发送给模型的内容 | calls、first_call 或 last_call |
检查模型调用 |
| 测试流式运行 | 常规响应步骤,或用于精确事件的 ModelStep.stream() |
测试流式传输 |
| 测试错误或重试决策 | ModelStep.raise_error() |
注入模型故障 |
| 检测意外的工作流变更 | 精确的 FIFO 步骤加 assert_complete() |
检测工作流偏移 |
在不启动沙箱的情况下测试 SandboxAgent |
scripted_sandbox_session() 加 ScriptedModel |
测试沙箱智能体工作流 |
| 匹配沙箱调用或生成其结果 | 沙箱步骤上的 match 或 responder |
配置沙箱步骤 |
| 在不建立连接的情况下测试实时会话 | ScriptedRealtimeModel 和 RealtimeStep |
测试实时会话 |
| 测试实时工具工作流 | 发出 RealtimeModelToolCallEvent 并预期工具输出 |
测试实时工具工作流 |
| 测试静态或流式语音管线 | ScriptedSTTModel、ScriptedTTSModel,以及脚本化或真实的工作流 |
测试语音管线 |
| 测试提供商序列化或线上传输载荷 | 使用受控网络传输的真实提供商适配器 | 选择正确的边界 |
导入
测试 API 位于其所替代的运行时边界旁:
| 边界 | 导入路径 |
|---|---|
| 智能体模型和沙箱工作流 | agents.testing |
| 实时模型传输 | agents.realtime.testing |
| 语音 STT、TTS 和工作流组件 | agents.voice.testing |
测试符号特意不包含在顶层 agents 导入中。
智能体工作流方案
固定响应的返回
为每个预期的模型调用传入一个标准化输出项序列。输出序列简写形式会为一次请求接收确定性的响应 ID 和用量。
import pytest
from agents import Agent, RunConfig, Runner
from agents.testing import ScriptedModel, assistant_message
@pytest.mark.asyncio
async def test_fixed_response() -> None:
model = ScriptedModel([[assistant_message("Paris is the capital of France.")]])
agent = Agent(name="Geography assistant", model=model)
result = await Runner.run(
agent,
"What is the capital of France?",
run_config=RunConfig(tracing_disabled=True),
)
assert result.final_output == "Paris is the capital of France."
assert len(model.calls) == 1
model.assert_complete()
使用 model.assert_complete() 完成确定性工作流测试。它可以捕获工作流在用完所有已配置步骤之前停止的情况。
工具工作流的测试
编写一个调用工具的模型响应脚本,再编写一个生成最终答案的响应脚本。真实的 SDK 工具管线会在这些模型调用之间运行。
import pytest
from agents import Agent, RunConfig, Runner
from agents.decorators import tool
from agents.testing import ScriptedModel, assistant_message, function_call
@tool
def get_weather(city: str) -> str:
"""Return the weather for a city."""
return f"{city}: sunny"
@pytest.mark.asyncio
async def test_tool_workflow() -> None:
model = ScriptedModel(
[
[function_call("get_weather", {"city": "Tokyo"}, call_id="call_1")],
[assistant_message("It is sunny in Tokyo.")],
]
)
agent = Agent(name="Weather assistant", model=model, tools=[get_weather])
result = await Runner.run(
agent,
"What is the weather in Tokyo?",
run_config=RunConfig(tracing_disabled=True),
)
assert result.final_output == "It is sunny in Tokyo."
assert len(model.calls) == 2
assert model.last_call is not None
assert any(item.get("type") == "function_call_output" for item in model.last_call.input)
model.assert_complete()
此模式涵盖工具输入验证、执行、结果转换、钩子、安全防护措施以及下一轮模型交互。直接调用 Python 函数会绕过这些 SDK 行为。
基于请求的响应生成
当响应确实依赖标准化模型调用,或断言应位于模型边界时,请使用 ModelStep.respond()。响应器可以是同步或异步的,并且可以返回 ScriptedModel 接受的任何步骤形式。
import pytest
from agents import Agent, RunConfig, Runner
from agents.testing import ModelCall, ModelStep, ScriptedModel, assistant_message
def respond(call: ModelCall):
assert call.streamed is False
assert call.input == [{"content": "Summarize this", "role": "user"}]
return {"output": [assistant_message("Handled the normalized request.")]}
@pytest.mark.asyncio
async def test_request_aware_response() -> None:
model = ScriptedModel([ModelStep.respond(respond)])
agent = Agent(name="Assistant", model=model)
result = await Runner.run(
agent,
"Summarize this",
run_config=RunConfig(tracing_disabled=True),
)
assert result.final_output == "Handled the normalized request."
model.assert_complete()
ScriptedModel 接受 ModelStep、与之等效的字典形式、ModelResponse、标准化输出项序列或异常。如果响应不依赖调用,请优先使用固定输出序列,因为固定脚本能让意外轮次更易于诊断。
模型调用的检查
ScriptedModel 会在解析每次调用或引发所选步骤的异常之前记录该调用。
| 成员 | 内容 |
|---|---|
calls |
按调用顺序排列的每个 ModelCall |
first_call |
第一次调用,或 None |
last_call |
最近一次调用,或 None |
remaining_steps |
尚未消耗的已配置步骤数量 |
常见断言包括 call.input、call.model_settings、call.tools、call.handoffs 和 call.streamed。可变请求数据会在调用边界生成快照,并且每个公共历史记录访问器都会返回分离的快照。工具、任务转移、输出 schema 和追踪对象会保留其运行时标识。
结构化的 call_index 和 input_index 错误字段从零开始,因此可直接索引 calls[...] 或提供的步骤序列。可读错误消息显示从一开始计数的调用或步骤编号。
当一个测试需要逐步追加模型步骤时,请使用 enqueue() 或 extend()。对于独立场景,请创建新的 ScriptedModel;该工具不会重置已消耗的步骤或调用历史记录。
流式传输的测试
常规响应步骤同时支持 Runner.run() 和 Runner.run_streamed()。对于常见的智能体消息、推理项、函数调用和应用补丁调用,ScriptedModel 会生成标准化的开始事件、增量事件、项目完成事件和终止响应事件。终止响应包含完整输出和用量。
仅当标准化 TResponseStreamEvent 的精确序列属于待测试行为的一部分时,才使用 ModelStep.stream():
step = ModelStep.stream(
events,
output=[assistant_message("The terminal output used by the runner.")],
)
events 可以是固定序列,也可以是接收已记录 ModelCall 的异步工厂。可选的 output 是在非流式调用中使用同一步骤时返回的响应。精确流式事件是 SDK 标准化事件,而不是 Responses API 或 Chat Completions 的线上传输分块。
自动流式传输会拒绝尚未实现增量生命周期的标准化输出项种类。对于这些项,请使用 ModelStep.stream(...),而不是依赖不完整的事件序列。
模型故障的注入
使用 ModelStep.raise_error() 使一次模型调用失败。可选的重试建议仅适用于该特定脚本化错误:
from agents import ModelRetryAdvice
from agents.testing import ModelStep
step = ModelStep.raise_error(
RuntimeError("temporary failure"),
retry_advice=ModelRetryAdvice(suggested=True, replay_safety="safe"),
)
运行器的重试策略决定该建议是否会触发另一次尝试。每次重试都是一次新的模型调用,并会消耗下一个脚本化步骤。Python 辅助工具接受固定的 ModelRetryAdvice 值;当重试建议本身需要根据尝试次数动态变化时,请使用自定义 Model。
工作流偏移的检测
将脚本化调用视为预期的工作流结构。额外的模型请求会引发 UnexpectedModelCall;提前退出会留下步骤,供 assert_complete() 报告。
当测试框架支持 teardown 或 finalizer 时,如果还希望在其他断言失败后报告未消耗的步骤,请将 assert_complete() 放在其中。不要在常规回归测试中捕获不匹配错误。
| 错误 | 结构化字段 | 含义 |
|---|---|---|
InvalidModelStep |
reason、input_index |
步骤格式错误,并在进入队列前被拒绝 |
UnexpectedModelCall |
call、call_index |
脚本结束后,工作流又进行了一次模型调用 |
UnconsumedModelSteps |
remaining_steps |
工作流在使用完所有步骤前结束 |
沙箱智能体方案
沙箱智能体工作流的测试
将 ScriptedModel 与 scripted_sandbox_session() 结合使用,可在不创建本地容器或远程沙箱的情况下运行真实的 SandboxAgent 运行时。模型脚本选择一个能力工具,而沙箱脚本定义相应 SandboxSession 方法返回的内容。
import pytest
from agents import RunConfig, Runner
from agents.sandbox import ExecResult, SandboxAgent
from agents.sandbox.capabilities import Shell
from agents.testing import (
ScriptedModel,
assistant_message,
function_call,
scripted_sandbox_session,
)
@pytest.mark.asyncio
async def test_sandbox_workflow() -> None:
sandbox = scripted_sandbox_session(
[
{
"method": "exec",
"match": lambda call: call.args == ("pwd",),
"result": ExecResult(
stdout=b"/workspace\n",
stderr=b"",
exit_code=0,
),
}
]
)
model = ScriptedModel(
[
[function_call("exec_command", {"cmd": "pwd"}, call_id="call_1")],
[assistant_message("The workspace is /workspace.")],
]
)
agent = SandboxAgent(
name="Workspace assistant",
model=model,
capabilities=[Shell()],
)
async with sandbox:
result = await Runner.run(
agent,
"Which directory are you in?",
run_config=RunConfig(
sandbox={"session": sandbox},
tracing_disabled=True,
),
)
assert result.final_output == "The workspace is /workspace."
assert [call.method for call in sandbox.calls] == ["exec"]
sandbox.assert_complete()
model.assert_complete()
此测试会跨越两个标准化 SDK 边界。它涵盖工具参数验证、能力路由、沙箱会话调用、将工具结果传递至下一轮模型交互以及最终输出处理。它不会测试真实模型是否会选择该命令,也不会测试真实沙箱提供商如何执行该命令。
沙箱步骤的配置
每次匹配的沙箱调用都会消耗全局 FIFO 序列中的下一个步骤。方法不匹配、匹配器拒绝或匹配器异常都会让该步骤保持待处理状态。设置 method,只选择一种结果,并且仅在调用详情很重要时添加 match。
| 步骤成员 | 适用情形 |
|---|---|
result |
方法应返回固定的类型化值 |
responder |
结果取决于分离的 SandboxCall |
error |
方法应引发特定异常 |
match |
除非匹配器返回 False 以外的值,否则应在生成结果前拒绝该调用 |
支持的脚本化方法名称包括 apply_patch、exec、ls、mkdir、pty_exec_start、pty_write_stdin、read、rm 和 write。仅公开已配置且面向模型的能力。配置任一 PTY 方法时,这两个 PTY 方法都会一起公开,因为它们共同构成一项交互式 shell 能力,但调用仍会消耗全局 FIFO 脚本。
sandbox.calls 包含分离的 SandboxCall 快照,其中有从零开始的 call_index、method、位置参数 args 和只读 kwargs。静态结果也会在创建脚本时生成快照。支持 io.BytesIO 和 io.StringIO 值;对于其他实时流对象或生命周期行为,请使用自定义沙箱会话。
| 错误 | 结构化字段 | 含义 |
|---|---|---|
InvalidSandboxStep |
reason、input_index、method |
步骤格式错误或指定了不受支持的方法 |
UnexpectedSandboxCall |
call、call_index、actual_method、expected_method、remaining_steps |
工作流调用了错误的方法,或在脚本结束后继续运行 |
SandboxCallMatcherError |
call、call_index、method |
步骤匹配器返回了 False |
UnconsumedSandboxSteps |
remaining_steps、pending_methods |
工作流在使用完所有步骤前结束 |
返回的对象就是会话本身。请将其直接传递给 RunConfig(sandbox={"session": sandbox});不存在包装器 .session 属性。
实时方案
实时会话的测试
ScriptedRealtimeModel 实现了 Python SDK 的标准化 RealtimeModel 边界。每个 RealtimeStep 都会匹配一个出站 RealtimeModelSendEvent,随后发出标准化的入站 RealtimeModelEvent 对象或引发注入的错误。
import pytest
from agents.realtime import (
RealtimeAgent,
RealtimeModelOutputTextDeltaEvent,
RealtimeModelSendUserInput,
RealtimeRawModelEvent,
RealtimeRunner,
)
from agents.realtime.testing import RealtimeStep, ScriptedRealtimeModel
@pytest.mark.asyncio
async def test_realtime_message() -> None:
reply = RealtimeModelOutputTextDeltaEvent(
item_id="item_1",
delta="Hello!",
response_id="response_1",
)
model = ScriptedRealtimeModel(
[
RealtimeStep(
expect=RealtimeModelSendUserInput(user_input="Hello"),
emit=[reply],
)
]
)
runner = RealtimeRunner(
RealtimeAgent(name="Assistant"),
model=model,
config={"tracing_disabled": True},
)
observed_reply = False
async with await runner.run() as session:
await session.send_message("Hello")
async for event in session:
if isinstance(event, RealtimeRawModelEvent) and event.data == reply:
observed_reply = True
break
assert observed_reply
assert model.sent_events == (RealtimeModelSendUserInput(user_input="Hello"),)
assert model.closed is True
model.assert_complete()
预期值可以是精确事件值、通过 isinstance 匹配的事件类,或接收出站事件并在匹配时返回 True 的可调用对象。默认启用严格模式。使用 strict=False 时,无关的出站事件会被记录,但不会消耗待处理步骤;当会话发出与待测试行为无关的附带事件时,这种方式很有用。
使用 connect_events 在连接期间发出入站事件。使用 connect_error 或 close_error 注入生命周期故障,使用 RealtimeStep(error=...) 注入与某次已匹配发送相关的故障。一个步骤不能同时定义 emit 和 error。
实时工具工作流的测试
将真实函数工具附加到 RealtimeAgent,发出标准化工具调用,并预期 SDK 通过模型边界发送工具输出。将 async_tool_calls 设置为 False,可让这个小型示例在连接期间完成,而无须使用测试专用的等待机制。
import pytest
from agents.decorators import tool
from agents.realtime import (
RealtimeAgent,
RealtimeModelSendToolOutput,
RealtimeModelToolCallEvent,
RealtimeRunner,
)
from agents.realtime.testing import RealtimeStep, ScriptedRealtimeModel
@tool
def lookup_order(order_id: str) -> str:
"""Look up an order by ID."""
return f"Order {order_id} has shipped."
@pytest.mark.asyncio
async def test_realtime_tool_workflow() -> None:
tool_call = RealtimeModelToolCallEvent(
name="lookup_order",
call_id="call_1",
arguments='{"order_id":"order_123"}',
)
def matches_tool_output(event) -> bool:
return (
isinstance(event, RealtimeModelSendToolOutput)
and event.tool_call.call_id == "call_1"
and event.output == "Order order_123 has shipped."
)
model = ScriptedRealtimeModel(
[RealtimeStep(expect=matches_tool_output)],
connect_events=[tool_call],
)
agent = RealtimeAgent(
name="Order assistant",
tools=[lookup_order],
)
runner = RealtimeRunner(
agent,
model=model,
config={"async_tool_calls": False, "tracing_disabled": True},
)
async with await runner.run():
pass
model.assert_complete()
这会运行真实的实时工具查找、参数验证、执行和输出路由。它无法证明真实模型会选择该工具。
实时调用和生命周期的检查
| 成员 | 内容 |
|---|---|
connect_calls |
不含凭据的分离连接快照 |
sent_events |
按调用顺序排列的分离出站事件快照 |
remaining_steps |
尚未发生的预期出站发送 |
listeners |
当前已注册的监听器对象 |
connected、closed、close_calls |
当前内存中生命周期状态 |
连接历史记录只记录是否提供了 API 密钥或标头字段,绝不会存储它们的值。URL 快照会移除用户信息、查询参数和片段。可变事件数据和设置会被分离,而工具、任务转移和播放跟踪器等实时 SDK 对象会保留其标识。
最后调用 model.assert_complete(),并让 RealtimeSession 异步上下文管理器关闭模型。Python 工具特意不提供待处理的预期 Promise、隐式超时或单独的 assert_closed() 辅助工具。
| 错误 | 结构化字段 | 含义 |
|---|---|---|
UnexpectedRealtimeSend |
actual、expected |
严格出站发送与下一步骤不匹配,或已没有剩余步骤 |
UnconsumedRealtimeSteps |
remaining_steps |
会话在完成所有预期发送前结束 |
RealtimeScriptError |
无 | 脚本在无效的生命周期状态下使用,例如在断开连接时发送 |
语音管线方案
语音管线的测试
将脚本化 STT 和 TTS 模型、SingleAgentVoiceWorkflow 以及由 ScriptedModel 支持的智能体结合起来,可在不发出提供商请求的情况下测试完整的语音转文本 -> 智能体 -> 文本转语音管线。
import numpy as np
import pytest
from agents import Agent
from agents.testing import ScriptedModel, assistant_message
from agents.voice import AudioInput, SingleAgentVoiceWorkflow, VoicePipeline
from agents.voice.testing import (
ScriptedSTTModel,
ScriptedTTSModel,
TTSResult,
pcm16_samples,
)
@pytest.mark.asyncio
async def test_voice_pipeline() -> None:
model = ScriptedModel([[assistant_message("Hello there.")]])
stt = ScriptedSTTModel("hello")
pcm = pcm16_samples([0, 100, -100, 0])
tts = ScriptedTTSModel([TTSResult([pcm])])
pipeline = VoicePipeline(
workflow=SingleAgentVoiceWorkflow(Agent(name="Voice assistant", model=model)),
stt_model=stt,
tts_model=tts,
config={"tracing_disabled": True, "tts_settings": {"buffer_size": 1}},
)
result = await pipeline.run(AudioInput(np.zeros(2, dtype=np.int16)))
events = [event async for event in result.stream()]
assert events
assert [call.text for call in tts.calls] == ["Hello there."]
stt.assert_complete()
tts.assert_complete()
model.assert_complete()
当测试目标是管线的 STT/TTS 生命周期而非智能体编排时,请改用 ScriptedVoiceWorkflow:
from agents.voice.testing import ScriptedVoiceWorkflow
workflow = ScriptedVoiceWorkflow(
turns=["Hello there."],
start="Welcome.",
)
start 步骤由 on_start() 消耗。仅当使用 StreamedAudioInput 时,VoicePipeline 才会调用 on_start();静态 AudioInput 运行不会消耗 start。每个常规轮次都会记录其转录文本,并消耗一个已配置的结果。一个字符串对应一个片段;字符串序列可在文本分割和 TTS 前控制片段边界。
流式转录的测试
ScriptedSTTModel 接受静态 transcriptions 和独立编写脚本的流式 sessions。会话可以是 ScriptedTranscriptionSession、转录轮次序列、异常或单个字符串:
from agents.voice.testing import ScriptedSTTModel, ScriptedTranscriptionSession
session = ScriptedTranscriptionSession(["first turn", "second turn"])
stt = ScriptedSTTModel(sessions=[session])
关闭 ScriptedTranscriptionSession 会停止迭代,并保留被跳过的轮次,供 assert_complete() 报告。类似地,ScriptedTTSModel 每次调用都会消耗一个 TTSResult、字节块序列或异常。
语音调用的检查
| 组件 | 记录的历史 |
|---|---|
ScriptedSTTModel |
calls、session_calls 和实时 created_sessions 标识 |
ScriptedTTSModel |
包含文本和分离设置的 calls |
ScriptedVoiceWorkflow |
按轮次顺序排列的 transcriptions |
静态音频缓冲区和可变设置会在调用时生成快照。StreamedAudioInput 和创建的转录会话对象会保留其实时标识,因为管线仍会继续使用它们。
| 错误 | 结构化字段 | 含义 |
|---|---|---|
UnexpectedVoiceCall |
operation |
静态转录、流式会话、TTS 调用、工作流启动或工作流轮次没有已配置的步骤 |
UnconsumedVoiceSteps |
remaining_steps |
仍有一个或多个已配置的语音步骤 |
对测试配置的每个脚本化语音组件调用 assert_complete()。ScriptedSTTModel.assert_complete() 还会检查其创建的转录会话中的轮次。
正确边界的选择
当测试应运行 SDK 运行循环、工具、任务转移、安全防护措施、会话、重试或标准化流式传输,而不依赖模型提供商时,请使用 ScriptedModel。
当测试应运行 SandboxAgent 功能和编排,而不启动沙箱提供商时,请将 scripted_sandbox_session() 与 ScriptedModel 配合使用。对于提供商创建、进程执行、文件系统保真度、持久化、资源限制和隔离检查,请保留针对真实沙箱提供商的集成测试。
当测试应运行 RealtimeSession 行为或 RealtimeAgent 工具和任务转移编排,而不建立 WebSocket 连接时,请使用 ScriptedRealtimeModel。原始实时客户端/服务器事件、身份验证、网络恢复和音频传输行为应在真实传输层或集成环境中测试。Realtime API 会话会在客户端发送输入并接收事件期间保持连接打开,因此这些网络和协议问题属于标准化模型边界之下。有关生产连接架构,请参阅 OpenAI Realtime API 指南。
当测试应运行 STT/TTS 排序、流式转录清理、工作流片段交付或完整的语音管线组合,而不依赖语音提供商时,请使用语音测试组件。当测试对象是转录质量、生成语音、编码兼容性、延迟或播放时,请使用真实音频模型和具有代表性的音频。
不要使用这些工具测试 Responses API 或 Chat Completions 的请求序列化、身份验证标头、提供商默认值、HTTP 载荷、提供商流分块、实时线上传输帧或提供商特定的生命周期行为。对于这些测试,请保留真实适配器,并替换或控制其网络边界。使用 openai v3 时,OpenAI 适配器测试应使用 httpx2 的请求、响应、传输和异常类型;旧版 httpx 不是 Agents SDK 的核心依赖项。
最终检查清单
- 仅为标准化模型、沙箱会话、实时模型或语音管线边界所管理的交互编写脚本。
- 断言重要的公共请求或调用字段,而不是运行器的私有状态。
- 优先使用固定响应步骤;仅对依赖请求的行为使用响应器。
- 优先使用自动模型流式传输;仅当事件级行为很重要时才使用精确流。
- 在每个脚本化组件测试结束时调用其
assert_complete()方法。 - 当外围测试管理相应生命周期时,请使用异步上下文管理器清理实时和沙箱生命周期。
- 断言结构化错误字段,而不是解析可读消息。
- 使用具有受控网络传输的真实适配器执行提供商线上传输测试。
范围与当前限制
测试模块特意不提供:
- 每种标准化模型输出项的便捷构建器。常见情况请使用
assistant_message()和function_call(),其他标准化项则直接传入。 - 提供商协议模拟器。精确模型流使用标准化 SDK 事件,而不是 Responses API 或 Chat Completions 的线上传输分块。
- 高层级的模拟实时服务器。测试会显式匹配标准化出站发送,并发出场景所需的标准化入站事件。
- 无序沙箱或实时预期。这两个工具都会按一个全局顺序消耗预期步骤。
- 测试运行器特定的匹配器、fixture、隐式超时或自动 teardown。
- 重置 API。
ScriptedModel支持使用enqueue()和extend()构建增量脚本,但对于独立场景,请创建新的脚本化组件。
当测试需要格式错误的流、受控暂停或并发、精确取消,或脚本化工具无法保留的生命周期边界时,请自定义实现相应的公共接口,并在测试中记录该专用边界。