이 페이지는 Cloud Translation API를 통해 번역되었습니다.

OpenAPI 및 통합 커넥터 도구

외부 API 및 데이터 소스와 함께 Agent Assist 기능을 사용할 수 있습니다. Google Cloud 는 Agent Assist 통합을 용이하게 하기 위해 OpenAPI 및 Integration Connectors 도구를 제공합니다.

OpenAPI 도구

OpenAPI 도구를 사용하면 Agent Assist 기능과 외부 API를 연결할 수 있습니다. 이 연결을 통해 Agent Assist 기능은 여러 소스의 정보를 읽고 쓸 수 있습니다. OpenAPI 도구를 만들려면 연결하려는 외부 API를 설명하는 OpenAPI 스키마를 제공해야 합니다.

Integration Connectors 도구

Integration Connectors를 사용하여 다양한 데이터 소스에 연결합니다. Google Cloud 커넥터 도구를 사용하면 Agent Assist 기능이 통합 커넥터를 사용하여 이러한 데이터 소스를 읽고 쓸 수 있습니다.

시작하기 전에

OpenAPI 및 Integration Connectors 도구를 만들 환경을 설정하려면 프로젝트 ID와 리전을 입력한 후 다음 코드를 실행합니다.

CLOUDSDK_CORE_PROJECT=YOUR_PROJECT_ID
REGION=YOUR_REGION
API_VERSION=v2beta1
API_ENDPOINT=https://${REGION}-dialogflow.googleapis.com/${API_VERSION}

function gcurl () {
        curl -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "X-Goog-User-Project: ${CLOUDSDK_CORE_PROJECT}" -H "Content-Type: application/json; charset=utf-8" "$@"
}

OpenAPI 도구 만들기

OpenAPI 도구를 사용하려면 먼저 도구 생성을 요청하고 도구 리소스 이름을 저장해야 합니다.

1단계: 도구 생성 요청

다음 단계에 따라 OpenAPI 도구 생성을 요청하세요.

다음과 같이 코드를 맞춤설정합니다.
1. 단일 프로젝트 내에서 모든 도구 중에서 고유한 tool_key 값을 사용합니다.
2. open_api_spec.text_schema 필드에 자체 OpenAPI 스키마를 입력합니다.

다음 맞춤 코드를 실행합니다.

$ cat > create-tool-request.json << EOF
{
  "tool_key": "UNIQUE_KEY",
  "description": "TOOL_DESCRIPTION",
  "display_name": "TOOL_DISPLAY_NAME",
  "open_api_spec": {
    "text_schema": "Your-Schema"
  }
}
EOF

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/tools -d @create-tool-request.json | tee create-tool-response.json

성공하면 API는 다음 예와 같이 리소스 이름이 포함된 새로 생성된 도구를 반환합니다.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
  "toolKey": "UNIQUE_KEY",
  "description": "TOOL_DESCRIPTION",
  "createTime": "2025-06-02T18:11:38.999174724Z",
  "updateTime": "2025-06-02T18:11:38.999174724Z",
  "displayName": "TOOL_DISPLAY_NAME",
  "openApiSpec": {
    "textSchema": "Your-Schema"
  }
}

2단계: 도구 리소스 이름 저장

나중에 사용할 수 있도록 도구 리소스 이름을 환경 변수에 저장합니다. 다음은 도구 리소스 환경 변수의 템플릿 예시입니다.

TOOL_RESOURCE=$(cat create-tool-response.json | jq .name | tr -d '"')

OpenAPI 도구를 사용하는 AI 코치

AI 코치 기능과 함께 OpenAPI 도구를 사용하여 Google Cloud외부의 추가 정보에 액세스할 수 있습니다. 그런 다음 이 외부 정보를 사용하여 고객센터 상담사를 지원하는 추천을 생성할 수 있습니다.

1단계: 생성기 만들기

다음 예시에서는 도구 리소스 환경 변수를 사용하여 생성기를 만듭니다.

$ cat > create-generator-request.json << _EOF_
{"agent_coaching_context":{"instructions":[{"agent_action":"help customer by using the tool to find information from library of congress","condition":"The customer asks about library of congress","description":"agent coaching test","display_name":"Search for information"}],"overarching_guidance":"Help customer with questions"},"description":"prober-generate-suggestions-with-agent-coaching-generator","inference_parameter":{"max_output_tokens":256,"temperature":0},"tools":["${TOOL_RESOURCE}"],"trigger_event":"CUSTOMER_MESSAGE"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/generators -d @create-generator-request.json | tee create-generator-response.json

_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/generators -d @create-generator-request.json | tee create-generator-response.json

다음과 같은 AI 코치 생성기 예시와 비슷한 응답이 표시됩니다.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID",
  "description": "example-generator",
  "inferenceParameter": {
    "maxOutputTokens": 256,
    "temperature": 0
  },
  "triggerEvent": "CUSTOMER_MESSAGE",
  "createTime": "2025-06-02T18:30:51.021461728Z",
  "updateTime": "2025-06-02T18:30:51.021461728Z",
  "agentCoachingContext": {
    "instructions": [
      {
        "displayName": "Search for information",
        "condition": "The customer asks about library of congress",
        "agentAction": "help customer by using the tool to find information from library of congress"
      }
    ],
    "version": "1.5",
    "overarchingGuidance": "Help customer with questions"
  },
  "tools": [
    "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID"
  ]
}

생성기 리소스 이름 저장

다음 예와 같이 나중에 사용할 수 있도록 환경 변수로 저장합니다.

GENERATOR_RESOURCE=$(cat create-generator-response.json | jq .name | tr -d '"')

2단계: 대화 프로필 만들기

다음 코드를 실행하여 대화 프로필을 만듭니다.

$ cat > create-conversation-profile-request.json << _EOF_
{"displayName":"prober-generate-suggestions-with-agent-coaching-generator","humanAgentAssistantConfig":{"humanAgentSuggestionConfig":{"generators":["${GENERATOR_RESOURCE}"]}}}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/conversationProfiles -d @create-conversation-profile-request.json | tee create-conversation-profile-response.json

다음과 같은 응답이 표시됩니다.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
  "displayName": "prober-generate-suggestions-with-agent-coaching-generator",
  "humanAgentAssistantConfig": {
    "humanAgentSuggestionConfig": {
      "generators": [
        "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID"
      ]
    }
  },
  "languageCode": "en-US",
  "createTime": "2025-06-02T18:40:39.940318Z",
  "updateTime": "2025-06-02T18:40:39.940318Z",
  "projectNumber": "${project_number}"
}

대화 프로필 리소스 이름 저장

다음 예와 같이 이 이름을 환경 변수로 저장합니다.

CONVERSATION_PROFILE_RESOURCE=$(cat create-conversation-profile-response.json | jq .name | tr -d '"')

3단계: 대화 만들기

다음 코드를 실행하여 대화를 만듭니다.

$ cat > create-conversation-request.json << _EOF_
{"conversationProfile":"${CONVERSATION_PROFILE_RESOURCE}"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/conversations -d @create-conversation-request.json | tee create-conversation-response.json

다음과 같은 응답이 표시됩니다.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-ID",
  "lifecycleState": "IN_PROGRESS",
  "conversationProfile": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
  "startTime": "2025-06-02T18:43:40.818123Z",
  "conversationStage": "HUMAN_ASSIST_STAGE",
  "source": "ONE_PLATFORM_API",
  "initialConversationProfile": {
    "name": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
    "displayName": "prober-generate-suggestions-with-agent-coaching-generator",
    "humanAgentAssistantConfig": {
      "humanAgentSuggestionConfig": {
        "generators": [
          "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID"
        ]
      }
    },
    "languageCode": "en-US"
  },
  "projectNumber": "${project_number}",
  "initialGeneratorContexts": {
    "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID": {
      "generatorType": "AGENT_COACHING",
      "generatorVersion": "1.5"
    }
  }
}

대화 리소스 이름 저장

나중에 사용할 수 있도록 이 이름을 환경 변수로 저장합니다. 변수는 다음 형식을 따라야 합니다.

CONVERSATION_RESOURCE=$(cat create-conversation-response.json | jq .name | tr -d '"')

4단계: 최종 사용자 만들기

다음 코드를 실행하여 최종 사용자를 만듭니다.

$ cat > create-end-user-request.json << _EOF_
{"role":"END_USER"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/${CONVERSATION_RESOURCE}/participants -d @create-end-user-request.json | tee create-end-user-response.json

다음과 같은 응답이 표시됩니다.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-ID/participants/End-User-Participant-ID",
  "role": "END_USER"
}

최종 사용자 리소스 이름 저장

다음과 같이 최종 사용자 리소스 이름을 환경 변수로 저장합니다.

END_USER_RESOURCE=$(cat create-end-user-response.json | jq .name | tr -d '"')

5단계: 상담사 만들기

다음 코드를 실행하여 사람 에이전트를 만듭니다.

$ cat > create-human-agent-request.json << _EOF_
{"role":"HUMAN_AGENT"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/${CONVERSATION_RESOURCE}/participants -d @create-human-agent-request.json | tee create-human-agent-response.json

다음과 같은 응답이 표시됩니다.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-IDHuman-Agent-Participant-ID",
  "role": "HUMAN_AGENT"
}

상담사 리소스 이름 저장

다음과 같이 상담사 리소스 이름을 환경 변수로 저장합니다.

HUMAN_AGENT_RESOURCE=$(cat create-human-agent-response.json | jq .name | tr -d '"')

6단계: AI 코치에게 텍스트 보내기

다음 코드를 실행하여 AnalyzeContent 메서드로 AI 코치에게 텍스트를 보냅니다.

cat > analyze-content-1-request.json << _EOF_
{"text_input":{"languageCode":"en-US","text":"Can you search library of congress for the latest trends"}}
_EOF_

gcurl -X POST "${API_ENDPOINT}/${END_USER_RESOURCE}:analyzeContent" -d @analyze-content-1-request.json | tee analyze-content-1-response.json

7단계: 도구 호출 확인

다음 코드를 실행하여 도구 호출을 확인합니다.

cat analyze-content-1-response.json| jq ".humanAgentSuggestionResults[0].generateSuggestionsResponse.generatorSuggestionAnswers[0].generatorSuggestion.toolCallInfo"

다음과 같은 응답이 표시됩니다.

[
  {
    "toolCall": {
      "tool": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
      "action": "search",
      "inputParameters": {
        "q": "latest trends",
        "fo": "json",
        "tool_description": "A generic search endpoint that might be available across various LoC APIs. The structure of the results will vary.\n",
        "at": "trending_content"
      },
      "createTime": "2025-06-02T18:56:53.882479179Z"
    },
    "toolCallResult": {
      "tool": "projects/Your-Project-ID/locations/Your-Region/tools/MjM0NTU3NDk2MTM5NTAwNzQ4OQ",
      "action": "search",
      "content": ""}]}",
      "createTime": "2025-06-02T18:56:54.289367086Z"
    }
  }
]

8단계: (선택사항) 리소스 삭제

이전 단계에서 만든 리소스를 삭제하려면 다음 코드를 실행합니다.

대화 프로필

gcurl -X DELETE ${API_ENDPOINT}/${CONVERSATION_PROFILE_RESOURCE}

생성기

gcurl -X DELETE ${API_ENDPOINT}/${GENERATOR_RESOURCE}

OpenAPI 도구

gcurl -X DELETE ${API_ENDPOINT}/${TOOL_RESOURCE}

Integration Connectors 도구 만들기

Google Cloud 콘솔을 사용하여 Integration Connectors를 설정할 수 있습니다. 다음 단계에 따라 BigQuery 커넥터를 기반으로 Agent Assist 통합 커넥터 도구를 만드세요.

1단계: BigQuery 커넥터 도구 만들기

Integration Connectors 도구를 만들기 전에 Google Cloud 콘솔로 이동하여 BigQuery Integration Connectors를 만듭니다.

2단계: 통합 커넥터 도구 생성 요청

다음 코드를 실행하여 도구 생성을 요청합니다. connector_spec.name 필드의 경우 BigQuery 커넥터의 리소스 이름을 사용합니다.

cat > create-connector-tool-request.json << _EOF_
{
  "tool_key": "order_tool",
  "description": "order bigquery connector tool",
  "display_name": "order bigquery connector tool",
  "connector_spec": {
    "name": "projects/Your-Project-ID/locations/Your-Region/connections/Your-Connector-ID",
    "actions": [
                             {
                               "entityOperation": {
                                 "entityId": "Orders",
                                 "operation": "LIST"
                               }
                             }, {
                               "entityOperation": {
                                 "entityId": "Orders",
                                 "operation": "GET"
                               }
                             }
                           ]
  }
}
_EOF_


gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/tools -d @create-connector-tool-request.json | tee create-connector-tool-response.json

다음과 같은 응답이 표시됩니다.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
  "toolKey": "order_tool",
  "description": "order bigquery connector tool",
  "createTime": "2025-06-03T19:29:55.896178942Z",
  "updateTime": "2025-06-03T19:29:55.896178942Z",
  "connectorSpec": {
    "name": "projects/Your-Project-ID/locations/Your-Region/connections/order-bigquery-connector",
    "actions": [
      {
        "entityOperation": {
          "entityId": "Orders",
          "operation": "LIST"
        }
      },
      {
        "entityOperation": {
          "entityId": "Orders",
          "operation": "GET"
        }
      }
    ]
  },
  "displayName": "order bigquery connector tool"
}

다음 단계

Agent Assist에서 지원하는 Integration Connectors 도구의 전체 목록은 Dialogflow 커넥터 도구 목록을 참고하세요.

OpenAPI 및 통합 커넥터 도구 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

OpenAPI 도구

Integration Connectors 도구

시작하기 전에

OpenAPI 도구 만들기

1단계: 도구 생성 요청

2단계: 도구 리소스 이름 저장

OpenAPI 도구를 사용하는 AI 코치

1단계: 생성기 만들기

생성기 리소스 이름 저장

2단계: 대화 프로필 만들기

대화 프로필 리소스 이름 저장

3단계: 대화 만들기

대화 리소스 이름 저장

4단계: 최종 사용자 만들기

최종 사용자 리소스 이름 저장

5단계: 상담사 만들기

상담사 리소스 이름 저장

6단계: AI 코치에게 텍스트 보내기

7단계: 도구 호출 확인

8단계: (선택사항) 리소스 삭제

대화 프로필

생성기

OpenAPI 도구

Integration Connectors 도구 만들기

1단계: BigQuery 커넥터 도구 만들기

2단계: 통합 커넥터 도구 생성 요청

다음 단계

OpenAPI 및 통합 커넥터 도구