API로 상호작용

대화 차례마다 상호작용이 발생합니다. 상호작용 중에 최종 사용자가 에이전트 앱에 입력을 보내고 에이전트 앱이 응답을 보냅니다. Vertex AI Agents API를 사용하여 런타임 시 에이전트 앱과 상호작용할 수 있습니다.

시작하기 전에

이 가이드를 읽기 전에 다음을 수행해야 합니다.

새 에이전트 앱을 만들거나 에이전트 앱 만들기에서 만든 에이전트 앱을 계속 사용합니다.

ID 수집

아래 샘플에서는 여러 ID가 입력으로 필요합니다. 프로젝트 ID, 리전 ID, 앱 ID를 찾으려면 다음 안내를 따르세요.

에이전트 빌더 콘솔로 이동합니다.

에이전트 빌더 콘솔
프로젝트 ID가 콘솔 상단에 표시됩니다.
위치 열에는 리전 ID가 표시됩니다.
앱을 선택합니다.
agents/ 뒤의 브라우저 URL 경로 세그먼트에 에이전트 앱 ID가 있습니다.

세션 ID도 필요합니다. 세션은 에이전트 앱과 최종 사용자 간의 대화를 나타냅니다. 대화를 시작할 때 고유한 세션 ID를 만들고 대화 차례마다 이 세션을 사용합니다. API를 살펴보기 위해 최대 36바이트의 문자열 ID를 사용할 수 있습니다(예: test-session-123).

인텐트 인식 호출

다음 샘플은 Sessions.detectIntent 메서드를 호출합니다.

세션 참조의 프로토콜 및 버전을 선택합니다.

프로토콜	V3	V3beta1
REST	세션 리소스	세션 리소스
RPC	세션 인터페이스	세션 인터페이스
C++	SessionsClient	해당 사항 없음
C#	SessionsClient	해당 사항 없음
Go	SessionsClient	해당 사항 없음
자바	SessionsClient	SessionsClient
Node.js	SessionsClient	SessionsClient
PHP	없음	해당 사항 없음
Python	SessionsClient	SessionsClient
Ruby	없음	해당 사항 없음

REST

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

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
AGENT_ID: 플레이북 에이전트 ID로, Dialogflow 에이전트 ID에 해당합니다.
REGION_ID: 리전 ID
SUBDOMAIN_REGION: 리전 ID가 us이면 하위 도메인 리전이 usa이고, 그 외의 경우 하위 도메인 리전은 리전 ID와 동일합니다.
SESSION_ID: 세션 ID
END_USER_INPUT: 최종 사용자 입력(예: 셔츠를 사고 싶습니다.)

HTTP 메서드 및 URL:

POST https://SUBDOMAIN_REGION-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent

JSON 요청 본문:

{
  "queryInput": {
    "text": {
      "text": "END_USER_INPUT"
    },
    "languageCode": "en"
  },
  "queryParams": {
    "timeZone": "America/Los_Angeles"
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 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 "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://SUBDOMAIN_REGION-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://SUBDOMAIN_REGION-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/REGION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "responseId": "a6cd27b0-5eaa-4f93-aa6e-11faf97dbb63",
  "queryResult": {
    "text": "I want to buy a shirt",
    "languageCode": "en",
    "responseMessages": [
      {
        "text": {
          "text": [
            "Great! I can help you with that. We have a wide variety of shirts to choose from. What size and color would you like?"
          ]
        }
      }
    ],
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {
      "Session Id": "123",
      "Response Id": "a6cd27b0-5eaa-4f93-aa6e-11faf97dbb63"
    },
    "match": {
      "confidence": 1
    },
    "advancedSettings": {
      "loggingSettings": {}
    }
  },
  "responseType": "FINAL"
}

에이전트 앱 만들기

에이전트 앱