使用 Freeplay 进行智能体可观测性和评估¶

Freeplay 提供了一个用于构建和优化 AI 智能体的端到端工作流，并且可以与 ADK 集成。通过 Freeplay，你的整个团队可以轻松协作，迭代智能体指令（提示），试验和比较不同的模型和智能体更改，运行离线和在线评估以衡量质量，监控生产，并手动审查数据。

Freeplay 的主要优势：

简单的可观测性 - 专注于智能体、LLM 调用和工具调用，便于人工审查
在线评估/自动化评分器 - 用于生产中的错误检测
离线评估和实验比较 - 在部署前测试更改
提示管理 - 支持将 Freeplay 游乐场中的更改直接推送到代码
人工审查工作流 - 用于错误分析和数据标注的协作
强大的 UI - 使领域专家能够与工程师紧密协作

Freeplay 和 ADK 相辅相成。ADK 为你提供了一个强大且富有表现力的智能体编排框架，而 Freeplay 则用于可观测性、提示管理、评估和测试。一旦你与 Freeplay 集成，你就可以从 Freeplay UI 或代码更新提示和评估，以便团队中的任何人都可以做出贡献。

点击此处查看演示。

入门¶

以下是 Freeplay 和 ADK 的入门指南。你还可以在此处找到一个完整的 ADK 智能体示例仓库。

创建 Freeplay 账户¶

注册一个免费的 Freeplay 账户。

创建账户后，你可以定义以下环境变量：

FREEPLAY_PROJECT_ID=
FREEPLAY_API_KEY=
FREEPLAY_API_URL=

使用 Freeplay ADK 库¶

安装 Freeplay ADK 库：

pip install freeplay-python-adk

当你初始化可观测性时，Freeplay 将自动从你的 ADK 应用程序捕获 OTel 日志：

from freeplay_python_adk.client import FreeplayADK
FreeplayADK.initialize_observability()

你还需要将 Freeplay 插件传递给你的 App：

from app.agent import root_agent
from freeplay_python_adk.freeplay_observability_plugin import FreeplayObservabilityPlugin
from google.adk.runners import App

app = App(
    name="app",
    root_agent=root_agent,
    plugins=[FreeplayObservabilityPlugin()],
)

__all__ = ["app"]

你现在可以像往常一样使用 ADK，并且你将在“可观测性”部分看到日志流向 Freeplay。

可观测性¶

Freeplay 的可观测性功能让你清晰地了解智能体在生产环境中的行为。你可以深入研究单个智能体跟踪，以了解每个步骤并诊断问题：

跟踪详情

你还可以使用 Freeplay 的过滤功能来搜索和过滤任何感兴趣的数据段：

提示管理（可选）¶

Freeplay 提供原生提示管理，它简化了版本控制和测试不同提示版本的过程。它允许你在 Freeplay UI 中试验 ADK 智能体指令的更改，测试不同的模型，并将更新直接推送到你的代码，类似于功能标志。

要利用 Freeplay 的提示管理功能与 ADK 结合使用，你需要使用 Freeplay ADK 智能体包装器。FreeplayLLMAgent 扩展了 ADK 的基础 LlmAgent 类，因此你无需将提示硬编码为智能体指令，而可以在 Freeplay 应用程序中对提示进行版本控制。

首先，通过“提示”->“创建提示模板”在 Freeplay 中定义一个提示：

创建提示模板时，你需要添加 3 个元素，如下节所述：

系统消息¶

这对应于你代码中的“指令”部分。

智能体上下文变量¶

在系统消息底部添加以下内容将创建一个变量，用于传递正在进行的智能体上下文：

{{agent_context}}

历史块¶

点击“新消息”并将角色更改为“历史”。这将确保在存在时传递过去的消息。

提示编辑器

现在在你的代码中，你可以使用 FreeplayLLMAgent：

from freeplay_python_adk.client import FreeplayADK
from freeplay_python_adk.freeplay_llm_agent import (
    FreeplayLLMAgent,
)

FreeplayADK.initialize_observability()

root_agent = FreeplayLLMAgent(
    name="social_product_researcher",
    tools=[tavily_search],
)

当 social_product_researcher 被调用时，提示将从 Freeplay 中检索并使用适当的输入变量进行格式化。

评估¶

Freeplay 使你能够从 Freeplay Web 应用程序定义、版本化和运行评估。你可以通过“评估”->“新建评估”为你任何提示或智能体定义评估。

在 Freeplay 中创建新评估

这些评估可以配置为用于在线监控和离线评估。离线评估的数据集可以上传到 Freeplay 或从日志示例中保存。

数据集管理¶

随着数据流入 Freeplay，你可以使用这些日志开始构建数据集，以便反复进行测试。使用生产日志创建黄金数据集或故障案例集合，你可以在进行更改时用于测试。

保存测试用例

批量测试¶

当你迭代智能体时，你可以在提示和端到端智能体级别运行批量测试（即离线实验）。这允许你比较多个不同的模型或提示更改，并量化在整个智能体执行过程中逐一进行的更改。

此处是一个使用 ADK 在 Freeplay 上执行批量测试的代码示例。此处是一个使用 Google ADK 在 Freeplay 上执行批量测试的代码示例。

前往 Freeplay 注册账户，并在此处查看完整的 Freeplay <> ADK 集成：https://github.com/228Labs/freeplay-google-demo。