직접 API 호출을 사용하여 세션 관리

이 섹션에서는 Vertex AI Agent Engine 세션을 사용하여 직접 API 호출을 통해 세션을 관리하는 방법을 설명합니다. ADK 에이전트를 사용하여 세션을 관리하지 않으려면 직접 API를 호출하면 됩니다.

ADK 에이전트를 사용하여 세션을 관리하려면 에이전트 개발 키트로 세션 관리를 참조하세요.

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 인스턴스와 연결된 모든 세션을 나열합니다.

Python용 Vertex AI SDK

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

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 에이전트 엔진 인스턴스를 만든 리전입니다.
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

반환된 세션 목록이 표시됩니다.

세션 만들기

사용자 ID와 연결된 세션을 만듭니다.

Python용 Vertex AI SDK

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

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 에이전트 엔진 인스턴스를 만든 리전입니다.
AGENT_ENGINE_ID: Agent Engine 인스턴스의 리소스 ID입니다.
USER_ID: 사용자 ID

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 인스턴스와 연결된 특정 세션을 가져옵니다.

Python용 Vertex AI SDK

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_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 인스턴스와 연결된 세션을 삭제합니다.

Python용 Vertex AI SDK

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 인스턴스와 연결된 세션의 이벤트를 나열합니다.

Python용 Vertex AI SDK

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

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID입니다.
LOCATION: 에이전트 엔진 인스턴스를 만든 리전입니다.
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 인스턴스와 연결된 세션에 이벤트를 추가합니다.

Python용 Vertex AI SDK

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_ID: Agent Engine 인스턴스의 리소스 ID입니다.
SESSION_ID: 이벤트를 추가할 세션의 리소스 ID입니다.
AUTHOR: 이벤트의 작성자입니다. 'user' 또는 에이전트 이름일 수 있습니다.
INVOCATION_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)와 빈 응답을 받게 됩니다.

직접 API 호출을 사용하여 세션 관리 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

Vertex AI Agent Engine 인스턴스 만들기

세션 나열

Python용 Vertex AI SDK

REST

curl

PowerShell

세션 만들기

Python용 Vertex AI SDK

REST

curl

PowerShell

세션 가져오기

Python용 Vertex AI SDK

REST

curl

PowerShell

세션 삭제

Python용 Vertex AI SDK

REST

curl

PowerShell

세션의 이벤트 나열

Python용 Vertex AI SDK

REST

curl

PowerShell

세션에 이벤트 추가

Python용 Vertex AI SDK

REST

curl

PowerShell

직접 API 호출을 사용하여 세션 관리