The Practitioner’s Guide to AgentOps

AgentOps 实践者指南 - MachineLearningMastery.com

AgentOps 实践者指南

作者：

Shittu Olumide

于

2026年6月9日

在

人工智能

0

分享

文章

在本文中，你将了解什么是 AgentOps，它与传统的 LLM 监控有何不同，以及如何为自主 AI 代理构建一个生产就绪的可观测性堆栈。

我们将涵盖的主题包括：

• AgentOps 的五个核心支柱，以及为什么标准日志记录对于自主代理是不够的。

• 如何使用 AgentOps 平台为研究代理添加完整的会话跟踪、成本归因和失败检测。

• 如何使用会话回放调试常见的代理失败模式，以及如何在操作层面上治理成本并确保安全性。

AgentOps 实践者指南 图片由作者提供

引言

根据 Futurum Research 2025 年对代理 AI 平台的市场概述，89% 的 CIO 现在将基于代理的 AI 视为提高生产力和工作流程自动化的首要战略优先事项。然而，2026 年大多数部署代理的团队都没有系统的方法来理解代理为何失败、每会话的成本是多少，或者它们是否在设计的范围内运行。当出现问题时，调查通常从堆栈跟踪开始，以某人逐行阅读日志，试图重建代理出错时的思考过程而结束。

这就是 AgentOps 所填补的空白。AgentOps 是用于设计、部署、监控、优化和管理生产环境中自主 AI 代理的一套实践、工具和框架。它将 DevOps、MLOps 和 LLMOps 扩展到一个软件组件可以独立推理、行动和适应的领域，这意味着操作挑战在性质上是不同的，而不仅仅是更多相同的问题。本指南涵盖了 AgentOps 实际上是什么，它与常规 LLM 监控的不同之处，包括完整的工具生态系统和一个完整的工作代码示例，如何使用会话回放调试代理失败，保持代理在生产中可持续运行的成本和安全模式，以及构建你自己的堆栈的决策框架。

什么是 AgentOps？

最简单的定义：AgentOps 是自主代理的操作骨干。它确保代理的行为在每一步都具有可解释性、可衡量性，并与业务和合规目标保持一致，而不仅仅是在最终输出时。

正如 DevOps 统一了开发和运维，MLOps 标准化了机器学习模型的部署，AgentOps 将同样的操作严谨性带入了智能自主领域。这一学科建立在三个关于为什么传统监控对代理不起作用的观察之上。

• 失败在步骤之间累积：一个普通的 API 监控工具会告诉你调用失败了。但它无法告诉你第 7 步的失败是由第 3 步中设置的不良工具参数引起的，而第 3 步的不良参数又是由第 1 步中提取的模糊上下文引起的。代理失败出现在多步骤的因果链中，而不是在单个调用级别上。如果你无法捕获并回放完整的链，你就无法诊断任何有意义的问题。

• 输出是轨迹，而非响应：在标准的大型语言模型（LLM）应用中，输出是对提示的响应。你可以对它进行评分、判断，并将其作为一个数据点进行记录。而对于代理（agent）来说，输出是一系列决策：调用哪个工具、按什么顺序、使用什么参数，以及如何在每一步解释结果。评估轨迹与评估响应是不同的问题，它需要不同的基础设施。

• 成本设计上是无上限的：静态的LLM调用具有可预测的令牌数量。一个在复杂任务上循环的代理——调用搜索工具、重新阅读上下文、修改其计划——可能在任何人看到结果之前就消耗数千个令牌。没有会话级别的成本可见性，预算管理只能是猜测。

AgentOps 的五大支柱

每个成熟的 AgentOps 实现都依赖于五个操作能力。它们不是可选的附加功能；它们是代理能够在任何有意义的规模上自主运行的条件。

• 可观测性：从代理初始化到任务完成，对整个会话中的每一步、每个工具调用、每个推理决策、每个输入、每个输出和每个错误进行完整追踪。这不是单个调用的日志记录，而是完整的会话捕获。AgentOps 的基石是可观测性——使自主代理的行为完全透明的能力。与传统日志记录捕获孤立事件不同，可观测性追踪代理如何处理输入、调用工具，并在整个工作流程中演变其理解。

• 评估：对代理轨迹进行评分，评估其质量、目标达成情况、工具使用正确性以及对约束的遵守情况。这与对单个响应进行评分不同，它需要评估决策序列是否合理，而不仅仅是最终答案是否看起来合理。

• 成本治理：令牌级别的可见性、会话级别的成本归属、预算限制和循环检测。哪种类型的代理成本最高？哪些工具调用被不必要的重复使用？会话类型之间的成本分布如何？这些问题需要会话级别的汇总，而不是按调用记录。

• 安全与防护：提示注入检测、在下游系统接收结果之前进行输出验证、限制代理可以调用的工具的范围约束，以及对高风险决策的人工干预检查点。安全性不是在最后添加的功能；它从一开始就设计到操作层中。

• 持续改进：利用生产轨迹识别模式、改进提示、重新设计工具并发现回归问题。从生产环境反馈到开发环境的反馈循环是区分随时间变好的代理和悄无声息退化的代理的关键。

AgentOps 的五大支柱（点击放大）

AgentOps 工具生态系统

当从业者提到“AgentOps”时，他们可能指的是上述描述的学科，或者 agentops.ai 上的具体平台。两者都值得理解。

AgentOps 平台

AgentOps 是一个专为 AI 代理设计的专用可观测性平台。它不是一个为代理适配的一般 LLM 监控工具；它是从零开始为多步骤、使用工具、自主系统构建的。其核心能力：

• 带有时间旅行调试的会话回放：每次代理运行都会被记录为可回放的会话。您可以回退到执行过程中的任意一点，检查该步骤的确切状态，并继续查看后续影响。这是在不本地重现失败的情况下诊断生产环境中失败的主要工具。

• 可视化事件追踪：LLM 调用、工具调用和多代理交互以图的形式进行可视化，而不是以扁平日志的形式。您可以一目了然地看到会话的结构 —— 哪些工具按什么顺序被调用，代理在何处分支，何处循环。

• 全面的成本追踪：AgentOps 监控、保存并追踪您的 AI 代理处理的每一个 token。会话级别的支出与每个调用的指标一起可见，成本被归因于特定的工具调用和决策点，而不是报告为整个会话的总成本。

• 安全与合规：AgentOps 从开发到生产阶段维护完整的日志、错误和检测到的提示注入攻击的数据轨迹。此审计轨迹是任何受监管或企业级部署的最低要求。

• 框架集成：该平台与超过 400 个 AI 框架集成，包括 CrewAI、OpenAI Agents SDK、LangChain、AutoGen、AG2、Agno 和 CamelAI。大多数集成只需要两行代码。

在部署之前，有一个实用的注意事项值得了解：与没有监控的基线相比，AgentOps 在多步骤工作流中会引入显著的开销。这是为了获得可观测性所做出的合理权衡，但在生产部署之前，最好根据您的延迟要求进行基准测试。

更广泛的生态系统

AgentOps 并不是这个领域中唯一的平台，对于某些团队来说，它可能不是最佳选择。以下是主要选项的分布情况：

| 平台 | 最强之处 | 最佳适配团队 | |--------------|--------------------------------------|------------------------------------------| | AgentOps | 多框架代理调试，会话回放 | 跨多个代理框架构建的团队 | | LangSmith | LangChain 和 LangGraph 集成深度 | 完全致力于 LangChain 栈的团队 | | Langfuse | 自托管、MIT 许可、数据主权 | 需要本地或开源的团队 | | Arize Phoenix| ML 级别的严谨性，RAG 评估 | 拥有现有 ML 监控基础设施的企业 | | Braintrust | CI/CD 评估门控部署，慷慨的免费层级 | 每月免费 100 万跨度的评估驱动开发 | | Galileo | 低延迟下的 100% 生产流量评估 | 高流量、质量关键的生产部署 |

从比较研究中得出的最清晰的决策规则是：LangSmith 最适合 LangChain/LangGraph 栈，而 AgentOps 是多框架代理调试的最强选项。其余一切则取决于次要需求：数据主权、评估工作流程、CI/CD 集成和团队规模。

AgentOps 捕获而常规日志遗漏的内容

理解标准日志无法告诉你的内容，是理解专用代理可观测性为何重要的最快方式。

• 多步骤因果链：一个普通的日志器会告诉你第 7 步返回了错误。AgentOps 会告诉你第 7 步的错误是由于第 3 步传递了一个格式错误的参数，而第 3 步的错误是因为第 1 步的上下文提取返回了模糊的实体。因果链才是真正的失败原因，而在每个调用的日志中它是不可见的。会话回放使其变得可导航。

• 工具调用模式和异常：在多个会话中，哪些工具被最频繁调用？哪些工具在没有引发异常的情况下静默失败？是否存在某些工具调用序列会持续地在不良输出之前发生？跨会话的模式数据使你能够有效地重新设计工具和提示。你无法从单个调用日志中推导出这些信息 —— 你需要跨多次运行的会话聚合数据。

• 会话级别的成本归因：单个 API 调用可能花费 \$0.003。一个在复杂研究任务上循环的代理会话可能花费 \$4.70。这种差异在按调用监控中是不可见的。AgentOps 将成本归因于特定的工具调用和决策序列，这样你可以精确地看到代理工作流程中哪些部分导致了成本，并进行精确优化，而不是猜测。

实践中的监控

这个示例构建了一个研究代理，它接受一个主题，使用工具调用来收集信息，并返回结构化的摘要。从第一行开始，每一步都使用 AgentOps 进行了监控。该示例旨在展示完整的监控模式：会话初始化、工具装饰、自定义操作记录、错误处理和会话结束。

让我们安装所需的依赖项：

pip install agentops anthropic python-dotenv

1

pip

install

anthropic

python

-

dotenv

你需要：

• 一个 AgentOps API 密钥，免费开始使用，可在你的账户设置中找到

• 一个 Anthropic API 密钥

• 项目根目录下的 .env 文件

环境设置

.env 文件 -- 在你的项目文件夹中创建此文件 AGENTOPS_API_KEY=your_agentops_key_here ANTHROPIC_API_KEY=sk-ant-your_key_here

2

3

.env 文件 -- 在你的项目文件夹中创建此文件

AGENTOPS_API_KEY

=

your_agentops_key_here

ANTHROPIC_API_KEY

sk

ant

your_key_here

完整的工作代理

research_agent.py

目的：一个带有完整 AgentOps 指标记录的研究代理。

每个会话都会在 AgentOps 仪表板中被记录、重放并跟踪成本。

先决条件：

pip install agentops anthropic python-dotenv

所需的环境变量（在 .env 文件中）：

AGENTOPS_API_KEY -- 来自 https://app.agentops.ai

ANTHROPIC_API_KEY -- 来自 https://console.anthropic.com

如何运行：

python research_agent.py

import os import json import time from dotenv import load_dotenv import anthropic import agentops from agentops.sdk.decorators import record_function

load_dotenv()

── 初始化 AgentOps ────────────────────────────────────────────────────────

在任何代理代码运行之前必须调用。

标签允许你在仪表板中过滤和分组会话。

SDK 在初始化后会自动拦截 LLM 调用。

agentops.init( api_key=os.environ["AGENTOPS_API_KEY"], tags=["research-agent", "production", "v1.0"], auto_start_session=True # 初始化时自动开始会话 )

在 AgentOps 之后初始化 Anthropic 客户端 -- SDK 会包装 LLM 客户端

以自动捕获每次调用的输入、输出、令牌和成本。

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"]) MODEL = "claude-sonnet-4-20250514"

── 系统提示 ─────────────────────────────────────────────────────────────

存储为常量，而不是内联 -- 可以控制版本并进行测试。

SYSTEM_PROMPT = """ 你是一个研究助理。当给定一个主题时：

1. 使用可用工具系统地收集信息
2. 调用 search_topic 以获取主题概述
3. 调用 get_key_facts 以提取最重要的要点
4. 调用 format_summary 以结构化最终输出

全面但简洁。始终在最后一步调用 format_summary。 """

── 工具定义 ──────────────────────────────────────────────────────────

这些是代理可以调用的工具。在实际系统中，search_topic 会调用真正的搜索 API（Tavily、SerpAPI 等）。

在这里它们是返回现实数据的存根，以便你可以在不使用外部 API 的情况下运行示例。

TOOLS = [ { "name": "search_topic", "description": ( "搜索有关主题的综合信息。" "返回包含关键主题和背景的概述。" "将此作为任何研究任务的第一步。" ), "input_schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "要研究的主题。请具体。" }, "depth": { "type": "string", "enum": ["overview", "detailed"], "description": "搜索的深度。首先使用 'overview'。" } }, "required": ["topic"] } }, { "name": "get_key_facts", "description": ( "从搜索结果中提取有关主题的最重要事实。" "在 search_topic 之后使用，以识别 5-7 个最重要的点。" ), "input_schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "要提取事实的主题" }, "focus": { "type": "string", "description": "可选：要关注的特定角度（例如，'最新进展'、'主要参与者'）" } }, "required": ["topic"] } }, { "name": "format_summary", "description": ( "将研究结果格式化为清晰的结构化摘要。" "始终在返回给用户之前调用此工具。" ), "input_schema": { "type": "object", "properties": { "title": { "type": "string", "description": "摘要的标题" }, "key_points": { "type": "array", "items": {"type": "string"}, "description": "关键发现列表（5-7 个条目）" }, "conclusion": { "type": "string", "description": "研究的 2-3 句综合总结" } }, "required": ["title", "key_points", "conclusion"] } } ]

── 工具实现 ──────────────────────────────────────────────────────

@record_function 装饰每个工具，这样 AgentOps 会捕获：

- 函数名称

- 输入参数

- 返回值

- 执行时间

- 任何异常

这些会作为带标签的跨度出现在会话重放时间线中。

@record_function("search_topic") def search_topic(topic: str, depth: str = "overview") -> dict: """搜索有关主题的信息。在生产环境中：将此存根替换为真正的搜索 API 调用。"""

模拟搜索延迟 -- 生产环境中移除

time.sleep(0.3)

存根响应 -- 替换为：tavily_client.search(query=topic)

return { "topic": topic, "depth": depth, "results": f"关于 {topic} 的全面概述：这是一个快速发展的领域，" f"2025-2026 年有重大进展。关键主题包括" f"技术创新、采用模式和组织影响。" f"多个研究小组和公司正在积极推动该领域的发展。", "source_count": 12, "timestamp": "2026-05-26" }

@record_function("get_key_facts") def get_key_facts(topic: str, focus: str = None) -> dict: """提取有关主题的关键事实。在生产环境中：这会处理真正的搜索结果。""" time.sleep(0.2) focus_note = f" (focus: {focus})" if focus else "" return { "topic": topic, "focus": focus_note, "facts": [ f"{topic} 的采用率同比增长了 42%", "领先的组织报告的生产率提高了 3-5 倍", "关键技术挑战

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

research_agent.py

目的：一个带有完整 AgentOps 指标记录的研究代理。

每个会话都会在 AgentOps 仪表板中进行记录、回放和成本跟踪。

#

先决条件：

pip install agentops anthropic python-dotenv

需要的环境变量（在 .env 中）：

AGENTOPS_API_KEY -- 从 https://app.agentops.ai 获取

ANTHROPIC_API_KEY -- 从 https://console.anthropic.com 获取

如何运行：

python research_agent.py

import

os

json

time

from

load_dotenv

.

sdk

decorators

record_function

(

)

── 初始化 AgentOps ────────────────────────────────────────────────────────

在任何代理代码运行之前必须调用。

标签允许你在仪表板中筛选和分组会话。

SDK 在初始化后会自动拦截所有 LLM 调用。

init

api_key

environ

[

"AGENTOPS_API_KEY"

]

,

tags

"research-agent"

"production"

"v1.0"

auto_start_session

True

初始化时自动开始一个会话

在 AgentOps 初始化之后初始化 Anthropic 客户端 -- SDK 包装 LLM 客户端

以自动捕获每次调用的输入、输出、令牌和成本。

client

"ANTHROPIC_API_KEY"

MODEL

"claude-sonnet-4-20250514"

── 系统提示 ─────────────────────────────────────────────────────────────

存储为常量，而不是内联 -- 可版本控制和可测试。

SYSTEM_PROMPT

""

"你是一个研究助手。当给定一个主题时：

1. 使用可用工具系统地收集信息

1. 调用 search_topic 以获取主题概述

1. 调用 get_key_facts 提取最重要的要点

1. 调用 format_summary 来构建最终输出

要详尽但简洁。始终将 format_summary 作为最后一步。"

── 工具定义 ──────────────────────────────────────────────────────────

这些是代理可以调用的工具。在实际系统中，search_topic

将会调用一个真正的搜索 API（如 Tavily、SerpAPI 等）。在这里它们只是存根

它们返回真实的数据，这样你可以在不使用外部 API 的情况下运行示例。

TOOLS

{ "name": "search_topic", "description": "搜索有关某个主题的全面信息。返回一个包含关键主题和背景的概述。将此作为任何研究任务的第一步。", "input_schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "要研究的主题。请具体一些。" }, "depth": { "type": "enum", "enum": ["overview", "detailed"], "description": "搜索的深度。首先使用 'overview'。" } }, "required": ["topic", "depth"] } }

{ "name": "get_key_facts", "description": "从搜索结果中提取关于某个主题的最重要事实。在使用 search_topic 之后，用于识别 5-7 个最重要的点。", "input_schema": { "type": "object", "properties": { "topic": { "type": "string", "description": "要提取事实的主题" }, "focus": { "type": "string", "description": "可选：要关注的具体角度（例如，'最新进展'、'主要参与者'）" } }, "required": ["topic"] } }

{ "name": "format_summary", "description": "将研究结果格式化为一个整洁的结构化摘要。在返回给用户之前，始终调用此工具作为最后一步。", "input_schema": { "type": "object", "properties": { "title": { "type": "string", "description": "摘要的标题" }, "key_points": { "type": "array", "items": { "type": "string", "description": "关键发现的列表（5-7 项）" } }, "conclusion": { "type": "string", "description": "研究的 2-3 句综合总结" } }, "required": ["title", "key_points", "conclusion"] } }

── 工具实现 ──────────────────────────────────────────────────────

@record_function 装饰每个工具，这样 AgentOps 可以捕获：

- 函数名称

- 输入参数

- 返回值

- 执行时间

- 任何异常

这些会作为标记的跨度出现在会话重放时间线中。

@record_function def search_topic(topic: str, depth: str) -> dict: """ 搜索有关某个主题的信息。

在生产环境中：将此存根替换为真正的搜索 API 调用。

模拟搜索延迟 -- 生产环境中移除

sleep(0.3)

存根响应 -- 替换为：tavily_client.search(query=topic)

return { "results": f"Comprehensive overview of {topic}: This is a rapidly evolving field with significant developments in 2025-2026. Key themes include technical innovation, adoption patterns, and organizational impact. Multiple research groups and companies are actively advancing the field.", "source_count": 12, "timestamp": "2026-05-26" } """

@record_function def get_key_facts(topic: str, focus: str = None) -> dict: """ 提取有关某个主题的关键事实。

在生产环境中：这将处理真正的搜索结果。

模拟延迟 -- 生产环境中移除

sleep(0.2)

focus_note = f" (focus: {focus})" if focus else "" return { "facts": [ f"{topic} has seen 42% year-over-year growth in adoption{focus_note}", "Leading organizations report 3-5x productivity improvements", "Key technical challenges include reliability, cost, and governance", "The market is projected to reach $4.9B by 2028", "Open-source tooling has matured significantly in the past 18 months" ], "confidence": "high" } """

@record_function def format_summary(title: str, key_points: list, conclusion: str) -> dict: """ 将研究格式化为结构化摘要。

这始终是研究工作流中的最后一步。 """ return { "format": "structured_summary", "title": title, "key_points": key_points, "conclusion": conclusion, "generated_at": datetime.now().isoformat() }

def execute_tool(tool_name: str, tool_input: dict) -> str: """ 将工具调用路由到正确的实现。

返回结果为 JSON 字符串，供模型读取。 """ if tool_name == "search_topic": result = search_topic(tool_input) elif tool_name == "get_key_facts": result = get_key_facts(tool_input) elif tool_name == "format_summary": result = format_summary(**tool_input) else: result = {"error": f"Unknown tool: {tool_name}"} return json.dumps(result)

── 代理循环 ─────────────────────────────────────────────────────────────

def run_research_agent(topic: str) -> dict: """ 在给定主题上运行研究代理。

循环：

1. 将目标发送给 Claude，附带可用的工具

1. 如果 Claude 想要调用工具，执行它并返回结果

1. 继续，直到 Claude 表示完成（stop_reason == 'end_turn'）

1. 返回最终的结构化摘要

AgentOps 会自动捕获每一次迭代，因为：

• LLM 客户端在 agentops.init() 之后被封装

• 每个工具都使用 @record_function 装饰

• 会话贯穿从 init 到 end_session() 的完整生命周期

print

"\n开始研究代理，主题为：'{topic}'"

"会话将在 https://app.agentops.ai 上可见\n"

messages

"role"

"user"

"content"

"研究这个主题并生成一个结构化摘要：{topic}"

final_summary

iteration

max_iterations

安全限制 -- 防止无限循环

while

<

+=

"第 {iteration} 次迭代：调用 Claude..."

response

create

max_tokens

4096

system

" stop_reason: {response.stop_reason}"

将助手的响应添加到消息历史中

append

"assistant"

content

如果 Claude 完成，提取最终摘要并退出

stop_reason

"end_turn"

在消息历史中查找 format_summary 的结果

for

msg

reversed

and

isinstance

block

hasattr

type

"tool_result"

try

result_data

loads

text

get

break

except

JSONDecodeError

AttributeError

KeyError

IndexError

TypeError

pass

如果 Claude 想使用工具，处理工具调用

"tool_use"

tool_results

" 工具调用：{block.name}({json.dumps(block.input, indent=2)})"

name

input

" 结果：{result[:100]}..."

"tool_use_id"

id

将工具结果返回给 Claude

=

"警告：代理达到最大迭代次数 ({max_iterations})。可能检测到循环。"

AgentOps 会将此标记为会话以失败结束

end_session

"Fail"

"达到最大迭代次数 -- 检查会话回放以进行循环分析"

以成功状态结束会话 -- 这将在 AgentOps 中最终确定会话

会话回放现在可在 app.agentops.ai 上查看

"Success"

or

"message"

"研究完成 -- 检查会话回放以查看完整追踪"

── 运行代理 ─────────────────────────────────────────────────────────────

__name__

"__main__"

"AgentOps 和 2026 年 AI 代理可观测性"

"\n"

+

"="

"研究摘要"

"错误：{result['error']}"

"标题：{result.get('title', 'N/A')}"

"\n关键点："

i

point

enumerate

" {i}. {point}"

"\n结论：{result.get('conclusion', 'N/A')}"

"会话回放可在：https://app.agentops.ai 上查看"

"查找标记为 'research-agent' 的会话"

KeyboardInterrupt

如果用户中断，清理会话结束

"\n会话由用户结束。部分追踪已保存到 AgentOps。"

Exception

as

e

记录失败，以便在仪表板中显示

"代理失败：{e}"

raise

如何运行

1. 创建你的 .env 文件

cat

.env

<<

'EOF'

EOF

2. 安装依赖项

3. 运行代理

research_agent

py

4. 打开仪表板查看你的会话

https://app.agentops.ai

这段代码的作用以及 AgentOps 捕获的内容：

• 顶部的 agentops.init() 调用会自动封装 Anthropic 客户端；之后的每次 LLM 调用都会被捕获，无需任何额外的仪器。

• 每个工具函数上的 @record_function 装饰器会在会话时间线中创建带标签的跨度，记录每个工具调用的输入、输出和执行时间。

• agentops.end_session(“Success”) 或 agentops.end_session(“Fail”) 调用会最终确定会话，并使其可供回放。

• 在 AgentOps 仪表板中，您将看到完整的会话时间线：每个 LLM 调用的令牌数量和成本，每个工具调用的参数和结果，代理推理的逐步进展，以及整个会话的总成本和延迟。

• 最大迭代次数保护机制以失败告终是循环检测的一个具体例子 —— 如果代理陷入循环，会话将被标记为失败，这使得在仪表板中轻松筛选和调查变得简单。

使用会话回放调试代理失败

当代理在生产环境中失败时，第一反应是添加更多日志。问题是，您需要的不是更多的数据点，而是能够导航已有数据的方法。AgentOps 的会话回放功能为您提供了一个时间旅行界面：可以回退到任意步骤，检查该时刻的确切状态，并向前查看其后果。

在生产环境中，有四种失败模式反复出现。以下是每种模式在会话跟踪中的表现方式以及如何解决它们：

• 循环代理：跟踪显示相同的工具调用反复进行，但参数略有不同。令牌数量在迭代过程中不断增长，而代理并未取得实质性的进展。成本图显示了一个失控的曲线。修复方法几乎总是以下两种之一：更好的停止条件（明确告诉代理“完成”的样子），或在 SDK 层面添加一个循环检测的防护机制，当同一工具连续调用 N 次后停止执行。上面代码中的 max_iterations 保护机制是这种修复方法的最简单版本。

• 工具幻觉：代理调用工具时，参数与工具的模式不匹配 —— 不存在的字段名，需要整数的地方却用了字符串，期望扁平值的地方却用了嵌套对象。跟踪显示了带有畸形参数的工具调用以及由此产生的错误。这种失败模式通常意味着工具描述存在歧义。解决方法是使用更精确的参数描述，并在工具定义中添加一两个示例，展示正确的使用方式。

• 上下文累积失败：在长时间的会话中，当代理将完整的对话历史传递给每个调用时，会出现一个特征模式：令牌数量随着会话长度线性增长，而到了某个点，质量会下降，因为模型的有效上下文窗口已被之前的对话填满。会话跟踪会以成本激增和同一会话范围内的质量下降来显示这一点。解决方法是上下文修剪；对已完成的子任务进行摘要，并裁剪之前的对话，而不是无限累积。

• 多代理交接失败：在多代理系统中，当一个代理将任务交接给另一个代理时，接收代理基于其获得的上下文进行操作。如果该上下文不完整或模糊，接收代理会做出错误的假设，失败会传播。交接负载在 AgentOps 跟踪中可见；您可以检查确切发送了什么内容，以及接收代理从中推导出的假设。这使得交接设计成为一个可调试的工程问题，而不是猜测游戏。

成本治理与安全

本节涵盖两个您需要了解的重要概念：成本治理和安全。

实践中的成本治理

生产环境中未管理的代理成本并不是一个小的不便 —— 它是工程团队最终不得不解释意外账单的原因。以下三种做法可以防止这种情况发生：

• 会话成本预算：设置每会话的最大成本，并中止超出阈值的代理运行。在上面的代码示例中，max_iterations 保护机制是这种机制的最简单形式。更高级的版本会在每次迭代后检查累积的令牌成本，并在超过配置限制时优雅地退出。AgentOps 的成本跟踪功能使每一步的成本都可见，这是这种动态预算执行的前提条件。

• 循环检测与告警：如果相同的工具连续被调用 N 次，且参数相似，而代理的状态没有明显变化，会话很可能在循环。这种模式在 AgentOps 时间线中表现为重复的相同跨度。在代理架构中构建显式的循环检测机制，无论是 SDK 层级还是代理循环内部的检查。

• 在保存的完成结果上进行微调：AgentOps 会保存代理生成的每一个完成结果。对于执行重复任务的代理（如分类、提取和格式化），可以利用这些保存的历史记录来微调一个更小、更便宜的专用模型。AgentOps 通过使用保存的完成结果来微调专用的 LLM，可以在高流量工作流程中实现高达 25 倍的成本节约。这是成熟生产代理系统中可获得的最高杠杆成本优化。

安全模式

• 提示注入检测：AgentOps 从原型到生产阶段完整地追踪所有注入尝试的数据轨迹。对于需要处理用户提供的内容（如网页、文档、电子邮件、客户消息）的代理，提示注入是一个真正的攻击面。在输入到达模型之前，需要检测包含隐藏指令的输入，这些指令旨在改变代理的行为。

• 范围约束：定义代理允许调用的工具，并在 SDK 层级强制执行。为客服设计的代理不应具有访问数据库写入工具的权限，无论模型认为它应该这么做。工具级别的范围约束是代理架构层中最直接的安全控制方式。

• 输出验证：在结构化代理输出到达下游系统（如数据库写入、API 调用、面向客户的消息）之前，将其与预期的模式进行验证。与在边界处捕获验证错误相比，导致下游失败的格式错误更难调试。输入防护机制在请求到达模型之前检测提示注入攻击和恶意意图，而输出防护机制则在传递到下游系统之前检查响应中的 PII 泄漏、幻觉、有毒内容和格式合规性。

• 人工介入检查点：对于高风险决策（如向客户发送通信、进行金融交易、修改生产数据），在代理工作流程中构建显式的批准关卡。代理到达检查点后，提交拟议的操作以供人工审核，并等待批准。这不是自动化失败，而是对于任何错误代价高于审核成本的操作的正确设计。

构建你的 AgentOps 堆栈

正确的堆栈不是功能最多的那个，而是最符合你实际约束条件的那个。按顺序回答以下四个问题。

• 你是否完全致力于使用 LangChain 或 LangGraph？如果是，那么 LangSmith 是显而易见的选择。其集成深度在行业内首屈一指，支持节点级状态差异对比、完整的代理执行图谱，以及针对新模型版本的回放功能。如果不在 LangChain 生态系统内，其价值会迅速下降。

• 你是否有数据主权或自托管需求？如果你的法律或合规团队要求数据必须保留在本地，那么 Langfuse 自托管版本是答案 —— 采用 MIT 许可证，功能齐全，是目前领先的开源选项，截至 2026 年中，每月 SDK 安装量超过 600 万。搭配 LiteLLM 可实现成本管理和路由控制。

• 你是否在多个代理框架之间构建系统？如果你的系统栈包括 CrewAI、OpenAI Agents SDK、AutoGen 和 LangChain —— 或者你预计随着框架生态的发展，这种混合情况会发生变化 —— 那么 AgentOps 是最适合的可观测性层。其 400 多个框架集成和会话回放设计，使其成为该领域最框架无关的选项。

• 评估门控的 CI/CD 是否是你的主要瓶颈？如果你团队的主要挑战是阻止提示回归进入生产环境，那么 Braintrust 拥有最强的 CI/CD 集成，其免费层级最为慷慨，每月支持 100 万次跨度和 1 万次评估运行。

如果以上条件均不明显适用，那么覆盖大多数团队需求的最小可行堆栈如下：

• 监控：AgentOps — 会话回放、成本跟踪、注入检测、400 多个框架集成。

• 追踪与评估：Langfuse 自托管 — MIT 许可证、完整追踪、提示管理、评估，无供应商锁定。

• 成本优化与路由：LiteLLM — 模型路由、语义缓存、跨所有主要提供商的统一 API。

• 安全性：Guardrails AI — 输入和输出验证、PII 检测、格式强制。

这四工具堆栈在无企业定价的情况下，涵盖了可观测性、评估、成本和安全性。对于大多数团队来说，这是合适的起点，并且随着需求增长，可以自然扩展。

结论

AgentOps 对于自主代理而言，就像 DevOps 对于软件部署一样 —— 是将实验性系统转化为可靠系统的操作性学科。没有它，你所交付的软件将具备推理、行动和无限循环的能力，却没有任何系统化的方法去理解其行为或随时间改进它。89% 的 CIO 将优先考虑基于代理的人工智能，他们将很快发现哪些团队具备这种操作性层级，哪些团队没有。

入门门槛比你想象的要低。只需三行代码，即可为任何代理添加完整的会话监控。会话回放、成本跟踪和注入检测从第一次运行起就已具备。从这个基础开始构建 —— 随着系统成熟和错误代价增加，逐步添加评估层、防护机制和 CI/CD 集成。2026 年，这些工具已具备生产就绪能力。唯一剩下的变量是，你是否选择使用它们。

更多相关内容

• 《机器学习实践者的智能代理指南》

• 《机器学习实践者的指南》

• 《机器学习实践者的模型指南》

• 世界级机器学习实践者的建议

• 从哲学研究生到机器学习实践者