direct API 呼び出しを使用してセッションを管理する

このセクションでは、Vertex AI Agent Engine セッションで API 呼び出しを直接使用してセッションを管理する方法について説明します。ADK エージェントを使用してセッションを管理しない場合は、API を直接呼び出すことができます。

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

Vertex AI Agent Engine インスタンスを作成する

Vertex AI Agent Engine セッションにアクセスするには、Vertex AI Agent Engine インスタンスを使用する必要があります。セッションの使用を開始するためにコードをデプロイする必要はありません。コードをデプロイしない場合、Vertex AI Agent Engine インスタンスの作成にはわずか数秒しかかかりません。

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

import vertexai

client = vertexai.Client(project=PROJECT, location=LOCATION)
agent_engine = client.agent_engines.create()

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

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

Vertex AI SDK for 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)

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

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

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

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

$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 です。

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

セッションを作成する

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

Vertex AI SDK for Python

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

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

REST

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

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: Agent Engine インスタンスを作成したリージョン。
  • AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
  • USER_ID: 定義したユーザー ID。例: sessions-agent

HTTP メソッドと URL:

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

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

{
  "userId": USER_ID
}

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

curl

リクエスト本文を 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

リクエスト本文を 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

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

セッションを取得する

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

Vertex AI SDK for 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

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

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

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

$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

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

セッションを削除する

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

Vertex AI SDK for 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

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

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

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

$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）と空のレスポンスが返されます。

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

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

Vertex AI SDK for 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

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

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

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

$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

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

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

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

Vertex AI SDK for 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"}]
        },
    },
)

REST

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

  • PROJECT_ID: プロジェクト ID。
  • LOCATION: Agent Engine インスタンスを作成したリージョン。
  • AGENT_ENGINE_ID: Agent Engine インスタンスのリソース ID。
  • SESSION_ID: イベントを追加するセッションのリソース ID。
  • AUTHOR: イベントの作成者。'user' またはエージェント名を指定できます。
  • INVOCATION_ID: 呼び出しの ID。
  • TIMESTAMP: イベントのタイムスタンプ。

HTTP メソッドと URL:

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

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

{
  "author": AUTHOR,
  "invocationId": INVOCATION_ID,
  "timestamp": TIMESTAMP,
}

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

curl

リクエスト本文を 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/SESSION_ID"

PowerShell

リクエスト本文を 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/SESSION_ID" | Select-Object -Expand Content

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