에이전트는 OpenAPI 스키마를 제공하여 OpenAPI 도구를 통해 외부 API에 연결할 수 있습니다. 에이전트는 사용자를 대신해 API를 호출합니다.
제한사항:
- 각 OpenAPI 도구에는 하나의 작업 또는 함수만 있을 수 있습니다.
스키마 예시:
openapi: 3.0.0
info:
title: Simple Pets API
version: 1.0.0
servers:
- url: 'https://api.pet-service-example.com/v1'
paths:
/pets/{petId}:
get:
summary: Return a pet by ID.
operationId: getPet
parameters:
- in: path
name: petId
required: true
description: Pet id
schema:
type: integer
responses:
200:
description: OK
/pets:
get:
summary: List all pets
operationId: listPets
parameters:
- name: petName
in: query
required: false
description: Pet name
schema:
type: string
- name: label
in: query
description: Pet label
style: form
explode: true
required: false
schema:
type: array
items:
type: string
- name: X-OWNER
in: header
description: Optional pet owner provided in the HTTP header
required: false
schema:
type: string
- name: X-SESSION
in: header
description: session id
required: true
schema:
type: string
x-ces-session-context: $context.session_id
responses:
'200':
description: An array of pets
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Pet'
post:
summary: Create a new pet
operationId: createPet
requestBody:
description: Pet to add to the store
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
responses:
'201':
description: Pet created
content:
application/json:
schema:
$ref: '#/components/schemas/Pet'
components:
schemas:
Pet:
type: object
required:
- id
- name
properties:
id:
type: integer
format: int64
name:
type: string
owner:
type: string
label:
type: array
items:
type: string
세션 컨텍스트 변수 삽입
세션 ID와 같은 세션 컨텍스트의 변수를 OpenAPI 요청에 삽입할 수 있습니다.
매개변수 정의 내에서 x-ces-session-context 확장 프로그램 필드를 사용합니다.
값은 context 객체 내의 변수 경로여야 합니다.
자세한 내용은 세션 컨텍스트 변수를 참조하세요.
예를 들면 다음과 같습니다.
parameters:
- name: X-SESSION
in: header
description: session id
required: true
schema:
type: string
# This extension injects the session ID
x-ces-session-context: $context.session_id
보안 고려사항
OpenAPI 도구를 구성할 때는 권한이 처리되는 방식을 이해하는 것이 중요합니다.
- 도구 실행 ID: OpenAPI 도구에서 수행하는 작업은 에이전트와 상호작용하는 최종 사용자의 직접 권한이 아닌 CX Agent Studio 서비스 계정에 부여된 권한을 사용하여 실행됩니다.
- 전이적 액세스 위험: 즉, CX Agent Studio 서비스 계정에 Cloud Run Functions를 호출할 수 있는 권한이 있는 경우 최종 사용자에게 직접 액세스 권한이 없더라도 도구에서 해당 서비스 계정으로 액세스할 수 있는 모든 함수를 호출할 수 있습니다.
이 동작과 관련된 잠재적 위험을 완화하려면 다음 단계를 따르세요.
- 전용 프로젝트 사용: 다른 중요한 리소스나 민감한 함수와 별도로 전용 프로젝트에 에이전트 애플리케이션을 배포하는 것이 좋습니다. 이 격리는 CX Agent Studio 서비스 계정에 사용할 수 있는 권한 범위를 제한합니다.
- VPC 서비스 제어 구현: VPC 서비스 제어를 활용하여 민감한 서비스 주변에 서비스 경계를 정의합니다. 이렇게 하면 Cloud Run Functions와 같은 서비스에 대한 액세스를 제어하고 CX Agent Studio 서비스 계정에서 원치 않는 호출을 방지할 수 있습니다.
- 최소 권한 원칙 준수: CX Agent Studio 서비스 계정에 의도된 기능에 필요한 최소한의 Identity and Access Management 역할 및 권한만 부여해야 합니다.
API 인증
외부 API를 호출할 때 지원되는 인증 옵션은 다음과 같습니다.
서비스 에이전트 ID 토큰
CX Agent Studio는 Customer Engagement Suite 서비스 에이전트(형식: service-{PROJECT_NUMBER}@gcp-sa-ces.iam.gserviceaccount.com)를 사용하여 ID 토큰을 생성할 수 있습니다. 토큰은 CX Agent Studio가 외부 API를 호출할 때 승인 HTTP 헤더에 추가됩니다.
Cloud Run Functions와 Cloud Run 서비스가 에이전트와 동일한 프로젝트에 있으면 이를 호출하는 데 추가 IAM 권한이 필요하지 않습니다. 서로 다른 프로젝트에 있는 경우 서비스 에이전트 주소에 roles/cloudfunctions.invoker 및 roles/run.invoker 역할을 부여한 후 ID 토큰을 사용하여 Cloud Run Functions 및 Cloud Run 서비스에 액세스할 수 있습니다.
서비스 계정 인증
서비스 계정은 이를 지원하는 모든 Google API에 대한 도구 요청을 인증하는 데 사용할 수 있습니다. 서비스 계정 이메일 주소를 입력합니다.
아직 계정이 없다면 서비스 계정을 만드세요.
서비스 계정은 주 구성원이므로
다른 주 구성원에게 역할을 부여했던 것과
마찬가지로 서비스 계정에
역할을 부여하여 프로젝트의
리소스에 액세스하도록 할 수 있습니다.
서비스 계정 이메일은 도구 요청의 Authorization 헤더에 전송되는 액세스 토큰을 생성하는 데 사용됩니다.
서비스 계정을 사용하도록 도구를 구성하는 사용자에게는 다음 권한이 있어야 합니다.
roles/iam.serviceAccountUser
Dialogflow CX에서 토큰을 생성하려면 Customer Engagement Suite 서비스 에이전트에 다음 권한이 있어야 합니다.
roles/iam.serviceAccountTokenCreator
서비스 계정에는 도구를 호스팅하는 서비스에 액세스할 수 있는 권한도 있어야 합니다.
OAuth
사용 중인 서비스의 OAuth 정보를 제공합니다.
Google 서비스에 OAuth를 사용하는 경우 서비스에 OAuth를 구성해야 합니다.
API 키
CX Agent Studio가 요청에서 API 키를 전달하도록 키 이름, 요청 위치(헤더 또는 쿼리 문자열), API 키를 제공하여 API 키 인증을 구성할 수 있습니다. Secret Manager 보안 비밀 버전을 사용하여 API 키를 제공합니다.
Secret Manager 인증
Secret Manager를 사용하여 사용자 인증 정보를 보안 비밀로 저장할 수 있습니다. 보안 비밀을 사용하여 도구를 인증하는 데 필요한 단계는 다음과 같습니다.
- 아직 보안 비밀이 없으면 보안 비밀을 만듭니다.
- Customer Engagement Suite 서비스 에이전트에 새 보안 비밀에 대한 Secret Manager 보안 비밀 접근자(
roles/secretmanager.secretAccessor) 역할을 부여합니다. - 사용자 인증 정보를 클립보드에 복사합니다.
- 보안 비밀에 새 보안 비밀 버전을 추가합니다. 사용자 인증 정보를 보안 비밀 값으로 붙여넣습니다.
- 끝에 있는 줄바꿈 문자는 생략합니다.
- 방금 추가한 보안 비밀 버전의 이름을 복사합니다. 이름 형식은
projects/{project_id}/secrets/{secret_id}/versions/{version_id}입니다. 도구 구성에 이 보안 비밀 버전을 사용합니다.
Bearer 토큰
OpenAPI 도구 요청의 Authorization 헤더에 있는 세션 컨텍스트 변수에 저장된 Bearer 토큰을 전달하도록 Bearer 토큰 인증을 구성할 수 있습니다. 이 옵션은 에이전트가 최종 사용자로부터 수집한 토큰을 다른 API에 전달해야 할 때 유용합니다.
세션 컨텍스트 변수를 $context.variables.VARIABLE_NAME 형식으로 지정합니다. 여기서 VARIABLE_NAME은 Bearer 토큰을 저장하는 변수의 이름입니다.