教程8：追踪与可观测性

文档摘要

教程 8：追踪与可观测性掌握内置追踪功能，轻松实现监控与调试！本教程将教你如何使用 OpenAI Agents SDK 的全面追踪系统，在开发和生产环境中可视化、调试并监控你的智能体工作流。你将学到的内容内置追踪：自动捕获大语言模型生成、工具调用及交接过程追踪与跨度：理解工作流结构与执行流程自定义追踪：为复杂工作流创建自定义追踪与跨度生产环境监控：调试与性能优化核心概念：什么是追踪？追踪提供全面的工作流监控，可自动捕获智能体执行过程中的每个事件：大语言模型生成：模型调用、输入、输出及性能工具调用：函数执行、参数与结果交接：智能体之间的委托与上下文传递防护措施：输入/输出验证事件自定义事件：你自己的监控点教程概览本教程将演示三种关键追踪模式： 1.

教程 8：追踪与可观测性

掌握内置追踪功能，轻松实现监控与调试！本教程将教你如何使用 OpenAI Agents SDK 的全面追踪系统，在开发和生产环境中可视化、调试并监控你的智能体工作流。

你将学到的内容

内置追踪：自动捕获大语言模型生成、工具调用及交接过程
追踪与跨度：理解工作流结构与执行流程
自定义追踪：为复杂工作流创建自定义追踪与跨度
生产环境监控：调试与性能优化

核心概念：什么是追踪？

追踪提供全面的工作流监控，可自动捕获智能体执行过程中的每个事件：

大语言模型生成：模型调用、输入、输出及性能
工具调用：函数执行、参数与结果
交接：智能体之间的委托与上下文传递
防护措施：输入/输出验证事件
自定义事件：你自己的监控点


┌─────────────────────────────────────────────────────────────┐
│                    TRACING ARCHITECTURE                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  AGENT WORKFLOW                                             │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    AUTOMATIC CAPTURE                       │
│  │    TRACE    │◀─────────────────────────────────────────┐ │
│  │ (Workflow)  │                                          │ │
│  └─────────────┘                                          │ │
│       │                                                   │ │
│       ▼                                                   │ │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │ │
│  │    SPAN     │    │    SPAN     │    │    SPAN     │    │ │
│  │ (LLM Call)  │    │ (Tool Call) │    │ (Handoff)   │    │ │
│  └─────────────┘    └─────────────┘    └─────────────┘    │ │
│       │                    │                    │         │ │
│       ▼                    ▼                    ▼         │ │
│  ┌─────────────────────────────────────────────────────┐  │ │
│  │         OPENAI TRACES DASHBOARD                     │  │ │
│  │    • Execution Visualization                        │  │ │
│  │    • Performance Metrics                            │__| │ 
│  │    • Debug Information                              │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

教程概览

本教程将演示三种关键追踪模式：

1. 默认追踪（`default_tracing.py`)

Built-in automatic tracing (enabled by default)
Understanding traces and spans structure
Basic workflow monitoring

2. Custom Tracing (`custom_tracing.py`)

Creating custom traces for multi-step workflows
Adding custom spans for monitoring points
Grouping multiple agent runs in single trace

3. Advanced Observability (`advanced_observability.py`）

敏感数据处理与配置
针对外部系统的自定义追踪处理器
生产环境监控模式

项目结构


8_tracing_observability/
├── README.md                    # This file - concept explanation
├── requirements.txt             # Dependencies  
├── default_tracing.py           # Built-in tracing basics (35 lines)
├── custom_tracing.py            # Custom traces and spans (45 lines)
├── advanced_observability.py    # Production tracing patterns (40 lines)
├── app.py                      # Streamlit tracing dashboard (optional)
└── env.example                 # Environment variables template

学习目标

完成本教程后，你将掌握：

✅ 内置追踪如何捕获智能体工作流事件
✅ 追踪（工作流）与跨度（操作）的区别
✅ 为复杂多步骤工作流创建自定义追踪
✅ 在生产环境中监控与调试智能体性能
✅ 与外部可观测性系统集成

开始使用

安装 OpenAI Agents SDK：
```
pip install openai-agents
```
安装依赖：
```
pip install -r requirements.txt
```

设置环境变量：


cp env.example .env
# Edit .env and add your OpenAI API key

测试默认追踪：
```
python default_tracing.py
```
尝试自定义追踪：
```
python custom_tracing.py
```
探索高级模式：
```
python advanced_observability.py
```

示例用例

默认追踪

自动监控基本智能体工作流
调试工具调用失败与大语言模型生成问题
跟踪性能指标以进行优化

自定义追踪

将相关智能体运行分组到复杂工作流中
在业务逻辑中添加自定义监控点
创建层次化的跨度结构以方便调试

高级可观测性

配置敏感数据处理以满足合规要求
将追踪导出到外部监控系统
设置生产环境告警与仪表板

关键追踪模式

1. 默认追踪（自动）


from agents import Agent, Runner

agent = Agent(name="Assistant")
# Tracing happens automatically - no setup required!
result = await Runner.run(agent, "Hello")
# View traces at: https://platform.openai.com/traces

2. 自定义追踪创建


from agents import Agent, Runner, trace

with trace("Multi-step Workflow") as my_trace:
    result1 = await Runner.run(agent, "Step 1")
    result2 = await Runner.run(agent, "Step 2")
    # Both runs are part of the same trace

3. 自定义跨度


from agents import custom_span

with custom_span("Data Processing") as span:
    # Your custom logic here
    data = process_data()
    span.add_event("Processing complete", {"records": len(data)})

追踪设计最佳实践

有意义的名称：使用描述性的追踪与跨度名称
逻辑分组：将相关操作分组到单一追踪中
自定义事件：将关键业务事件作为自定义跨度添加
敏感数据：配置数据处理以满足合规要求
性能监控：跟踪执行时间和资源使用情况

重要提示

默认启用：追踪功能已自动启用
零数据保留：对于 ZDR 政策组织，追踪功能不可用
免费仪表板：在 OpenAI 追踪仪表板查看追踪记录
按需禁用：设置 OPENAI_AGENTS_DISABLE_TRACING=1 可禁用追踪

下一步

完成本教程后，你将准备好：

教程 9：交接与委托 - 智能体交接与任务委托
教程 10：多智能体编排 - 复杂多智能体工作流
教程 11：生产环境模式 - 实际部署策略

故障排除

无追踪可见：检查 OpenAI API 密钥与网络连接
缺失跨度：确保操作处于追踪上下文中
性能问题：配置敏感数据过滤
ZDR 政策：追踪功能不可用——禁用或使用自定义处理器

专业小贴士

从简单开始：先使用默认追踪，根据需要再添加自定义追踪
战略性命名：为追踪与跨度使用一致的命名规范
监控性能：跟踪执行时间随时间的变化趋势
外部集成：考虑为你的监控栈使用自定义处理器
开发与生产环境：针对不同环境采用不同的追踪策略

免责声明：
本文档采用基于机器的 AI 翻译服务进行翻译。尽管我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。应以原文语言版本的文档作为权威依据。如需获取关键信息，建议使用专业的人工翻译。对于因使用本翻译而产生的任何误解或误读，我们概不负责。