Arize Phoenix has a built-in MCP server that lets your agents query traces with SQL

Phoenix MCP SQL 工具：代码模式下的追踪查询

TL;DR

• Phoenix 现在内置了一个 MCP 服务器，因此编码代理现在可以通过 MCP 与您的追踪数据进行交互。

• 该服务器现在提供了两个只读 SQL 工具：describeSqlSchema 和 executeSql，代理可以通过 SQL 查询追踪数据，而无需逐页浏览。

• 代理在代码模式下使用这些工具：它编写一个简短的程序，程序在沙箱中调用这些工具，只有结果会传递给模型。

• 服务器永远不会直接运行模型编写的 SQL。每个语句在到达数据库之前都会经过检查、重建和绑定。

• 在八题基准测试中，SQL 工具以大约 17 倍于仅检索工具的成本回答了相同的问题。

Phoenix 现在内置了 MCP（Model Context Protocol）服务器，因此编码代理可以像编写和调试代码时一样，在相同环境中检查追踪数据。

对于需要跨多个跨度进行聚合的问题，仅检索工具可能变得昂贵，因为代理必须通过模型上下文逐页获取数据。SQL 改变了工作方式：数据库处理过滤、连接和聚合，而代码模式将中间结果保留在沙箱中。

在我们的八题基准测试中，这种方法将平均成本降低了约 17 倍。

仅检索的 MCP：89 次交互获取一个计数

当我们将一个问题和服务器的检索工具交给代理时发生了什么？问题是：“有多少追踪数据触发了高影响错误？”为了解答，代理必须遍历所有跨度，即构成每个追踪的单个模型和工具调用。它列出了项目，找到正确的项目，然后逐页获取跨度。由于项目包含的 JSON 数据量超过了代理一次能处理的范围，它读取一页，统计所需内容，获取下一页，重复这一过程。

在读取 19 页后，它正确回答了问题：99 条追踪。整个过程耗时 89 次交互，约 14 分钟，花费了 10.35 美元的 tokens。

这个差距正是此功能要解决的问题。数据库一直保存着答案；工具的结构是代理为此付出高昂代价的唯一原因。

为什么仅检索的 MCP 工具在代理追踪数据上会变得昂贵

大多数 MCP 检索工具以对象形式暴露数据：列出项目，获取跨度页面，读取跨度的注释。这种结构在需要获取单个追踪的完整细节时非常理想。但当问题需要统计、平均值、百分位数或跨多个追踪的分类时，就会变得昂贵，因为代理必须检索每个相关跨度并自行执行聚合。要获得这些答案，唯一的方法是拉取所有相关跨度并自行计算。

对于 LLM 追踪数据，这种计算尤其昂贵。典型的基础设施日志行很短：时间戳、状态码、持续时间。而 LLM 跨度可能包含提示和完成内容，单行可能包含数千字节的文本。这使得追踪数据成为最不适合逐页读取的数据之一，也是最适合在模型看到之前进行汇总的数据之一。

这就是开头示例中发生的情况。代理获取了所有 3,624 个跨度，跨 19 页 JSON 传递累计值，重建了一个数据库本可以一查询生成的数字。每一页都必须经过模型处理，这正是交互次数、分钟数和美元支出的来源。

仅提供对象获取的工具，代理的行为就像一个爬虫。我们希望它能像分析师一样进行查询。

Arize Phoenix 的 MCP 服务器如何通过代码模式运行 SQL

为此，我们为代理提供了两种直接向数据库提问的工具。这两个工具都运行在 Phoenix 的 MCP 服务器上，且均为只读操作。describeSqlSchema 向代理展示它可以查询的表及其连接方式。executeSql 执行一条只读 SQL 语句并返回结果行。通过这两个工具，代理可以先查看遥测数据的结构，然后像在 SQL 控制台中一样提出精确的问题。

代码模式是保持成本低廉的关键。代理不再逐个调用聊天中的工具，而是编写一个简短的 Python 程序。Phoenix 在受限的 Monty 沙箱中服务器端运行该程序，程序从沙箱内部调用 MCP 工具。中间的模式查询和查询结果都保留在沙箱内；只有程序返回的最终值会传递给模型。Phoenix 默认为远程 MCP 服务器启用代码模式。

以下是代理如何针对 benchmark 示例项目 trail-gaia 回答相同的关键错误问题。该项目包含慢速运行产生的相同 3,624 个跨度。在此数据集中，关键错误是指带有 1.0 分数的 trail_error 注释，因此查询会统计至少包含一个匹配注释的不同追踪数量。

result = await call_tool("executeSql", {"sql": """
SELECT COUNT(DISTINCT t.id) AS n
FROM span_annotations sa
JOIN spans s ON s.id = sa.span_rowid
JOIN traces t ON t.id = s.trace_rowid
JOIN projects p ON p.id = t.project_rowid
WHERE p.name = 'trail-gaia'
AND sa.name = 'trail_error'
AND sa.score = 1.0
"""})

return result["rows"] # [[99]]: 唯一传递给模型的值

这次运行仅用了 7 轮对话，耗时约 33 秒，费用为 $0.23，相比之下，首次方法需要 89 轮对话，耗时约 14 分钟，费用为 $10.35。答案完全相同：99 个追踪。区别在于这 3,624 个跨度从未离开数据库，只有最终的计数结果返回给模型。

Phoenix 如何确保代理编写的 SQL 保持只读

代理编写的 SQL 需要严格边界。Phoenix 不会直接执行模型的 SQL 语句。它会解析查询，限制其仅访问批准的遥测数据，重新构建查询，应用数据库级别的检查，并限制执行范围和结果规模。

• 首先解析查询。服务器将 SQL 转换为结构化查询，使检查关注查询的实际操作，而非文本写法。

• 仅允许授权的表和列。如果查询请求超出批准的遥测范围，将在执行前被拒绝。

• 重新构建语句。Phoenix 从解析后的查询生成新的 SQL。数据库执行的是重新构建后的语句，而非模型原始文本。

• 让数据库强制边界。重新构建后的查询仍需通过 SQLite 授权器或 Postgres 查询计划检查。

• 限制所有查询。所有查询均为只读，且受运行时间、行数和结果规模限制。

这是核心约定：只读 SQL 经解析而非信任，且在执行前即被限制。SQL 工具不会为数据访问开辟新路径。它们只能读取已登录用户在 Phoenix 中可访问的遥测数据，且无法修改数据库中的任何内容。

基准测试：SQL + 代码模式 vs. 仅检索工具

我们对同一代理的两种配置（仅使用检索工具和SQL工具在代码模式下运行）进行了八次遥测问题的测试，每个问题测试三次。这些问题涵盖了计数、百分位数、分类分解、连接和时间趋势。评分模型对每个答案进行评分，我们还手动审查了输出结果。

在整个基准测试中，结合SQL和代码模式的平均成本约为每题0.23美元，而仅使用检索工具的成本为3.97美元（约为前者的六分之一）。

详细数据如下：

问题

SQL $

检索 $

检索 / SQL

SQL轮次

检索轮次

高影响错误数量

0.23

10.35

44倍

7

89

p95 LLM-跨度持续时间

0.22

4.96

23倍

6

49

10分钟时间桶

0.28

4.76

17倍

100

平均跨度持续时间

0.19

3.69

19倍

54

五个最长跨度

3.66

16倍

55

按跨度类型分解

0.18

1.90

10倍

工具相关错误数量

1.71

8倍

67

平均可靠性评分

0.31

0.70

2倍

8

13

平均

3.97

6.5

64.5

成本是显而易见的差异，但并非唯一的差异。以按类型分组的跨度分解为例。SQL运行在6轮次内给出了精确的计数。在三次运行中的一次，检索代理加载了整个项目，搜索了已保存的文件，并报告了622个类型为TOOL的跨度。实际数量是626个。这个4个跨度的误差持续了103轮次和2.01美元的投入，评分模型仍然将其标记为正确。手动在十几页中进行计数，正是这种小误差容易被忽略的地方。

目前基准测试尚未涵盖的两个方面是：最困难的多步骤相关性尚未包含在内。在像最后一行的单个过滤计数这种简单查询中，检索工具可能更便宜，因为SQL没有需要压缩的内容。每当替代方案需要手动重建答案时，SQL都会占据优势，而这种情况在调试过程中占大多数。

将您的编码代理连接到Phoenix的MCP服务器

Phoenix内置的MCP服务器从Phoenix 19.0.0版本开始提供，SQL工具从v20.2.0版本开始提供。将Claude Code、Cursor、MCP Inspector或其他MCP客户端连接到您的Phoenix端点，并通过OAuth进行授权。px CLI可以为您编写配置：

px setup mcp --agent claude # 或 codex, cursor, gemini, opencode, vscode

您也可以手动设置。在Claude Code中，只需一条命令：

claude mcp add --transport http phoenix https://your-phoenix-host/mcp

关于不同客户端的设置详情，请参阅远程MCP服务器文档。

然后使用您已用于调试生产追踪的问题进行查询：哪些工具最常失败？延迟集中在哪些地方？本周有多少追踪遇到了错误？

代理可以检查模式、编写只读查询，并在不将每个跨度通过模型上下文进行分页的情况下返回答案。

由于Phoenix是开源的，您可以自由阅读、配置或关闭所有功能。当您自托管时，查询将针对您已经在运行的SQLite或PostgreSQL数据库，而不是针对供应商云中的副本。

Phoenix的MCP设置页面。代码模式默认开启，服务器URL已准备好指向客户端，每个客户端都有一个单行连接命令。

相关资源：从远程MCP服务器文档开始，然后查看Meet PXI、编码代理追踪与评估，以及Arize Phoenix的下一步计划。对于更广泛的堆栈，请阅读从追踪构建代理评估以及Model Context Protocol (MCP)和追踪的术语表条目。

SQL 为 Phoenix 的 MCP 服务器带来的价值

可观测性工具一直帮助团队了解系统运行状况。现在，你的代理可以直接查询这些数据并返回所需答案。让数据库执行计数操作，而不是先将每一行数据移动到其他位置，这是处理数据时最古老的教训之一。现在，代理也可以应用这一教训。

SQL 是基础，因为它具有通用性：它可以回答那些未曾预料到的问题，包括你下周可能提出的全新问题。我们构建这一功能，使分析你追踪数据的代理能够从收集数据页面转变为向数据提出精确问题。将它指向你自己的追踪数据，告诉我们它哪些地方正确，哪些地方存在困难。如果你有任何反馈，欢迎在 Phoenix 社区 Slack 中与我们联系。