플레이북 도구

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

도구를 사용하여 플레이북을 외부 시스템에 연결할 수 있습니다. 이러한 시스템은 플레이북의 지식을 강화하고 복잡한 태스크를 효율적으로 실행할 수 있도록 지원합니다.

기본 제공 도구를 사용하거나 요구사항에 맞게 맞춤설정된 도구를 빌드할 수 있습니다.

도구 테스트

도구를 만들면 도구 테스트 기능을 사용하여 작동하는지 확인할 수 있습니다. 도구를 볼 때 도구 창 위의 테스트 버튼을 클릭합니다. 이렇게 하면 시뮬레이터에서 입력할 수 있는 도구가 열립니다. 도구 입력을 제공한 다음 View Output(출력 보기)을 클릭하여 올바른 도구 출력을 확인합니다.

예시 도구에 도구를 추가할 때 도구 테스트 기능을 사용할 수도 있습니다.

기본 제공 도구

기본 제공 도구는 Google이 호스팅하며, 수동 구성 없이 에이전트에서 이러한 도구를 활성화할 수 있습니다.

지원되는 기본 제공 도구는 다음과 같습니다.

• Code Interpreter: 코드 생성 및 코드 실행 기능을 결합하여 사용자가 데이터 분석, 데이터 시각화, 텍스트 처리, 방정식 풀이 또는 최적화 문제를 포함한 다양한 태스크를 수행할 수 있게 해주는 Google 퍼스트 파티 도구입니다.

에이전트는 언제 어떻게 이러한 도구를 호출해야 할지 최적화된 결정을 내릴 수 있지만, 사용 사례에 맞게 추가 예시를 제공할 수 있습니다.

예시에는 다음과 같은 스키마가 있어야 합니다.

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/df-code-interpreter-tool",
    "action": "generate_and_execute",
    "inputParameters": [
      {
        "name": "generate_and_execute input",
        "value": "4 + 4"
      }
    ],
    "outputParameters": [
      {
        "name": "generate_and_execute output",
        "value": {
          "output_files": [
            {
              "name": "",
              "contents": ""
            }
          ],
          "execution_result": "8",
          "execution_error": "",
          "generated_code": "GENERATED_CODE"
        }
      }
    ]
  }
}

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: Dialogflow session id
          required: false
          schema:
            $ref: "@dialogflow/sessionId"
      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

선택적으로 내부 스키마 참조 @dialogflow/sessionId를 매개변수 스키마 유형으로 사용할 수 있습니다. 이 파라미터 스키마 유형을 사용하면 현재 대화의 Dialogflow 세션 ID가 파라미터 값으로 제공됩니다. 예를 들면 다음과 같습니다.

- name: X-SESSION
   in: header
   description: Dialogflow session id
   required: false
   schema:
     $ref: "@dialogflow/sessionId"

OpenAPI 도구 제한사항

다음과 같은 제한사항이 적용됩니다.

• 지원되는 매개변수 유형은 path, query, header입니다. cookie 매개변수 유형은 아직 지원되지 않습니다.
• OpenAPI 스키마에서 정의되는 매개변수는 string, number, integer, boolean, array 데이터 유형을 지원합니다. object 유형은 아직 지원되지 않습니다.
• 현재 콘솔 예시 편집기에서 쿼리 매개변수를 지정할 수 없습니다.
• 요청 및 응답 본문은 비어 있거나 JSON이어야 합니다.

OpenAPI 도구 API 인증

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

• Dialogflow 서비스 에이전트 인증
  • Dialogflow는 Dialogflow 서비스 에이전트를 사용하여 ID 토큰 또는 액세스 토큰을 생성할 수 있습니다. 토큰은 Dialogflow가 외부 API를 호출할 때 승인 HTTP 헤더에 추가됩니다.
  • roles/cloudfunctions.invoker 및 roles/run.invoker 역할을 service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com에 부여한 후에 ID 토큰을 Cloud Run Functions 및 Cloud Run 서비스에 액세스하는 데 사용할 수 있습니다. Cloud Run Functions 및 Cloud Run 서비스가 같은 리소스 프로젝트에 있으면 호출하는 데 필요한 추가 IAM 권한은 없습니다.
  • service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com에 필요한 역할을 부여한 후 액세스 토큰을 다른 Google Cloud API에 액세스하는 데 사용할 수 있습니다.

• 서비스 계정 인증

  • 서비스 계정은 이를 지원하는 모든 Google API에 대한 도구 요청을 인증하는 데 사용할 수 있습니다. 서비스 계정은 주 구성원이므로 다른 주 구성원에게 역할을 부여했던 것과 마찬가지로 역할을 부여하여 프로젝트의 리소스에 액세스할 수 있습니다. 서비스 계정 이메일은 액세스 토큰을 생성하는 데 사용되며, 이 액세스 토큰은 도구 요청의 Authorization 헤더에 전송됩니다.

  • 이 기능을 사용하려면 다음 권한이 필요합니다.

    • roles/iam.serviceAccountUser 역할을 부여합니다.
    • roles/iam.serviceAccountTokenCreator 역할을 Dialogflow 서비스 에이전트에 부여합니다.

  • 여러 프로젝트에서 서비스 계정을 사용하려는 경우 조직 정책에서 지원하는지 확인합니다. 서비스 계정이 포함된 프로젝트에서 두 권한을 모두 부여해야 합니다.

• API 키

  • Dialogflow가 요청에서 API 키를 전달하도록 키 이름, 요청 위치(헤더 또는 쿼리 문자열), API 키를 제공하여 API 키 인증을 구성할 수 있습니다.
  • Secret Manager를 사용하여 API 키를 제공하는 것이 좋습니다.

• OAuth

  • OAuth 클라이언트 사용자 인증 정보 흐름은 서버 간 인증에 지원됩니다.

    • 이 흐름은 Agent Builder Console이 리소스 소유자이고 최종 사용자 승인이 필요하지 않은 경우 사용할 수 있습니다.
    • OAuth 제공업체의 클라이언트 ID, 클라이언트 보안 비밀번호, 토큰 엔드포인트는 Dialogflow에서 구성되어야 합니다.
      • Secret Manager를 사용하여 클라이언트 보안 비밀을 제공하는 것이 좋습니다.
    • Dialogflow는 OAuth 제공업체의 OAuth 액세스 토큰을 교환하여 요청의 인증 헤더에 전달합니다.

  • 승인 코드 플로우 및 PKCE 흐름과 같이 최종 사용자 승인이 필요한 다른 OAuth 흐름의 경우:

    1. 자체 로그인 UI를 구현하고 클라이언트 측에서 액세스 토큰을 가져와야 합니다.

    2. 이후 다음 작업 중 하나를 수행하면 됩니다.

       a. Bearer 토큰 인증 옵션을 사용하여 토큰을 OpenAPI 도구에 전달합니다. Dialogflow는 도구를 호출할 때 승인 헤더에 이 토큰을 포함합니다.

       b. 함수 도구를 사용하여 클라이언트 측에서 직접 도구를 호출하고 도구 호출 결과를 Dialogflow에 전달합니다.

• 베어러(Bearer) 토큰

  • 클라이언트에서 Bearer 토큰을 동적으로 전달하도록 베어러 인증을 구성할 수 있습니다. 이 토큰은 요청의 인증 헤더에 포함되어 있습니다.
  • 도구 인증을 설정할 때 베어러 토큰 역할을 할 세션 매개변수를 지정할 수 있습니다. 예를 들면 $session.params.<parameter-name-for-token>을 사용해 토큰을 지정하세요.
  • 런타임에 Bearer 토큰을 세션 매개변수에 할당합니다.

  DetectIntentRequest {
    ...
    query_params {
      parameters {
        <parameter-name-for-token>: <the-auth-token>
      }
    }
    ...
  }
  

  • 세션 매개변수에서 토큰을 가져오는 대신 정적 토큰을 구성해야 하는 경우 Secret Manager를 사용하여 토큰을 제공하는 것이 좋습니다.

• 상호 TLS 인증

  • 상호 TLS 인증 문서를 참조하세요.
  • 맞춤 클라이언트 인증서가 지원됩니다. 에이전트 설정의 보안 탭에서 에이전트 수준으로 클라이언트 인증서를 설정할 수 있습니다. 인증서 (PEM 형식) 및 비공개 키 (PEM 형식)는 필수 입력란입니다. 설정되면 이 클라이언트 인증서는 모든 도구 및 웹훅에 대한 상호 TLS 중에 사용됩니다.

• 커스텀 CA 인증서

  • 커스텀 CA 인증서 문서를 참조하세요.

Secret Manager 인증

OAuth, API 키 또는 Bearer 토큰을 사용하는 경우 Secret Manager를 사용하여 사용자 인증 정보를 보안 비밀로 저장할 수 있습니다. 다음은 보안 비밀을 사용하여 도구를 인증하는 데 필요한 단계입니다.

1. 아직 비밀번호가 없는 경우 비밀번호를 만듭니다.
2. 새 보안 비밀에 Dialogflow Service Agent에 Secret Manager 보안 비밀 접근자(roles/secretmanager.secretAccessor) 역할을 부여합니다.
3. 사용자 인증 정보를 클립보드에 복사합니다.
4. 보안 비밀에 새 보안 비밀 버전을 추가합니다. 사용자 인증 정보를 보안 비밀 값으로 붙여넣습니다.
   • 끝에 있는 줄바꿈 문자는 생략합니다.
5. 방금 추가한 보안 비밀 버전의 이름을 복사합니다. 이름 형식은 projects/{project_id}/secrets/{secret_id}/versions/{version_id}"입니다.
6. 도구 수정 화면을 연 다음 다음 단계를 따르세요.
   • OAuth를 사용하는 경우 인증 유형으로 OAuth를 선택한 다음 클라이언트 보안 비밀번호에서 보안 비밀 버전을 클릭하고 보안 비밀 버전 이름을 보안 비밀 버전 입력 상자에 붙여넣습니다.
   • API 키를 사용하는 경우 인증 유형으로 API 키를 선택한 다음 API 키 아래에서 보안 비밀 버전을 클릭합니다. 보안 비밀 버전 이름을 보안 비밀 버전 입력란에 붙여넣습니다.
   • 베어러 토큰을 사용하는 경우 인증 유형으로 베어러 토큰을 선택한 다음 베어러 토큰에서 보안 비밀 버전을 클릭합니다. 보안 비밀 버전 이름을 보안 비밀 버전 입력 상자에 붙여넣습니다.
7. 저장을 클릭합니다.

OpenAPI 도구 비공개 네트워크 액세스

OpenAPI 도구는 서비스 디렉터리 비공개 네트워크 액세스와 통합되므로 VPC 네트워크 내의 API 타겟에 연결할 수 있습니다. 이렇게 하면 트래픽이 Google Cloud 네트워크 내에서 유지되며 IAM 및 VPC 서비스 제어가 적용됩니다.

비공개 네트워크를 타겟팅하는 OpenAPI 도구를 설정하려면 다음 안내를 따르세요.

1. 서비스 디렉터리 비공개 네트워크 구성을 따라 VPC 네트워크와 서비스 디렉터리 엔드포인트를 구성합니다.

2. 에이전트 프로젝트에 다음 주소를 사용하는 Dialogflow Service Agent 서비스 계정이 있어야 합니다.

   service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

   Dialogflow 서비스 에이전트 서비스 계정에 다음 IAM 역할을 부여합니다.
   • 서비스 디렉터리 프로젝트의 servicedirectory.viewer
   • 네트워크 프로젝트의 servicedirectory.pscAuthorizedService

3. 도구를 만들 때 OpenAPI 스키마 및 선택적 인증 정보와 함께 서비스 디렉터리 서비스를 제공합니다.

OpenAPI 도구 세션 파라미터 액세스

Open API 도구 입력은 스키마를 가이드로 사용하여 사용자가 LLM과 나눈 대화에서 파생됩니다. 경우에 따라 입력은 흐름 중에 수집된 세션 파라미터에서 파생되거나 사용자 입력과 함께 쿼리 파라미터 입력으로 제공되어야 할 수 있습니다.

입력으로 전달해야 하는 세션 파라미터를 다음과 같이 지정할 수 있습니다.

     parameters:
       - in: query
         name: petId
         required: true
         description: Pet id
         schema:
           type: integer
           x-agent-input-parameter: petId # Reads from the $session.params.petId
       - in: header
         name: X-other
         schema:
           type: string
           x-agent-input-parameter: $request.payload.header # Reads from the header specified in the request payload input
     requestBody:
       required: false
       content:
         application/json:
           schema:
             type: object
             properties:
               name:
                 type: string
                 x-agent-input-parameter: petName # Reads from the $session.params.petName
                 description: Name of the person to greet (optional).
               breed:
                 type: string
                 description: Bread of the pet.

이러한 세션 파라미터를 사용할 수 없으면 LLM에서 생성한 입력이 도구에 전달됩니다.

OpenAPI 도구 기본값

Open API 스키마를 사용하여 기본값을 지정할 수 있습니다. 기본값은 해당 매개변수 또는 속성에 LLM에서 생성된 입력 값 또는 세션 매개변수 기반 입력 값이 없는 경우에만 사용됩니다.

기본값은 다음과 같이 스키마의 일부로 지정할 수 있습니다.

     parameters:
       - in: query
         name: zipcode
         required: true
         description: Zip code to search for
         schema:
           type: integer
           default: 94043
     requestBody:
       content:
         application/json:
           schema:
             type: object
             properties:
               breed:
                 type: string
                 description: Bread of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

LLM에서 생성한 값, 세션 매개변수 값 또는 기본값이 없으면 입력이 지정되지 않습니다.

데이터 스토어 도구

플레이북에서 데이터 스토어 도구를 사용하는 방법에 관한 자세한 내용은 데이터 스토어 도구 문서를 참고하세요.

커넥터 도구

상담사는 커넥터 도구를 사용하여 Integration Connectors에 구성된 연결을 사용하여 작업을 실행할 수 있습니다. 각 커넥터 도구는 단일 연결과 하나 이상의 작업으로 구성됩니다. 필요한 경우 상담사가 사용할 수 있도록 다양한 작업을 그룹화하기 위해 단일 연결에 여러 도구를 만들 수 있습니다.

커넥터 도구는 다음 커넥터 유형을 지원합니다.

• BigQuery
• CloudSQL - SQL Server
• Jira 서비스 관리
• Oracle DB
• PayPal
• Salesforce
• Salesforce Marketing Cloud
• ServiceNow
• SharePoint
• Stripe
• Zendesk

예시는 상담사가 도구를 호출하고 응답을 사용하는 방법을 보여주어 상담사가 커넥터 도구를 더 효과적으로 사용하는 데 사용해야 합니다.

연결 만들기

연결을 만들고 상담사에게 연결하려면 도구 > 만들기로 이동하여 커넥터 도구 유형과 선택한 커넥터 유형을 선택하고 연결 만들기 버튼을 사용합니다. 이렇게 하면 여러 필드가 미리 입력된 상태로 통합 커넥터 생성으로 이동합니다.

또는 Integration Connectors로 이동하여 연결을 만드는 안내를 따르세요.

커넥터 작업

각 커넥터 도구에는 상담사에게 제공할 수 있는 두 가지 유형의 작업이 있습니다 (자세한 내용은 항목, 작업, 작업 참고).

1. 항목 CRUD 작업
   
   각 연결에는 해당 데이터 소스의 객체에 해당하는 '항목'이 있습니다 (BigQuery의 경우 테이블, Salesforce의 경우 '주문' 또는 '케이스'와 같은 객체).
   
   각 항목에 대해 CRUD 작업을 실행할 수 있습니다.
   

   • 만들기: 지정된 필드 값으로 항목을 만듭니다.
     
   • 목록: 항목 인스턴스의 필터 기반 검색
     
   • 업데이트: 항목 필드 값을 변경하는 필터 기반 메서드
     
   • 삭제: 항목을 삭제합니다.
     
   • Get은 entityId
     를 사용하여 단일 항목을 검색합니다.

   커넥터 문서에서 항목 CRUD 작업 세부정보에 대해 자세히 알아보세요.

2. 커넥터별 작업
   
   많은 커넥터는 각 데이터 소스 항목을 테이블로 참조할 수 있는 데이터 소스에 대해 SQL 쿼리를 실행할 수 있는 'ExecuteCustomQuery' 작업을 지원합니다. 지원되는 커넥터 목록을 확인하세요.
   
   추가 작업은 커넥터 유형에 따라 다릅니다. 예를 들어 BigQuery 커넥터 작업 또는 Salesforce 커넥터 작업을 참고하세요.

CRUD 작업의 입력 / 출력 필드 구성

커넥터 도구 작업에서 사용할 특정 입력 또는 출력 필드를 선택하면 상담사의 이러한 작업의 복잡성을 제한할 수 있습니다.

예를 들어 필드의 하위 집합으로 항목을 만들기만 하면 되는 경우 작업에서 이 필드 집합을 구성하면 에이전트의 작업이 간소화됩니다.

출력 필드 집합을 지정하면 도구 응답 크기가 줄어들고 (토큰 한도가 우려되는 경우 유용) 관련 필드만 노출하여 에이전트의 출력 처리가 간소화됩니다.

인증

사용 중인 연결이 인증 재정의를 허용하도록 구성된 경우 지정된 세션 매개변수의 사용자 인증 정보를 전달하도록 도구를 구성할 수 있습니다.

에이전트 빌더는 이러한 사용자 인증 정보가 세션 매개변수에 채워지는 방식을 담당하며, 도구의 작업이 호출될 때 도구는 인증에 사용할 데이터 소스에 자동으로 전달합니다.

함수 도구

클라이언트 코드에서는 액세스할 수 있지만 OpenAPI 도구에서는 액세스할 수 없는 기능이 있으면 함수 도구를 사용할 수 있습니다. 함수 도구는 항상 에이전트가 아닌 클라이언트 측에서 실행됩니다.

프로세스는 다음과 같습니다.

1. 클라이언트 코드가 인텐트 인식 요청을 전송합니다.
2. 에이전트에서 함수 도구가 필요함을 감지하고 인텐트 인식 응답에는 입력 인수와 함께 도구 이름이 포함됩니다. 이 세션은 도구 결과로 또 다른 인텐트 인식 요청이 수신될 때까지 일시중지됩니다.
3. 클라이언트 코드에서 도구를 호출합니다.
4. 클라이언트 코드는 도구 결과를 출력 인수로 제공하는 또 다른 인텐트 인식 요청을 보냅니다.

다음 예시에서는 함수 도구의 입력 및 출력 스키마를 보여줍니다.

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, for example, San Francisco, CA"
    }
  },
  "required": [
    "location"
  ]
}

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "The temperature"
    }
  }
}

다음 예시는 REST를 사용한 초기 인텐트 인식 요청 및 응답을 보여줍니다.

HTTP method and URL:
POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent
{
  "queryInput": {
    "text": {
      "text": "what is the weather in Mountain View"
    },
    "languageCode": "en"
  }
}

{
  "queryResult": {
    "text": "what is the weather in Mountain View",
    "languageCode": "en",
    "responseMessages": [
      {
        "source": "VIRTUAL_AGENT",
        "toolCall": {
          "tool": "<tool-resource-name>",
          "action": "get-weather-tool",
          "inputParameters": {
            "location": "Mountain View"
          }
        }
      }
    ]
  }
}

다음 예시는 도구 결과를 제공하는 두 번째 인텐트 인식 요청을 보여줍니다.

{
  "queryInput": {
    "toolCallResult": {
      "tool": "<tool-resource-name>",
      "action": "get-weather-tool",
      "outputParameters": {
        "temperature": 28.0
      }
    },
    "languageCode": "en"
  }
}

클라이언트 측 실행

함수 도구와 마찬가지로 OpenAPI 및 데이터 스토어 도구는 세션과 상호작용할 때 API 재정의를 적용하여 클라이언트 측에서 실행할 수 있습니다.

예를 들면 다음과 같습니다.

DetectIntentRequest {
  ...
  query_params {
    playbook_state_override {
      playbook_execution_mode: ALWAYS_CLIENT_EXECUTION
    }
  }
  ...
}

프로세스는 다음과 같습니다.

1. 클라이언트 코드는 클라이언트 실행을 지정하는 인텐트 인식 요청을 전송합니다.
2. 에이전트에서 도구가 필요함을 감지하고 인텐트 인식 응답에는 도구 이름과 입력 인수가 포함됩니다. 이 세션은 도구 결과로 또 다른 인텐트 인식 요청이 수신될 때까지 일시중지됩니다.
3. 클라이언트 코드에서 도구를 호출합니다.
4. 클라이언트 코드는 도구 결과를 출력 인수로 제공하는 또 다른 인텐트 인식 요청을 보냅니다.