このページは Cloud Translation API によって翻訳されました。

エージェントフレームワークチュートリアル
コレクションでコンテンツを整理必要に応じて、コンテンツの保存と分類を行います。

ノートブックで使ってみる

ノートブックで「Hello World」エージェントを使用して、Agent Framework を使ってみましょう。

サンプルエージェント

サンプルエージェントのサンプルコードを確認するには、こちらの Google ドライブフォルダから .zip ファイルをローカル開発環境にダウンロードします。

samples ディレクトリにはデモエージェントがあります。特定のデモエージェントの 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 などのテキストファイルは、書式なしテキストに変換して手順に埋め込むことができます。

考慮事項

ファイルの内容がモデルに送信されるため、ファイルが大きくなるほど、レイテンシと費用が高くなります。
ユーザーのクエリがコンテンツと関係がない場合でも、すべてのリクエストでコンテンツがモデルに送信されます。
ファイルには、書式なしテキストまたは読み取り可能なテキスト形式（マークダウンなど）を使用できます。

セキュリティリスク

このようにコンテンツを埋め込むと、埋め込まれたドキュメントのコンテンツがサーバー独自の指示として扱われる可能性があるため、セキュリティ上のリスクが生じます。
このセキュリティリスクは、埋め込まれたコンテンツの開始と終了を明確にマークすることで、ある程度軽減できます。以下の例をご覧ください。
このリスクがあるため、信頼できないコンテンツ（ユーザー作成コンテンツなど）を埋め込まないでください。

例

手順を読みやすくするには、ファイルを読み込み、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 検索を使用して質問を調査できます。

メモ

Google 検索によるグラウンディングを使用すると、追加料金が発生する場合があります。
Gemini 1.5 の場合:
- エージェントに Google 検索ツールを追加すると、そのエージェントに他のツールを追加することはできません。
- Google 検索ツールは、クエリに Google 検索が必要かどうかにかかわらず、常に実行されます。
Gemini 2.0 以降の場合:
- Google 検索ツールを使用しながら、他のツールを使用することもできます。
- Google 検索ツールは、モデルが必要と判断した場合にのみ実行されます。
サードパーティ製モデルは Google 検索ツールをサポートしていません。
Google 検索ツールを使用するには、Google 検索の検索候補を使用するのガイドラインに従う必要があります。たとえば、関連する Google 検索語句を示すバナーを常に表示する必要があります。デベロッパー向け UI もこれらのルールに準拠しています。

例

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` - ウェブ UI で評価を実行する

エージェントは、ウェブベースの UI を使用してインタラクティブに評価できます。

手順:

bash af web を実行してウェブサーバーを起動します。
ウェブインターフェースで次の操作を行います。
- エージェントを選択します。
- [セッションをテストファイルとして保存] をクリックして、セッションをテストファイルとして保存します。
- [テストファイルを実行] をクリックすると、エージェントのフォルダにあるテストファイルを含むポップアップが表示されます。

テストファイル:

テストファイルは、エージェントと同じフォルダに保存されます。必要に応じて、テストファイルを手動で更新または追加できます。

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 パイプラインまたは大規模なテストスイートに統合できます。

エージェント フレームワーク チュートリアル コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。