Herramientas de OpenAPI y de Integration Connectors

Puedes usar las funciones de Agent Assist junto con APIs y fuentes de datos externas. Google Cloud proporciona herramientas de OpenAPI y Integration Connectors para facilitar tus integraciones de Agent Assist.

Herramientas de OpenAPI

OpenAPIOpenAPI permiten la conexión entre las funciones de Agent Assist y las APIs externas. Esta conexión permite que las funciones de Agent Assist lean y escriban información de varias fuentes. Para crear una herramienta de OpenAPI, debes proporcionar un esquema de OpenAPI que describa las APIs externas a las que deseas conectarte.

Herramienta de Integration Connectors

Usa Integration Connectors para conectarte Google Cloud a varias fuentes de datos. Las herramientas de conectores permiten que las funciones de Agent Assist usen Integration Connectors para leer y escribir esas fuentes de datos.

Antes de comenzar

Para configurar el entorno para crear herramientas de OpenAPI y Integration Connectors, ingresa el ID del proyecto y la región y, luego, ejecuta el siguiente código.

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" "$@"
}

Crea una herramienta de OpenAPI

Para usar una herramienta de OpenAPI, primero debes solicitar su creación y guardar el nombre del recurso de la herramienta.

Paso 1: Solicita crear la herramienta

Sigue estos pasos para solicitar la creación de una herramienta de OpenAPI.

Personaliza el código de la siguiente manera:
1. Dentro de un solo proyecto, usa un valor tool_key que sea único entre todas tus herramientas.
2. Ingresa tu propio esquema de OpenAPI en el campo open_api_spec.text_schema.

Ejecuta el siguiente código personalizado.

$ 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

Si se ejecuta correctamente, la API muestra la herramienta recién creada, que contiene el nombre del recurso, como se muestra en el siguiente ejemplo.

{
  "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"
  }
}

Paso 2: Guarda el nombre del recurso de la herramienta

Guarda el nombre del recurso de la herramienta en una variable de entorno para usarlo más adelante. El siguiente es un ejemplo de plantilla para la variable de entorno del recurso de la herramienta.

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

Coach de IA con una herramienta de OpenAPI

Puedes usar una herramienta de OpenAPI con la función de coach de IA para acceder a información adicional desde fuera de Google Cloud. Luego, esa información externa se puede usar para generar sugerencias que ayuden a los agentes del centro de contacto.

Paso 1: Crea un generador

En el siguiente ejemplo, se crea un generador con la variable de entorno del recurso de la herramienta.

$ 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

Deberías recibir una respuesta similar al siguiente ejemplo de un generador de coach de IA.

{
  "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"
  ]
}

Guarda el nombre del recurso del generador

Guárdalo como una variable de entorno para usarlo más adelante, como en el siguiente ejemplo.

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

Paso 2: Crea un perfil de conversación

Ejecuta el siguiente código para crear un perfil de conversación.

$ 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

Deberías recibir una respuesta como la siguiente.

{
  "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}"
}

Guarda el nombre del recurso del perfil de conversación

Guarda este nombre como una variable de entorno, como en el siguiente ejemplo.

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

Paso 3: Crea una conversación

Ejecuta el siguiente código para crear una conversación.

$ 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

Deberías recibir una respuesta como la siguiente.

{
  "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"
    }
  }
}

Guarda el nombre del recurso de conversación

Guarda este nombre como una variable de entorno para usarlo más adelante. Tu variable debe tener el siguiente formato.

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

Paso 4: Crea un usuario final

Ejecuta el siguiente código para crear un usuario final.

$ 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

Deberías recibir una respuesta como la siguiente.

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

Guarda el nombre del recurso del usuario final

Guarda el nombre del recurso del usuario final como una variable de entorno como la siguiente.

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

Paso 5: Crea un agente humano

Ejecuta el siguiente código para crear un agente humano.

$ 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

Deberías recibir una respuesta como la siguiente.

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

Guarda el nombre del recurso del agente humano

Guarda el nombre del recurso del agente humano como una variable de entorno como la siguiente.

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

Paso 6: Envía texto al coach de IA

Ejecuta el siguiente código para enviar texto al coach de IA con el método AnalyzeContent.

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

Paso 7: Verifica la llamada a la herramienta

Ejecuta el siguiente código para verificar la llamada a la herramienta.

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

Deberías recibir una respuesta como la siguiente.

[
  {
    "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"
    }
  }
]

Paso 8 (opcional): Borra recursos

Para borrar los recursos que creaste en los pasos anteriores, ejecuta el siguiente código.

Perfil de conversación

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

Generador

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

Herramienta de OpenAPI

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

Crea una herramienta de Integration Connectors

Puedes configurar Integration Connectors con la Google Cloud consola. Sigue estos pasos para crear una herramienta de Integration Connectors de Agent Assist basada en un conector de BigQuery.

Paso 1: Crea una herramienta de conector de BigQuery

Antes de crear una herramienta de Integration Connectors, ve a la Google Cloud consola y crea un Integration Connectors de BigQuery.

Paso 2: Solicita crear la herramienta de Integration Connectors

Ejecuta el siguiente código para solicitar la creación de una herramienta. Para el campo connector_spec.name, usa el nombre del recurso de tu conector de 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

Deberías recibir una respuesta similar a la siguiente.

{
  "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"
}

¿Qué sigue?

Para obtener una lista completa de las herramientas de Integration Connectors que admite Agent Assist, consulta la lista de herramientas de conectores de Dialogflow.

Herramientas de OpenAPI y de Integration Connectors Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.