OpenAPI 도구

에이전트는 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 함수를 호출할 권한이 있으면 최종 사용자에게 직접 액세스 권한이 없더라도 이 도구는 해당 서비스 계정에서 액세스할 수 있는 모든 함수를 호출할 수 있습니다.

이 동작과 관련된 잠재적 위험을 완화하려면 다음 단계를 따르세요.

전용 프로젝트 사용: 다른 중요 리소스나 민감한 기능과 별도로 전용 프로젝트에 에이전트 애플리케이션을 배포하는 것이 좋습니다. 이 격리로 인해 CX Agent Studio 서비스 계정에서 사용할 수 있는 권한의 범위가 제한됩니다.
VPC 서비스 제어 구현: VPC 서비스 제어를 사용하여 민감한 서비스 주변에 서비스 경계를 정의합니다. 이를 통해 Cloud Run 함수와 같은 서비스에 대한 액세스를 제어하고 CX Agent Studio 서비스 계정에서 원치 않는 호출을 방지할 수 있습니다.
최소 권한 준수: CX Agent Studio 서비스 계정에 의도된 기능에 필요한 최소한의 Identity and Access Management 역할과 권한만 부여해야 합니다.

API 인증

외부 API를 호출할 때 지원되는 인증 옵션은 다음과 같습니다.

서비스 에이전트 ID 토큰

CX Agent Studio는 Customer Engagement Suite 서비스 에이전트를 사용하여 ID 토큰을 생성할 수 있습니다. 토큰은 CX Agent Studio가 외부 API를 호출할 때 승인 HTTP 헤더에 추가됩니다.

Cloud Run 함수와 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}입니다. 도구 구성에 이 보안 비밀 버전을 사용합니다.