追踪与可观测性

内置追踪系统

OpenAI Agents SDK 的每次 Runner.run() 都会自动记录完整的执行轨迹，无需任何额外配置：

from agents import Agent, Runner, RunConfig
import asyncio

agent = Agent(
    name="追踪演示",
    instructions="回答用户的问题。",
    model="gpt-4o-mini"
)

async def main():
    result = await Runner.run(
        agent,
        "Python 的 GIL 是什么？",
        run_config=RunConfig(
            # 追踪相关配置
            workflow_name="问答工作流",      # 在 Traces UI 中的名称
            trace_id="custom-trace-001",    # 自定义 trace ID（可用于关联）
            group_id="session-abc123",        # 关联同一会话的多次 Run
            tracing_disabled=False,           # 默认开启
            trace_include_sensitive_data=True, # 是否在追踪中包含消息内容
        )
    )
    print(result.final_output)

asyncio.run(main())

自定义 Span：追踪业务逻辑

除了自动记录的 SDK 事件，你可以用 custom_span 追踪自己的业务代码：

from agents.tracing import custom_span, agent_span, trace
import asyncio

async def process_research_request(topic: str, agent):
    # trace() 为整个工作流创建顶层追踪
    with trace("研究请求处理", trace_id=f"research-{topic[:20]}"):

        # custom_span 追踪数据预处理步骤
        with custom_span("数据预处理"):
            clean_topic = topic.strip().lower()
            cached = await check_cache(clean_topic)
            if cached:
                return cached

        # Agent 运行（自动产生 span）
        result = await Runner.run(agent, f"研究主题：{clean_topic}")

        # custom_span 追踪后处理步骤
        with custom_span("结果格式化"):
            formatted = await format_report(result.final_output)
            await save_to_cache(clean_topic, formatted)

        return formatted

# 追踪结果在 OpenAI Traces UI 中呈现为：
# 研究请求处理
# ├── 数据预处理 (Span)
# ├── Agent: 研究助手 (Span)
# │   ├── LLM 调用 1 (Span)
# │   ├── Tool: search_web (Span)
# │   └── LLM 调用 2 (Span)
# └── 结果格式化 (Span)

敏感数据保护

在某些场景下（医疗、金融、法律），消息内容属于敏感数据，不应该上传到第三方追踪服务：

from agents import Runner, RunConfig

# ── 方式 1：全局关闭敏感数据记录 ─────────────────────────
result = await Runner.run(
    agent,
    user_input,
    run_config=RunConfig(
        # False = 追踪中只记录结构（调用了哪些工具），不记录具体内容
        trace_include_sensitive_data=False
    )
)

# ── 方式 2：完全关闭追踪（高隐私场景）───────────────────
result = await Runner.run(
    agent,
    user_input,
    run_config=RunConfig(
        tracing_disabled=True  # 不上传任何追踪数据
    )
)

# ── 方式 3：全局设置（影响所有 Run）──────────────────────
from agents.tracing import set_tracing_disabled, set_trace_include_sensitive_data

set_tracing_disabled(True)              # 关闭所有追踪
set_trace_include_sensitive_data(False)  # 全局不记录敏感内容

第三方集成：LangSmith

# 安装：pip install langsmith
# 环境变量：LANGCHAIN_TRACING_V2=true, LANGCHAIN_API_KEY=ls__...
import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "ls__your_key"
os.environ["LANGCHAIN_PROJECT"] = "openai-agents-demo"

from agents.tracing.processors import LangSmithSpanExporter
from agents.tracing import add_trace_processor

# 注册 LangSmith 导出器
add_trace_processor(LangSmithSpanExporter())

# 之后所有的 Runner.run() 都会自动上报到 LangSmith
result = await Runner.run(agent, "测试问题")
# 在 smith.langchain.com 的 Project 页面查看追踪数据

生产监控：关键指标

在生产环境中，需要追踪以下核心指标来评估 Agent 的运行状况：

# 自定义监控：记录每次 Run 的关键指标
import time
from agents import Runner
from agents.exceptions import MaxTurnsExceeded, InputGuardrailTripwireTriggered

async def monitored_run(agent, user_input: str, metrics_client=None):
    start_time = time.time()
    status = "success"

    try:
        result = await Runner.run(agent, user_input)
        turn_count = len([
            item for item in result.new_items
            if item.type == "message_output_item"
        ])
        return result

    except MaxTurnsExceeded:
        status = "max_turns_exceeded"
        raise
    except InputGuardrailTripwireTriggered:
        status = "guardrail_blocked"
        raise
    finally:
        latency = time.time() - start_time
        if metrics_client:
            metrics_client.record({
                "agent": agent.name,
                "latency_s": latency,
                "status": status,
            })