利用 AI 可观测性与治理功能掌控您的 OpenHands 智能体
OpenHands 是一款领先的开源 AI Agent 框架，在 SWE-bench 基准测试中表现卓越。AI 编码 Agent 功能非常强大，但往往也是“黑盒”。你交给它一项任务，它会编辑文件、运行终端命令、浏览网页，但你却无法获得结构化的记录来了解发生了什么，或者结果是否理想。在这篇文章中，我们将展示 MLflow 如何通过追踪每一步操作并评估每一次输出，以极简的设置为您提供对 OpenHands Agent 的全面可观测性与治理能力。
什么是 OpenHands？
OpenHands 是一个用于构建 AI Agent 的开源平台，能够与代码、终端、文件系统和网络进行交互。它同时提供 Python SDK 和 CLI，使得编写超越传统聊天式代码助手的自动化工作流变得非常容易。
关键能力包括
- 终端访问 - Agent 在沙盒环境中运行 shell 命令
- 文件编辑 - Agent 可以读取、创建和修改项目文件
- 网页浏览 - Agent 可以导航网页并从中提取信息
- MCP 集成 - Agent 通过模型上下文协议 (Model Context Protocol) 连接外部工具
- 模型无关 - 适用于 Claude、OpenAI 以及开源模型
由于 OpenHands Agent 是自主运行的，没有人类会实时监控每一个步骤。这使得可观测性和治理变得至关重要。你需要了解发生了什么、触发了哪些工具、消耗了多少 token，以及输出是否达到了你的标准。这就是 MLflow 发挥作用的地方。
通过 OpenTelemetry 追踪 OpenHands Agent
当 Agent 自主运行时，了解其操作过程非常重要。哪些工具被触发了？调用了多少次 LLM？Token 花在哪里了？如果没有这些信息，调试故障和优化性能只能靠猜测。
MLflow Tracing 是一个功能强大的工具，只需极简设置即可为任何 Agent 增加可观测性。OpenHands 原生支持发送 OpenTelemetry 追踪数据，而 MLflow 开箱即用地支持这些数据。要连接 OpenHands 和 MLflow，请首先启动您的 MLflow 服务器（如果尚未启动）。
uvx mlflow server
如需使用 pip、docker compose 等其他工具，请参阅 设置 MLflow 服务器。
然后，在您的 OpenHands 脚本中设置以下三个环境变量，以连接两者：
import os
# Point OpenTelemetry traces to your MLflow server
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://:5000"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = "x-mlflow-experiment-id=123" # Replace "123" with your MLflow experiment ID
os.environ["OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"] = "http/protobuf"
设置完成后，下面这个脚本将创建一个 OpenHands Agent，给它分配一个简单任务，并将所有追踪数据发送到 MLflow：
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.task_tracker import TaskTrackerTool
from openhands.tools.terminal import TerminalTool
llm = LLM("openai/gpt-5")
agent = Agent(
llm=llm,
tools=[
Tool(name=TerminalTool.name),
Tool(name=FileEditorTool.name),
Tool(name=TaskTrackerTool.name),
],
)
cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)
conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()
print("All done!")
一旦 Agent 完成任务，每一次 LLM 调用、工具调用和 Agent 步骤都会以结构化 Span 的形式显示在 MLflow 中。导航至 MLflow UI（例如 https://:5000），选择在环境变量中设置的实验，然后打开“Traces”选项卡查看记录的追踪数据。
点击追踪记录的 ID，将打开一个包含更多详细信息的新窗格，如下所示。
通过该视图，您可以查看关于 OpenHands Agent 的详细信息，例如：
- 来自 LLM 的 Prompt 和响应
- 给予 Agent 的工具和系统 Prompt
- Agent 实际调用的工具及其输入和输出
- 每个步骤的延迟
- Token 使用情况分解及相应的成本
这些信息对于调试和优化 OpenHands Agent 非常有帮助。
评估 OpenHands Agent 的运行结果
追踪可以告诉您*发生了什么*。评估则可以告诉您结果是否*良好*。这是两个互补的角度：可观测性与质量保证。Agent 产生的结果对吗？生成的代码正确吗？输出与原始请求相关吗？是否存在效率低下的工具调用？
MLflow Evaluation 是一个综合工具包，供 Agent 开发者系统地评估其 Agent 的质量。它提供了 60 多种内置评分器和 LLM 裁判，并集成了 RAGAS、DeepEval 等流行库。
评估 OpenHands Agent 运行结果的最快方法是直接从 MLflow UI 运行内置的 LLM 裁判。
- 从“Traces”选项卡中选择要评估的追踪记录。
- 点击操作菜单中的“Run Judges”按钮。
- 选择要运行的裁判并提交。
- 裁判运行完成后，MLflow 会在同一页面上显示结果，并在表格中添加新列。
在以下示例中，我们使用三个评分器来评估输出质量。
RelevanceToQuery：输出是否与原始请求相关Correctness：输出是否正确ToolCallEfficiency：工具调用是否高效
有关内置裁判的完整列表，请参阅 内置 LLM 裁判。
每个追踪记录都会根据评分标准进行评估，产生明确的通过/失败指标以及来自 LLM 裁判的详细依据。这对于无人值守运行的 Agent 尤为强大。您定义质量标准，MLflow 会告诉您 Agent 是否达标。
或者，您也可以通过 mlflow.genai.evaluate() API 以编程方式运行评估，如下所示。
import mlflow
from mlflow.genai.scorers import RelevanceToQuery, Correctness, ToolCallEfficiency
# Load OpenHands traces from MLflow
traces = mlflow.search_traces(locations=["123"], max_results=10) # substitute "123" with your experiment ID
# Evaluate output quality
results = mlflow.genai.evaluate(
data=traces,
scorers=[
RelevanceToQuery(),
Correctness(),
ToolCallEfficiency(),
],
)
评估结果的链接将显示在控制台中。
使用 AI Gateway 进行 LLM 流量治理
高度自主的 Agent（如 OpenHands）的一个隐患在于它们自带风险。它们可能会在长时间运行的任务中消耗过多的 Token、向 LLM 提供商泄露敏感数据，或遭到 Prompt 注入攻击。
AI Gateway 是一个中心化的代理层，位于您的应用程序和 LLM 提供商之间。它通过统一的 API 路由请求，同时管理凭据、追踪使用情况、执行治理策略，并提供跨所有 LLM 调用的完整可观测性。无需在脚本和环境中散布 API 密钥，您只需在网关中配置一次凭据，即可由它处理所有请求的身份验证、成本追踪和策略执行。
将 MLflow AI Gateway 与 OpenHands 配合使用非常简单。只需将 base_url 设置为 AI Gateway 的端点 URL（可以在 MLflow AI Gateway UI -> Endpoints -> Use 中找到）。
llm = LLM(
base_url="https://:5000/gateway/mlflow/v1", # MLflow AI Gateway endpoint URL
model="my-openai-endpoint", # Set the model to the name of the endpoint you want to use
)
就是这样！现在，来自 OpenHands 的所有 LLM 流量都会通过 MLflow AI Gateway 路由。您可以免费获得治理和可观测性，例如：
- 预算控制 - 设置预算策略，在支出超过阈值时发出警报或拒绝请求
- 使用追踪 - 每一项 LLM 调用都会自动记录，并具有 Token 级的成本可见性
- 密钥管理 - 将 API 密钥安全地存储在中心化网关中，绝不将其暴露在脚本中
- 回退路由 - 定义回退链，当主提供商不可用时，将请求路由到备份提供商
总结
OpenHands Agent 虽然强大但具有自主性，这意味着您需要强大的可观测性来信任和改进它们。MLflow 作为 AI 平台，从三个层面提供了这一点：
- 追踪 (Trace) 每一个 Agent 的运行。通过三个环境变量，以结构化、可搜索的 Span 形式查看工具调用、LLM 交互和 Token 计数。
- 评估 (Evaluate) 使用内置和自定义评分器来评估输出质量和工具有效性。在进入生产环境之前捕获回归问题。
- 治理 (Govern) 通过 AI Gateway 管理 LLM 流量，实现成本控制、使用追踪和集中式凭据管理。
这两个项目都是完全开源的，随着生态系统的成熟，我们期待更深入的整合。
如果您觉得这些内容有用，请在 GitHub 上为我们点个星：github.com/mlflow/mlflow⭐️