Google Cloud コンソールまたは API 呼び出しを使用してセッションを管理する

このセクションでは、Agent Platform セッションで Google Cloud コンソールまたは API 呼び出しを直接使用してセッションを管理する方法について説明します。ADK エージェントを使用してセッションを管理しない場合は、 Google Cloud コンソールまたは直接 API 呼び出しを使用できます。

ADK エージェントを使用してセッションを管理するには、Agent Development Kit でセッションを管理するをご覧ください。

Agent Runtime インスタンスを作成する

Agent Platform セッションにアクセスするには、まず Agent Runtime インスタンスを使用する必要があります。セッションの使用を開始するためにコードをデプロイする必要はありません。Agent Engine を使用したことがある場合、コードをデプロイしなくても、Agent Runtime インスタンスの作成には数秒しかかかりません。Agent Engine を初めて使用する場合は、時間がかかることがあります。

既存の Agent Runtime インスタンスがない場合は、次のコードを使用して作成します。

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have an Agent Engine instance already, create an instance.
agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Engine resource name. You will need the
# resource name to interact with Sessions later on.
print(agent_engine.api_resource.name)

次のように置き換えます。

• PROJECT_ID: プロジェクト ID。
• LOCATION: リージョン。Sessions のサポートされているリージョンをご覧ください。

セッションを一覧表示する

Agent Runtime インスタンスに関連付けられているセッションを一覧表示します。

コンソール

デプロイされたエージェントの場合は、 Google Cloud コンソールを使用して、エージェントに関連付けられているセッションを一覧表示できます。

1. Google Cloud コンソールで、Agent Platform の [デプロイ] ページに移動します。
   

   [デプロイメント] に移動

   選択したプロジェクトの一部である Agent Engine インスタンスがリストに表示されます。[フィルタ] フィールドを使用して、指定した列でリストをフィルタできます。

2. Agent Engine インスタンスの名前をクリックします。

3. [セッション] タブをクリックします。セッションのリストが ID 別に表示されます。

Python

for session in client.agent_engines.sessions.list(
    name=agent_engine.api_resource.name,  # Required
):
    print(session)

# To list sessions for a specific user:
for session in client.agent_engines.sessions.list(
    name=agent_engine.api_resource.name,  # Required
    config={"filter": "user_id=USER_ID"},
):
    print(session)

• USER_ID: 128 文字以内のユーザー ID を選択します。例: user-123

REST

リクエストのデータを使用する前に、次のように置き換えます。

• PROJECT_ID: プロジェクト ID。
• LOCATION: Agent Engine インスタンスを作成したリージョン。
• AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand Content

返されたセッションのリストが表示されます。

必要に応じて、特定のユーザーのセッションを一覧表示するには、クエリ パラメータ ?filter=user_id=\"USER_ID\" を追加します。ここで、USER_ID はクエリするユーザーの ID です。

セッションを作成する

ユーザー ID に関連付けられたセッションを作成します。

コンソール

デプロイされたエージェントの場合、 Google Cloud コンソールを使用してセッションを作成できます。

1. Google Cloud コンソールで、Agent Platform の [デプロイ] ページに移動します。
   

   [デプロイメント] に移動

   選択したプロジェクトの一部である Agent Engine インスタンスがリストに表示されます。[フィルタ] フィールドを使用して、指定した列でリストをフィルタできます。

2. Agent Engine インスタンスの名前をクリックします。

3. [Playground] タブをクリックします。

4. [新しいセッション] をクリックして、新しいセッションを作成します。

Python

session = client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
    session_id=SESSION_ID,
)

ここで、USER_ID は定義したユーザー ID です。例: user-123

SESSION_ID の場合は、システム生成 ID との競合を避けるため、次の制限事項を考慮してください。

• 最初の文字が英字の場合、ID は最大 63 文字にできます。有効な文字は、英小文字、数字、ハイフン（[a-z0-9-]）です。最後の文字は英字または数字にする必要があります。
• 最初の文字が数字の場合、ID は最大 9 文字まで使用できます。有効な文字は、先頭にゼロが付かない数字（[0-9]）です。

REST

リクエストのデータを使用する前に、次のように置き換えます。

• PROJECT_ID: プロジェクト ID。
• LOCATION: Agent Engine インスタンスを作成したリージョン。
• AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
• USER_ID: 定義したユーザー ID。例: sessions-agent
• SESSION_ID: 定義したセッション ID。たとえば、my-custom-session です。

  システム生成 ID との競合を回避するため、カスタム セッション ID を指定する際は、次の制限事項に従ってください。

  • 最初の文字が英字の場合、ID の長さは最大 63 文字です。有効な文字は、英小文字、数字、ハイフン（`[a-z0-9-]`）です。最後の文字は英字または数字にする必要があります。
  • 最初の文字が数字の場合、ID の長さは最大 9 文字です。有効な文字は、先頭にゼロのない数字（`[0-9]`）です。

  HTTP メソッドと URL:

  POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

  リクエストの本文（JSON）:

  {
    "userId": USER_ID
  }
  
  

  リクエストを送信するには、次のいずれかのオプションを選択します。

  curl

  注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

  リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

  curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d @request.json \
       "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"

  PowerShell

  注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

  リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

  $cred = gcloud auth print-access-token
  $headers = @{ "Authorization" = "Bearer $cred" }
  
  Invoke-WebRequest `
      -Method POST `
      -Headers $headers `
      -ContentType: "application/json; charset=utf-8" `
      -InFile request.json `
      -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand Content

  長時間実行オペレーションが返されます。このオペレーションをクエリで使用してセッションの作成ステータスを確認します。

セッションの有効期間（TTL）を構成する

すべてのセッションに有効期限が必要です。この有効期限は、セッションの作成時または更新時に定義できます。セッションとその子イベントは、有効期限が切れると自動的に削除されます。有効期限（expire_time）を直接設定するか、有効期間（ttl）を秒単位で設定できます。どちらも指定されていない場合、システムはデフォルトの TTL（365 日）を適用します。

有効期間（TTL）

有効期間を設定すると、サーバーは新規作成されたセッションの有効期限を create_time + ttl、更新されたセッションの有効期限を update_time + ttl として計算します。

client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
    config={
        # Session will be deleted 10 days after creation time.
        "ttl": f"{24 * 60 * 60 * 10}s"
    }
)

有効期限

import datetime

client.agent_engines.sessions.create(
    name=agent_engine.api_resource.name,  # Required
    user_id=USER_ID, # Required
    config={
        # Session will be deleted at the provided time (10 days after current time).
        "expire_time": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(seconds=24 * 60 * 60 * 10),
    }
)

セッションを取得する

Agent Platform インスタンスに関連付けられている特定のセッションを取得します。

コンソール

デプロイされたエージェントの場合、 Google Cloud コンソールを使用してセッションを作成できます。

1. Google Cloud コンソールで、Agent Platform の [デプロイ] ページに移動します。
   

   [デプロイメント] に移動

   選択したプロジェクトの一部である Agent Engine インスタンスがリストに表示されます。[フィルタ] フィールドを使用して、指定した列でリストをフィルタできます。

2. Agent Engine インスタンスの名前をクリックします。

3. [Playground] タブをクリックします。

4. [セッション] タブをクリックします。セッションのリストが ID 別に表示されます。

5. 詳細を表示するセッションをクリックします。

Python

session = client.agent_engines.sessions.get(
    name='projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID',  # Required
    user_id=USER_ID, # Required
)
# session.name will correspond to
#   'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID'

REST

リクエストのデータを使用する前に、次のように置き換えます。

• PROJECT_ID: プロジェクト ID。
• LOCATION: Agent Engine インスタンスを作成したリージョン。
• AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
• SESSION_ID: 取得するセッションのリソース ID。セッション ID は、セッションの作成時に受信したレスポンスから取得できます。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID" | Select-Object -Expand Content

レスポンスにセッションに関する情報が表示されます。

セッションを削除する

Agent Platform インスタンスに関連付けられているセッションを削除します。

コンソール

デプロイされたエージェントの場合は、 Google Cloud コンソールを使用して、エージェントに関連付けられたセッションを削除できます。

1. Google Cloud コンソールで、Agent Platform の [デプロイ] ページに移動します。
   

   [デプロイメント] に移動

   選択したプロジェクトの一部である Agent Engine インスタンスがリストに表示されます。[フィルタ] フィールドを使用して、指定した列でリストをフィルタできます。

2. Agent Engine インスタンスの名前をクリックします。

3. [セッション] タブをクリックします。セッションのリストが ID 別に表示されます。

4. 削除するセッションの [その他の操作] メニュー（）をクリックします。

5. [削除] をクリックします。

6. [セッションを削除] をクリックします。

Python

client.agent_engines.sessions.delete(name=session.name)

REST

リクエストのデータを使用する前に、次のように置き換えます。

• PROJECT_ID: プロジェクト ID。
• LOCATION: Example Store インスタンスを作成するリージョン。
• AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
• SESSION_ID: 取得するセッションのリソース ID。

HTTP メソッドと URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID" | Select-Object -Expand Content

成功したことを示すステータス コード（2xx）と空のレスポンスが返されます。

セッションのイベントを一覧表示する

Agent Platform インスタンスに関連付けられているセッションのイベントを一覧表示します。

コンソール

デプロイされたエージェントの場合、 Google Cloud コンソールを使用してセッションを作成できます。

1. Google Cloud コンソールで、Agent Platform の [デプロイ] ページに移動します。
   

   [デプロイメント] に移動

   選択したプロジェクトの一部である Agent Engine インスタンスがリストに表示されます。[フィルタ] フィールドを使用して、指定した列でリストをフィルタできます。

2. Agent Engine インスタンスの名前をクリックします。

3. [Playground] タブをクリックします。

4. [セッション] タブをクリックします。セッションのリストが ID 別に表示されます。

5. 詳細を表示するセッションをクリックします。

6. [イベント] タブをクリックして、セッションに関連付けられたイベントを表示します。

Python

for session_event in client.agent_engines.list_session_events(
    name=session.name,
):
    print(session_event)

REST

リクエストのデータを使用する前に、次のように置き換えます。

• PROJECT_ID: プロジェクト ID。
• LOCATION: Agent Engine インスタンスを作成したリージョン。
• AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
• SESSION_ID: 取得するセッションのリソース ID。

HTTP メソッドと URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events"

PowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions/SESSION_ID/events" | Select-Object -Expand Content

レスポンスには、セッションに関連付けられているイベントのリストが表示されます。

セッションにイベントを追加する

Agent Platform インスタンスに関連付けられているセッションにイベントを追加します。

コンソール

デプロイされたエージェントの場合、 Google Cloud コンソールを使用してセッションを作成できます。

1. Google Cloud コンソールで、Agent Platform の [デプロイ] ページに移動します。
   

   [デプロイメント] に移動

   選択したプロジェクトの一部である Agent Engine インスタンスがリストに表示されます。[フィルタ] フィールドを使用して、指定した列でリストをフィルタできます。

2. Agent Engine インスタンスの名前をクリックします。

3. [Playground] タブをクリックします。

4. [セッション] タブをクリックします。セッションのリストが ID 別に表示されます。

5. 詳細を表示するセッションをクリックします。

6. [イベント] タブをクリックして、セッションに関連付けられたイベントを表示します。

7. [メッセージを入力] し、Enter キーを押して、セッションに新しいイベントを追加します。

Python

import datetime

client.agent_engines.sessions.events.append(
    name=session.name,
    author="user",                                              # Required.
    invocation_id="1",                                          # Required.
    timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required.
    config={
        "content": {
            "role": "user",
            "parts": [{"text": "hello"}]
        },
    },
)

または、raw_event フィールドを使用して、セッション イベントに任意のデータを含めることもできます。これは、他のエージェント フレームワークとの相互運用性やカスタム イベントデータの保存に役立ちます。

client.agent_engines.sessions.events.append(
    name=session.name,
    author="user",                                              # Required.
    invocation_id="1",                                          # Required.
    timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required.
    config={
        "raw_event": {
            "content": "hello",
            "custom_field": "custom_value"
        },
    },
)

REST

リクエストのデータを使用する前に、次のように置き換えます。

• PROJECT_ID: プロジェクト ID。
• LOCATION: Agent Engine インスタンスを作成したリージョン。
• AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
• USER_ID: 定義したユーザー ID。例: sessions-agent
• SESSION_ID: 定義したセッション ID。たとえば、my-custom-session です。

  システム生成 ID との競合を回避するため、カスタム セッション ID を指定する際は、次の制限事項に従ってください。

  • 最初の文字が英字の場合、ID の長さは最大 63 文字です。有効な文字は、英小文字、数字、ハイフン（`[a-z0-9-]`）です。最後の文字は英字または数字にする必要があります。
  • 最初の文字が数字の場合、ID の長さは最大 9 文字です。有効な文字は、先頭にゼロのない数字（`[0-9]`）です。

  HTTP メソッドと URL:

  POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions

  リクエストの本文（JSON）:

  {
    "userId": USER_ID
  }
  
  

  リクエストを送信するには、次のいずれかのオプションを選択します。

  curl

  注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザー アカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

  リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

  curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d @request.json \
       "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions"

  PowerShell

  注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザー アカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

  リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

  $cred = gcloud auth print-access-token
  $headers = @{ "Authorization" = "Bearer $cred" }
  
  Invoke-WebRequest `
      -Method POST `
      -Headers $headers `
      -ContentType: "application/json; charset=utf-8" `
      -InFile request.json `
      -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/AGENT_ENGINE_ID/sessions" | Select-Object -Expand Content

  長時間実行オペレーションが返されます。このオペレーションをクエリで使用してセッションの作成ステータスを確認します。

クリーンアップ

このプロジェクトで使用されているすべてのリソースをクリーンアップするには、Agent Platform インスタンスとその子リソースを削除します。

agent_engine.delete(force=True)