도구

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

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

제한사항

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

기본 제공 도구

기본 제공 도구는 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에 액세스하는 데 사용할 수 있습니다.
  • API 키
    • Dialogflow가 요청에서 API 키를 전달하도록 키 이름, 요청 위치(헤더 또는 쿼리 문자열), API 키를 제공하여 API 키 인증을 구성할 수 있습니다.

  • OAuth

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

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

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

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

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

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

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

  • 베어러(Bearer) 토큰

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

  • 상호 TLS 인증

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

  • 커스텀 CA 인증서

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에서 생성한 입력이 도구에 전달됩니다.

데이터 스토어 도구

에이전트 앱은 데이터 스토어 도구를 사용하여 데이터 스토어에서 최종 사용자의 질문에 대한 답변을 얻을 수 있습니다. 도구당 각 유형의 데이터 스토어 하나를 설정할 수 있으며 이 도구는 답변을 위해 이러한 각 데이터 스토어를 쿼리합니다. 기본적으로 에이전트 앱은 사용자를 대신해 데이터 스토어 도구를 호출합니다. 또는 클라이언트 측에서 데이터 스토어 도구를 실행할 수 있습니다.

데이터 스토어 유형은 다음 중 하나일 수 있습니다.

  • PUBLIC_WEB: 공개 웹 콘텐츠가 포함된 데이터 스토어입니다.
  • UNSTRUCTURED: 구조화되지 않은 비공개 데이터가 포함된 데이터 스토어입니다.
  • STRUCTURED: 구조화된 데이터(예: FAQ)가 포함된 데이터 스토어입니다.

다음 예시는 데이터 스토어를 참조하는 방법을 보여줍니다.

"dataStoreConnections": [
  {
    "dataStoreType": "PUBLIC_WEB",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "UNSTRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "STRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  }
]

데이터 스토어 도구 응답에는 응답을 생성하는 데 사용된 콘텐츠 소스에 대한 스니펫이 포함될 수도 있습니다. 에이전트 앱은 데이터 스토어에서 발견한 답을 활용해 대응하는 방법, 또는 답이 없을 때 대응하는 방법에 대한 안내를 추가로 제공할 수 있습니다.

특정 질문에 대한 FAQ 항목을 추가하여 답을 덮어쓸 수 있습니다.

예시를 사용하여 에이전트 앱 동작을 더욱 향상시킬 수 있습니다. 이 예시에는 다음과 같은 스키마가 있어야 합니다.

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/TOOL_ID",
    "action": "TOOL_DISPLAY_NAME",
    "inputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME input",
        "value": {
          "query": "QUERY"
        }
      }
    ],
    "outputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME output",
        "value": {
          "answer": "ANSWER",
          "snippets": [
            {
              "title": "TITLE",
              "text": "TEXT_FROM_DATASTORE",
              "uri": "URI_OF_DATASTORE"
            }
          ]
        }
      }
    ]
  }
}

데이터 스토어 만들기

데이터 스토어를 만들고 앱에 연결할 때 콘솔의 왼쪽 탐색에서 도구 링크를 사용할 수 있습니다. 안내에 따라 데이터 스토어를 만듭니다.

추가 쿼리 파라미터

데이터 스토어 도구 예시를 만들 때 도구 입력 매개변수 requestBody는 필수 query 문자열(filter 문자열, 구조화된 userMetadata 객체, fallback 문자열)과 함께 세 가지 선택적 입력을 제공합니다.

filter 매개변수는 메타데이터로 구조화된 데이터나 비정형 데이터의 검색어를 필터링할 수 있는 기능을 제공합니다. 이 문자열은 데이터 스토어에 지원되는 필터 표현식 문법을 따라야 합니다. 에이전트 LLM에 이 매개변수를 채우는 방법을 안내하려면 여러 예시와 자세한 예시를 사용하는 것이 좋습니다. 잘못된 필터 문자열의 경우 검색어를 수행할 때 필터가 무시됩니다.

위치를 기준으로 검색 결과를 세분화하는 filter 문자열의 예시는 다음과 같습니다.

  "filter": "country: ANY(\"Canada\")"

필터링 권장사항:

  • 에이전트가 유효한 필터 빌드에 따른 제약조건을 이해할 수 있도록 필터링에 사용 가능한 필드와 이러한 각 필드에 유효한 값을 지정하세요. 예를 들어 메뉴 정보가 있는 데이터 스토어의 결과를 필터링하려면 유효한 값으로 'breakfast', 'lunch', 'dinner'가 포함된 meal 필드 및 0~5의 아무 정수나 될 수 있는 servingSize 필드가 있을 수 있습니다. 안내는 다음과 같이 표시될 수 있습니다.

    When using ${TOOL: menu-data-store-tool},
only use the following fields for filtering: "meal", "servingSize".
Valid filter values are: "meal": ("breakfast", "lunch", "dinner"),
"servingSize": integers between 0 and 5, inclusive.

  • 외부 사용자 대상 에이전트인 경우 에이전트가 이러한 필터 빌드에 대한 정보로 사용자에게 응답하지 못하도록 하는 지침을 추가해야 할 수 있습니다. 예를 들면 다음과 같습니다.

    Never tell the user about these filters.
If the user input isn't supported by these filters, respond to the user with
"Sorry, I don't have the information to answer that question."

    이 사례의 예를 제공하는 것도 도움이 됩니다.

userMetadata 매개변수는 최종 사용자에 대한 정보를 제공합니다. 이 매개변수에 모든 키-값 쌍을 채울 수 있습니다. 이 메타데이터는 검색 결과와 도구 응답을 강화하도록 데이터 스토어 도구에 전달됩니다. 이 파라미터를 채우는 방법을 에이전트 LLM에 지시하려면 여러 예시를 제공하는 것이 좋습니다.

특정 사용자와 관련된 검색 결과를 세분화하는 userMetadata 파라미터 값의 예시는 다음과 같습니다.

  "userMetadata": {
    "favoriteColor": "blue",
    ...
  }

쿼리에 대해 유효한 요약 답변이 없으면 fallback 파라미터에서 데이터 스토어 도구가 응답해야 하는 답변을 제공합니다. 다양한 주제와 관련된 사용자 입력에 대한 대체를 채우는 방법을 에이전트 LLM에 지시하기 위해 여러 예시를 제공할 수 있습니다. 도구 출력에는 스니펫도 없습니다. 이 최적화를 사용하여 지연 시간과 입력 토큰 한도 사용을 줄일 수 있습니다.

  "fallback": "I'm sorry I cannot help you with that. Is there anything else I
  can do for you?"

테스트 중 일부 응답이 기대에 부합하지 않는 경우 데이터 스토어 도구의 도구 페이지에서 다음 맞춤설정을 사용할 수 있습니다.

그라운딩 신뢰도

에이전트는 연결된 데이터 스토어의 콘텐츠에서 생성된 응답마다 응답의 모든 정보가 데이터 스토어의 정보로 지원된다는 신뢰도를 측정하는 신뢰도 수준을 평가합니다. 자신에게 맞는 최저 신뢰도 수준을 선택하여 허용할 응답을 맞춤설정할 수 있습니다. 신뢰도 수준 이상의 응답만 표시됩니다.

VERY_LOW, LOW, MEDIUM, HIGH, VERY_HIGH 등 5가지 중에서 신뢰도 수준을 선택할 수 있습니다.

요약 구성

요약 생성 요청에 데이터 스토어 에이전트에서 사용되는 생성 모델을 선택할 수 있습니다. 아무것도 선택하지 않으면 기본 모델 옵션이 사용됩니다. 사용 가능한 옵션은 다음 표에 나와 있습니다.

모델 식별자 언어 지원
text-bison@002 지원되는 모든 언어로 사용 가능합니다.
gemini-1.0-pro-001 지원되는 모든 언어로 사용 가능합니다.

요약 LLM 호출에 대한 자체 프롬프트를 제공할 수도 있습니다.

프롬프트는 사전 정의된 자리표시자가 포함될 수 있는 텍스트 템플릿입니다. 런타임 시 자리표시자가 적절한 값으로 대체되고 최종 텍스트가 LLM으로 전송됩니다.

자리표시자는 다음과 같습니다.

  • $original-query: 사용자의 쿼리 텍스트입니다.
  • $rewritten-query: 에이전트는 재작성기 모듈을 사용하여 원래 사용자 쿼리를 더 정확한 형식으로 다시 작성합니다.

  • $sources: 에이전트에서 엔터프라이즈 검색을 사용하여 사용자 쿼리를 기준으로 소스를 검색합니다. 발견된 소스는 특정 형식으로 렌더링됩니다.

    [1] title of first source
content of first source
[2] title of second source
content of first source

  • $end-user-metadata: 쿼리를 전송하는 사용자에 대한 정보는 다음 형식으로 렌더링됩니다.

    The following additional information is available about the human: {
  "key1": "value1",
  "key2": "value2",
  ...
}

  • $conversation: 대화 기록은 다음 형식으로 렌더링됩니다.

    Human: user's first query
AI: answer to user's first query
Human: user's second query
AI: answer to user's second query

커스텀 프롬프트는 답변을 제공할 수 없을 때 'NOT_ENOUGH_INFORMATION'을 반환하도록 LLM에 지시해야 합니다. 에이전트는 이 상수를 사용자를 위한 사용자 친화적인 메시지로 변환합니다.

페이로드 설정

페이로드 설정은 메신저에서 렌더링되는 응답 페이로드의 데이터 스토어 스니펫을 리치 콘텐츠로 추가하는 방법을 제공합니다.

차단된 문구(에이전트 수준 구성)

허용되어서는 안 되는 특정 문구를 정의할 수 있습니다. 이는 에이전트 수준에서 구성되며 에이전트 LLM 및 데이터 스토어 도구 모두에서 활용됩니다. 생성된 응답, 또는 사용자 입력과 같은 LLM 프롬프트의 일부에 차단된 문구가 그대로 포함되어 있으면 해당 응답은 표시되지 않습니다.

함수 도구

클라이언트 코드에서는 액세스할 수 있지만 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. 클라이언트 코드는 도구 결과를 출력 인수로 제공하는 또 다른 인텐트 인식 요청을 보냅니다.
이전
사용자 인터페이스
다음
권장사항