Herramientas

Con las herramientas, puedes conectar agentes generativos a sistemas externos. Estos sistemas pueden aumentar el conocimiento de los agentes generativos y permitirles ejecutar tareas complejas de manera eficiente.

Puedes usar herramientas integradas o compilar herramientas personalizadas para satisfacer tus requisitos.

Herramientas integradas

Google aloja las herramientas integradas. Puedes activar estas herramientas en agentes generativos sin necesidad de una configuración manual.

Las herramientas integradas compatibles son las siguientes:

  • Code Interpreter: Es una herramienta propia de Google que combina las capacidades de generación y ejecución de código, y permite al usuario realizar varias tareas, como análisis de datos, visualización de datos, procesamiento de texto, resolución de ecuaciones o problemas de optimización.

Tu agente está optimizado para determinar cómo y cuándo se deben invocar estas herramientas, pero puedes proporcionar ejemplos adicionales que se adapten a tus casos prácticos.

Los ejemplos deben tener un esquema como el siguiente:

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

Herramientas personalizadas

En las siguientes secciones, se describen las herramientas personalizadas.

Herramientas de OpenAPI

Un agente generativo puede conectarse a una API externa por medio de una herramienta de OpenAPI. Para ello, debes proporcionar el esquema de OpenAPI. De forma predeterminada, el agente generativo llamará a la API por ti. De manera alternativa, puedes ejecutar herramientas de OpenAPI en el lado del cliente.

Esquema de ejemplo:

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

De forma opcional, puedes usar la referencia del esquema interno @dialogflow/sessionId como tipo de esquema del parámetro. Con este tipo de esquema de parámetro, el ID de sesión de Dialogflow para la conversación actual se proporcionará como un valor de parámetro. Por ejemplo:

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

Limitaciones de la herramienta de OpenAPI

Se aplica la siguiente limitación:

  • Los tipos de parámetros admitidos son path, query y header. Aún no se admite el tipo de parámetro cookie.
  • Los parámetros definidos por el esquema de OpenAPI admiten los siguientes tipos de datos: string, number, integer, boolean y array. Aún no se admite el tipo object.
  • Por el momento, no puedes especificar parámetros de consulta en el editor de ejemplo de la consola.
  • El cuerpo de la solicitud y la respuesta deben estar vacíos o ser JSON.

Autenticación de la API de la herramienta de OpenAPI

Las siguientes opciones de autenticación son compatibles cuando se llama a una API externa:

  • Autenticación del agente de servicio de Dialogflow
    • Dialogflow puede generar un token de ID o un token de acceso mediante el agente de servicio de Dialogflow. El token se agrega en el encabezado HTTP de autorización cuando Dialogflow llama a una API externa.
    • Se puede usar un token de ID para acceder a los servicios de Cloud Functions y Cloud Run después de que otorgues los roles roles/cloudfunctions.invoker y roles/run.invoker a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Si los servicios de Cloud Functions y Cloud Run están en el mismo proyecto de recursos, no necesitas permisos de IAM adicionales para llamarlos.
    • Se puede usar un token de acceso para acceder a otras API de Google Cloud después de que hayas otorgado las funciones necesarias a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
  • Clave de API
    • Para configurar la autenticación con clave de API, proporciona el nombre de la clave, la ubicación de la solicitud (encabezado o cadena de consulta) y la clave de API, de manera que Dialogflow pase la clave de API en la solicitud.
  • OAuth
    • El flujo de credenciales de cliente de OAuth es compatible con la autenticación de servidor a servidor. El ID de cliente, el secreto del cliente y el extremo del token del proveedor de OAuth deben configurarse en Dialogflow. Dialogflow intercambia un token de acceso de OAuth y lo pasa en el encabezado de autenticación de la solicitud.
    • Para otros flujos de OAuth, debes usar la Herramienta de función a fin de realizar la integración con tu propia IU de acceso para intercambiar el token.
  • Autenticación mutua de TLS
  • Certificado de la AC personalizado

Herramientas de almacén de datos

Un agente generativo puede usar las herramientas de almacén de datos para obtener respuestas a las preguntas del usuario final sobre tus almacenes de datos. Puedes configurar un almacén de datos de cada tipo por herramienta, y la herramienta consultará cada uno de estos almacenes de datos para obtener respuestas. De forma predeterminada, el agente generativo llamará a la herramienta de almacén de datos en tu nombre. Como alternativa, puedes ejecutar herramientas de almacén de datos en el lado del cliente.

El tipo de almacén de datos puede ser uno de los siguientes:

  • PUBLIC_WEB: Es un almacén de datos que incluye contenido web público.
  • UNSTRUCTURED: Es un almacén de datos que contiene datos privados no estructurados.
  • STRUCTURED: Es un almacén de datos que contiene datos estructurados (por ejemplo, preguntas frecuentes).

En el siguiente ejemplo, se muestra cómo hacer referencia a un almacén de datos:

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

Las respuestas de la herramienta de almacén de datos también pueden contener fragmentos sobre la fuente de contenido que se usó para generar la respuesta. El agente generativo puede proporcionar instrucciones adicionales sobre cómo proceder con la respuesta de los almacenes de datos o cómo responder cuando no hay respuesta. Los ejemplos se pueden usar para mejorar aún más el comportamiento del agente generativo. El ejemplo debería tener los siguientes esquemas:

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

Herramientas para la función

Si tienes una funcionalidad a la que puedes acceder con tu código de cliente, pero no con las herramientas de OpenAPI, puedes usar herramientas de función. Las herramientas de función siempre se ejecutan del lado del cliente, no del agente generativo.

El proceso es el siguiente:

  1. Tu código de cliente envía una solicitud de detección de intent.
  2. El agente generativo detecta que se requiere una herramienta de función, y la respuesta de detección de intent contiene el nombre de la herramienta y los argumentos de entrada. Esta sesión se pausa hasta que se reciba otra solicitud de detección de intent con el resultado de la herramienta.
  3. Tu código de cliente llama a la herramienta.
  4. El código de cliente envía otra solicitud de detección de intent que proporciona el resultado de la herramienta como argumentos de salida.

En el siguiente ejemplo, se muestra el esquema de entrada y salida de una herramienta de función:

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

En el siguiente ejemplo, se muestra la solicitud y la respuesta de intent de detección inicial mediante 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"
          }
        }
      }
    ]
  }
}

En el siguiente ejemplo, se muestra la segunda solicitud de detección de intent, que proporciona el resultado de la herramienta:

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

Ejecución del cliente

Al igual que las herramientas de función, las herramientas de OpenAPI y de almacén de datos se pueden ejecutar en el lado del cliente mediante la aplicación de una anulación de API cuando se interactúa con la sesión.

Por ejemplo:

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

El proceso es el siguiente:

  1. El código de cliente envía una solicitud de detección de intent que especifica la ejecución del cliente.
  2. El agente generativo detecta que se requiere una herramienta y la respuesta de detección de intent contiene el nombre de la herramienta y los argumentos de entrada. Esta sesión se pausa hasta que se reciba otra solicitud de detección de intent con el resultado de la herramienta.
  3. Tu código de cliente llama a la herramienta.
  4. El código de cliente envía otra solicitud de detección de intent que proporciona el resultado de la herramienta como argumentos de salida.