Herramientas del cliente

Las herramientas del lado del cliente se ejecutan en el navegador del usuario o en la aplicación host, lo que permite el acceso a los datos locales del cliente y las capacidades del dispositivo no disponibles en el lado del servidor.

Las herramientas del lado del cliente se ejecutan en la superficie del cliente (el navegador del usuario o la aplicación host) en lugar de en el servidor UiPath. Cuando el agente llama a una herramienta del lado del cliente, el runtime se detiene, delega la llamada de la herramienta al cliente y se reanuda una vez que el cliente devuelve un resultado.

Usa herramientas del lado del cliente cuando el agente necesite acceder a datos o capacidades que solo existen en el cliente, como el estado de la aplicación, los datos locales o las acciones de IU que no se pueden realizar en el lado del servidor.

Cuándo utilizar herramientas del lado del cliente

Usa herramientas del lado del cliente cuando el agente necesite:

• Acceder a datos locales del cliente : leer información de la aplicación host que no está disponible para el servidor, como el contenido de un panel de tareas, campos de formulario o estado específico de la sesión.
• Desencadenar acciones del lado del cliente : realiza acciones dentro de la aplicación host, como navegar a una página, abrir un cuadro de diálogo, crear un registro en la IU local o actualizar un componente.
• Aprovecha las capacidades específicas del cliente : utiliza características del dispositivo o del navegador a las que no se puede acceder desde el servidor, como el acceso al portapapeles, el almacenamiento local o la geolocalización.

Nota:

Las herramientas del lado del cliente solo están disponibles para los agentes de conversación implementados a través de una superficie que admita la gestión de herramientas del lado del cliente, como el SDK de UiPath TypeScript o cualquier superficie que implemente el protocolo de conversación de UiPath. La superficie debe registrar un controlador para cada herramienta del lado del cliente; las herramientas sin un controlador registrado devuelven un error al agente.

Configurar herramientas del lado del cliente

Para añadir una herramienta del lado del cliente a tu agente conversacional:

1. En el diseñador de agentes, selecciona Añadir herramienta.

2. Selecciona la categoría Herramientas del lado del cliente .

3. Rellena los siguientes campos:

   • Nombre de la herramienta : un nombre único para la herramienta. Debe comenzar con una letra o un guion bajo y solo puede contener letras, dígitos, espacios y guiones bajos.
   • Descripción : describe lo que hace la herramienta y cuándo utilizarla. Esta descripción guía la decisión del agente de llamar a la herramienta.
   • Esquema de entrada : un objeto de esquema JSON que define los parámetros que el agente pasa al cliente al llamar a la herramienta.
   • Esquema de salida : un objeto de esquema JSON que define la estructura del resultado que el cliente devuelve al agente.

   

4. Selecciona Crear.

Después de crear la herramienta, puedes configurar ajustes adicionales en el panel de propiedades de la herramienta:

• Edite el nombre, la descripción y los esquemas de la herramienta.
• Aplica barreras de seguridad para aplicar políticas de runtime.
• Habilite las confirmaciones de llamada de herramienta para requerir la aprobación del usuario antes de la ejecución.

Esquemas de entrada y salida

Ambos esquemas son necesarios y deben ser objetos de esquema JSON válidos. Definen el contrato entre el agente y el cliente:

• El esquema de entrada especifica qué datos envía el agente al cliente cuando llama a la herramienta. El agente rellena los valores de entrada en función del contexto de la conversación y la definición del esquema.
• El esquema de salida especifica qué datos devuelve el cliente al agente después de ejecutar la herramienta. El agente utiliza este resultado para continuar con su razonamiento.

Esquemas de ejemplo

Para una herramienta que lee tareas de un tablero de proyecto:

Esquema de entrada:

{
  "type": "object",
  "properties": {
    "boardId": {
      "type": "string",
      "description": "The ID of the task board to read from"
    },
    "status": {
      "type": "string",
      "enum": ["todo", "in-progress", "done"],
      "description": "Filter tasks by status"
    }
  },
  "required": ["boardId"]
}

Esquema de salida:

{
  "type": "object",
  "properties": {
    "tasks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "string" },
          "assignee": { "type": "string" }
        }
      }
    }
  }
}

Comportamiento en superficies prediseñadas

En superficies prediseñadas como la gestión de instancias y la incrustación de iFrame, las herramientas del lado del cliente muestran un formulario al usuario en función del esquema de salida. El usuario rellena los campos manualmente y envía el resultado al agente.

El valor completo de las herramientas del lado del cliente se realiza en superficies personalizadas creadas con el SDK de TypeScript de UiPath, donde la aplicación host gestiona las llamadas de herramientas de forma programática: lee datos, desencadena acciones o interactúa con sistemas locales sin entrada manual del usuario.

Cómo funcionan las herramientas del lado del cliente en runtime

Cuando el agente llama a una herramienta del lado del cliente durante una conversación:

1. El agente decide utilizar la herramienta en función del contexto de la conversación y la descripción de la herramienta.
2. Si las confirmaciones de llamada de herramienta están habilitadas, el usuario revisa y aprueba la entrada propuesta antes de que la herramienta continúe.
3. El runtime envía la llamada de la herramienta, incluido el nombre de la herramienta, los valores de entrada y los esquemas de entrada/salida, a la superficie del cliente.
4. La superficie del cliente ejecuta su controlador registrado para la herramienta utilizando la entrada proporcionada.
5. El cliente devuelve el resultado al runtime.
6. El agente recibe el resultado y continúa su razonamiento.

Confirmaciones de llamadas de herramientas

Puedes requerir la confirmación del usuario antes de que se ejecute una herramienta del lado del cliente. Esto es útil para las herramientas que realizan acciones con efectos secundarios visibles, como crear una tarea, actualizar un registro o salir de la página actual.

Para habilitar la confirmación para una herramienta del lado del cliente:

1. Selecciona la herramienta del lado del cliente en el diseñador de agentes.
2. En las propiedades de la herramienta, habilita Requerir confirmación.

Cuando está habilitado, el agente se detiene antes de ejecutar la herramienta y muestra al usuario los parámetros de entrada propuestos. El usuario puede aprobar, modificar las entradas o rechazar la llamada de la herramienta.

Ejemplo: asistente de planificación de proyectos

Considera un asistente de planificación de proyectos integrado en una aplicación de gestión de tareas. El agente tiene dos herramientas del lado del cliente:

• read_board_tasks : lee las tareas actuales del panel de tareas del usuario en la aplicación host.
• create_task — Crea una nueva tarea en el panel del usuario.

Leer datos del cliente: cuando un usuario pregunta "¿En qué debo trabajar a continuación?", el agente llama a read_board_tasks. La aplicación host lee el estado de la placa y devuelve los datos de la tarea. A continuación, el agente analiza las tareas y sugiere un orden de prioridad en función del estado, los plazos y las dependencias.

Escribir datos en el cliente: cuando el usuario pide "Añadir una tarea para revisar el informe del tercer trimestre antes del viernes", el agente create_task con el título, la descripción y la fecha límite. Si la confirmación está habilitada, el usuario revisa primero los detalles de la tarea propuesta. La aplicación host crea la tarea en el tablero y el agente confirma que se creó.

Limitaciones

• La ejecución de la herramienta del lado del cliente depende de la disponibilidad y la capacidad de respuesta de la superficie del cliente. Si el cliente se desconecta durante la ejecución de la herramienta, la llamada de la herramienta puede fallar.
• La superficie del cliente debe registrar un controlador para cada herramienta del lado del cliente que define el agente. Si falta un controlador, la llamada de la herramienta devuelve un error al agente.