Agent Framework 教程

在笔记本中开始使用

使用“Hello World”代理在笔记本中开始使用 Agent Framework。

示例代理

如需探索示例代理的示例代码，请将此 Google 云端硬盘文件夹中的 .zip 文件下载到您的本地开发环境。

示例目录中包含演示代理。在 requirements.txt 文件中为特定演示代理安装依赖项：

pip install  -r samples/anthropic_demo/requirements.txt

运行以下命令：

af web samples

af run samples/hello_world

教程

本页面提供了有关使用 Agent Framework 时常见任务的分步教程。选择教程以开始使用。

教程：将您自己的数据集成到代理中

本教程介绍了向代理提供您自己的数据、知识或文档的不同方法。最佳方法取决于数据的大小和类型，以及您希望在延迟时间和准确率之间取得的平衡。

提供您自己的数据

您可以通过多种方式向代理提供自己的数据/知识/文档，具体取决于数据大小、数据类型以及所需的延迟时间/准确率权衡。

类型 少量 大量
纯文本 在指令或 RAG 中嵌入 RAG
文档 在指令或 RAG 中嵌入 RAG
其他媒体
（图片、音频、视频等）		 WIP WIP

以下操作方法详细介绍了每种方法。

在指令中嵌入数据

向代理提供少量文档的简单方法是在指令中嵌入它们。

PDF 或其他文本文件可以转换为纯文本并在指令中嵌入。

注意事项

  • 文件的内容将发送到模型，因此文件越大，延迟时间和费用就越高。

  • 无论用户的查询是否与内容无关，系统都会针对所有请求将内容发送到模型。

  • 您可以将纯文本或任何易于阅读的文本格式（例如 Markdown）用于文件。

安全风险

  • 以这种方式嵌入内容存在一些安全风险，因为服务器可能会将嵌入文档的内容视为自己的指令。

  • 通过明确标记嵌入内容的开头和结尾，可以在一定程度上降低此安全风险，如以下示例所示。

  • 由于存在此风险，请勿嵌入您不信任的内容，例如任何用户生成的内容。

示例

为了使指令易于阅读，一种常见方法是加载文件，然后使用 Python 的 f 字符串语法将其插入到指令中。

请注意，它使用 XML 标记将文件内容与其余指令分隔开来。您也可以使用其他方式进行分隔，只要模型能够清楚理解即可。例如，BEGIN_USER_GUIDE/END_USER_GUIDE 之类的标记。

def read_file(filename):
  file_path = os.path.join(os.path.dirname(__file__), filename)
  with open(file_path, 'r') as f:
    return f.read()

agent_framework_bot = Agent(
    # ...
    instruction=f"""You are an agent that answers user's questions about the Agent Framework.

You answer users' questions based on the user guide below:
<user_guide>
{read_file('user_guide.md')}
</user_guide>
"""
)

使用 RAG

检索增强生成是一种常见模式，用于使用您自己的数据增强模型回答。该方法对于大量数据特别有用，因为它通过为数据编制索引来发挥作用，并且只检索与查询相关的一小部分数据。

Agent Framework 提供了多种与各种不同的 RAG 系统集成的方法。

场景 建议
演示/原型 FilesRetrieval
少量数据
（少量文档）		 FilesRetrieval
全托管式 RAG 解决方案 VertexRagRetrieval
DIY 或其他 RAG 解决方案 LlamaIndexRetrieval

FilesRetrieval

FilesRetrieval 会在代理启动时构建内存中向量存储区，这会增加延迟时间，并且受 API 托管环境的内存和性能的限制。因此，此选项仅适用于演示/原型，或文档数量非常少的生产环境。

FilesRetrieval 是基于 LlamaIndex 构建的。您需要按照 LlamaIndex 的文档进行设置。

设置完成后，您可以将文档放在文件夹中，并创建检索工具，如下所示：

company_policies_retrieval = FilesRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    input_dir=os.path.join(os.path.dirname(__file__), 'company_policies'),
)

root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

VertexRagRetrieval

Vertex RAG Engine 是一种全托管式服务，可处理数据注入、转换、嵌入、索引编制和检索。

如需使用该工具，请按照快速入门设置语料库并注入文档。然后将该工具添加到您的代理中。

company_policies_retrieval = VertexRagRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    rag_corpus_name='projects/.../locations/.../ragCorpora/...',
)
root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

通过使用 Google 搜索，您的代理将能够访问实时的现实世界知识，并使用 Google 搜索来研究问题。

备注

  • 使用“依托 Google 搜索进行接地”功能可能会产生额外费用。
  • 对于 Gemini 1.5：
    • 将 Google 搜索工具添加到代理后，该代理就无法使用其他工具。
    • 无论查询是否需要 Google 搜索，Google 搜索工具都会始终执行。
  • 对于 Gemini 2.0 及更高版本：
    • 您可以在使用 Google 搜索工具的同时使用其他工具。
    • 只有当模型认为有必要时，才会执行 Google 搜索工具。
  • 第三方模型不支持 Google 搜索工具。
  • 如需使用 Google 搜索工具，您必须遵循使用 Google 搜索建议页面中的准则，包括始终显示横幅以显示相关 Google 搜索查询。我们的开发者界面也遵循这些规则。

示例

启用 Google 搜索工具非常简单，只需将 google_search 添加到工具列表中即可。

from agents.tools import google_search

root_agent = Agent(
    # ...
    tools=[google_search],
)

教程：评估代理的性能

评估您的代理对于确保其按预期运行并符合您的质量标准至关重要。Agent Framework 提供了多种使用测试文件和评估标准评估代理性能的方法。

评估的工作原理

每个测试文件都包含一个查询列表、预计的工具轨迹和参考回答。测试文件可以整理到文件夹中。（可选）文件夹可以包含用于指定评估标准的 test_config.json 文件。

示例测试文件

测试文件包含带有查询、预计工具使用情况和参考回答的会话。示例如下：

[
  {
    "query": "hi",
    "expected_tool_use": [],
    "reference": "Hello! What can I do for you?\n"
  },
  {
    "query": "roll a die for me",
    "expected_tool_use": [
      {
        "tool_name": "roll_die",
        "tool_input": {
          "sides": 6
        }
      }
    ]
  },
  {
    "query": "what's the time now?",
    "expected_tool_use": [],
    "reference": "I'm sorry, I cannot access real-time information, including the current time. My capabilities are limited to rolling dice and checking prime numbers.\n"
  }
]

评估标准

test_config.json 中的评估标准定义了如何衡量代理的性能：

  • tool_trajectory_avg_score：评估工具轨迹。
  • response_match_score：评估回答。

如果未提供评估标准，系统将应用默认配置。

示例评估标准 (test_config.json)

下面是一个 test_config.json 文件示例，其中指定了自定义评估标准：

{
  "criteria": {
    "tool_trajectory_avg_score": 1.0,
    "response_match_score": 0.8
  }
}
  • tool_trajectory_avg_score：设置为 1.0，表示预计工具轨迹使用情况完美。
  • response_match_score：设置为 0.8，允许代理的回答存在一小部分误差。

运行评估的方式

1. af web - 通过网页界面运行评估

您可以使用基于网页的界面以互动方式评估代理。

步骤：
  1. 通过运行以下命令启动 Web 服务器：bash af web
  2. 在网页界面中：
    • 选择一个代理。
    • 点击“Save session as test file”，以将会话保存为测试文件。
    • 点击“Run test file”，以显示包含代理文件夹中的测试文件的弹出式窗口。
测试文件：

测试文件与代理存储在同一文件夹中。您可以根据需要手动更新或添加测试文件。

2. af test - 通过命令行运行测试

您可以使用 af test 命令运行指定文件夹中的所有测试文件。该文件夹应包含代理定义和测试文件。

示例：
af test samples/agent_folder

此命令会找到并执行指定文件夹中的所有测试文件 (*.test.json)。

3. pytest - 以程序化方式运行测试

您还可以使用 pytest 运行测试文件，以作为集成测试的一部分。

示例命令：
pytest tests/integrations/
示例测试代码：

以下是运行单个测试文件的 pytest 测试用例示例：

def test_with_single_test_file():
    """Test the agent's basic ability via a session file."""
    AgentEvaluator.evaluate(
        "tests.integration.fixture.home_automation_agent",
        "tests/integration/fixture/home_automation_agent/simple_test.test.json",
    )

通过这种方法，您可以将代理评估集成到 CI/CD 流水线或更大的测试套件中。