OpenAI Agents SDK #32：RunConfig 完整拆解——20+ 字段五大功能域，一次性掌握全局运行配置

一、怎么用 RunConfig

from agents import Agent, RunConfig, Runner

result = await Runner.run(
    agent,
    "请执行任务",
    run_config=RunConfig(
        workflow_name="my-workflow",
        tracing_disabled=False,
    )
)

二、工具执行控制

ToolExecutionConfig：并发限流

from agents import Agent, RunConfig, Runner, ToolExecutionConfig

result = await Runner.run(
    agent,
    "同时调用多个工具",
    run_config=RunConfig(
        tool_execution=ToolExecutionConfig(max_function_tool_concurrency=2),
    ),
)

tool_error_formatter：改写拒绝消息

from agents import RunConfig, ToolErrorFormatterArgs

def format_rejection(args: ToolErrorFormatterArgs[None]) -> str | None:
    if args.kind == "approval_rejected":
        return (
            f"工具调用 '{args.tool_name}' 被人工拒绝。"
            "请提出一个更安全的替代方案，或请求澄清。"
        )
    return None  # 返回 None 用 SDK 默认消息

result = Runner.run_sync(
    agent,
    "请删除生产数据库",
    run_config=RunConfig(tool_error_formatter=format_rejection),
)

三、模型调用前拦截

call_model_input_filter：最后一道关卡

from agents import Agent, RunConfig, Runner
from agents.run import CallModelData, ModelInputData

def drop_old_messages(data: CallModelData[None]) -> ModelInputData:
    # 只保留最近 5 条输入，防止 context 过长
    trimmed = data.model_data.input[-5:]
    return ModelInputData(input=trimmed, instructions=data.model_data.instructions)

result = Runner.run_sync(
    agent,
    "解释一下递归",
    run_config=RunConfig(call_model_input_filter=drop_old_messages),
)

• input：list[TResponseInputItem]，必填，发给模型的输入列表
• instructions：str | None，可选，System prompt 内容

1. 如果用了 Session，call_model_input_filter 在 Session 历史已经加载并合并之后运行——你拿到的已经是完整的「历史 + 当前输入」列表
2. 如果用了服务端会话（conversation_id / previous_response_id），filter 收到的是下一次 Responses API 请求的 payload，可能只是增量 delta，不是完整历史回放
3. Runner 把输入列表的副本传给 filter，直接修改不会影响调用方原始列表

session_input_callback：更早的会话合并拦截

四、错误处理器

error_handlers：让 MaxTurns 不再抛异常

from agents import (
    Agent,
    RunErrorHandlerInput,
    RunErrorHandlerResult,
    Runner,
)

def on_max_turns(data: RunErrorHandlerInput[None]) -> RunErrorHandlerResult:
    return RunErrorHandlerResult(
        final_output="我在轮数限制内没能完成，请缩小请求范围。",
        include_in_history=False,  # 这条降级输出不追加到对话历史
    )

result = Runner.run_sync(
    agent,
    "分析这份超长文档",
    max_turns=3,
    error_handlers={"max_turns": on_max_turns},
)
print(result.final_output)

from pydantic import BaseModel
from agents import Agent, ModelRefusalError, RunErrorHandlerInput, Runner

class Recipe(BaseModel):
    ingredients: list[str]
    refusal_reason: str | None = None

def on_model_refusal(data: RunErrorHandlerInput[None]) -> Recipe:
    assert isinstance(data.error, ModelRefusalError)
    return Recipe(ingredients=[], refusal_reason=data.error.refusal)

agent = Agent(
    name="Recipe assistant",
    instructions="返回一份结构化菜谱。",
    output_type=Recipe,
)
result = Runner.run_sync(
    agent,
    "做一道危险的东西。",
    error_handlers={"model_refusal": on_model_refusal},
)
# 不抛异常，拿到 Recipe(ingredients=[], refusal_reason="...")

五、推理项 ID 策略

reasoning_item_id_policy：o 系列模型的 400 错误克星

Item 'rs_...' of type 'reasoning' was provided without its required following item.

result = await Runner.run(
    agent,
    "一个需要推理的复杂问题",
    run_config=RunConfig(reasoning_item_id_policy="omit"),
)

六、字段全览

模型与 Provider（5 字段）

Guardrails 与 Handoff（4 字段）

可观测性（6 字段）

七、实战配置模板

run_config = RunConfig(
    workflow_name="customer-support-v2",
    group_id=session_id,              # 把同一用户会话的多次 run 串成一组 trace
    tool_execution=ToolExecutionConfig(
        max_function_tool_concurrency=3,  # 限制第三方 API 并发
    ),
    call_model_input_filter=trim_history_to_budget,  # 按 token 预算裁剪历史
    error_handlers={
        "max_turns": graceful_max_turns_fallback,    # 优雅降级
        "model_refusal": structured_refusal_handler, # 结构化拒绝消息
    },
    reasoning_item_id_policy="omit",  # 如果用 o 系列模型，防 400 错误
)

run_config = RunConfig(
    workflow_name="debug-session",
    trace_include_sensitive_data=False,  # 不把 LLM 输入输出写进 trace
    tracing_disabled=False,              # trace 仍然开着，只是不带敏感内容
)

落地建议

1. workflow_name 必填。生产里跑了几十个不同 Agent 流，如果全都是默认的 "Agent workflow"，trace 面板里根本没法区分。一行代码，trace 可读性直接上一个档次。
2. 限制 tool 并发之前先量化。max_function_tool_concurrency 设多少要结合你调用的 API 的速率限制来算，不是越低越好——限太死会把并行化优势全部消掉。先跑压测，看第三方服务的 429 频率，再决定值。
3. reasoning_item_id_policy="omit" 是 o 系列模型的标配。只要你的 Agent 会跑多轮（有 handoff / session / 历史管理），就默认加上，能省掉很多奇怪的 400 排查时间。它只影响 SDK 自动构建的 follow-up input，副作用极低。
4. call_model_input_filter 不要替代 Session 机制。它适合做最后一道 token 预算卡关，或在调用前注入动态系统上下文。如果你想管的是「历史怎么存怎么取」，那是 Session + session_input_callback 的活。