用于 ADK 的 Freeplay 可观测性¶

Supported in ADKPython

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 的“Observability”部分看到日志流。

可观测性¶

Freeplay 的可观测性功能可让你清晰地查看智能体在生产环境中的行为。你可以深入分析单个智能体追踪记录（Traces），以了解每个步骤并诊断问题：

追踪详情

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

提示词管理 (可选)¶

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

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

首先，通过“Prompts” -> “Create Prompt Template”在 Freeplay 中定义一个提示词模板：

提示词定义

创建模板时，你需要添加以下 3 个元素：

系统消息¶

这对应于你代码中的 instruction 部分。

智能体上下文变量¶

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

{{agent_context}}

历史记录块¶

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

提示词编辑器

现在在你的代码中，你可以使用 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 使你能够直接从 Web 应用中定义、版本化并运行评估。你可以通过“Evaluations” -> “New Evaluation”为你任何提示词或智能体定义评估。

在 Freeplay 中创建新评估

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

数据集管理¶

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

保存测试用例

批量测试¶

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

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

前往 Freeplay 官网注册账户。你可以在此处查看完整的 Freeplay <> ADK 集成示例：https://github.com/freeplayai/freeplay-google-demo/tree/main。