Ferramentas do lado do cliente

As ferramentas no lado do cliente são executadas no navegador do usuário ou no aplicativo host, permitindo o acesso a dados locais do cliente e recursos do dispositivo indisponíveis no lado do servidor.

As ferramentas do lado do cliente são executadas na superfície do cliente — o navegador do usuário ou aplicativo host — em vez de no servidor UiPath. Quando o agente chama uma ferramenta do lado do cliente, o runtime pausa, delega a chamada da ferramenta ao cliente e retoma quando o cliente retorna um resultado.

Use ferramentas do lado do cliente quando o agente precisar acessar dados ou recursos que existem apenas no cliente, como estado do aplicativo, dados locais ou ações de interface gráfica que não podem ser executadas no lado do servidor.

Quando usar ferramentas do lado do cliente

Use ferramentas do lado do cliente quando o agente precisar:

• Acessar dados locais do cliente — Leia informações do aplicativo host que não estão disponíveis para o servidor, como o conteúdo de um painel de tarefas, campos de formulário ou estado específico da sessão.
• Disparar ações do lado do cliente — Execute ações dentro do aplicativo host, como navegar até uma página, abrir uma caixa de diálogo, criar um registro na interface gráfica local ou atualizar um componente.
• Aproveite recursos específicos do cliente — Use funcionalidades do dispositivo ou navegador que não são acessíveis do servidor, como acesso à área de transferência, armazenamento local ou localização geográfica.

Observação:

As ferramentas do lado do cliente estão disponíveis apenas para agentes de conversação implantados por meio de uma superfície que é compatível com o tratamento de ferramentas do lado do cliente, como o UiPath TypeScript SDK ou qualquer superfície que implemente o protocolo de conversa da UiPath. A superfície deve registrar um manipulador para cada ferramenta do lado do cliente; as ferramentas sem um manipulador registrado retornam um erro ao agente.

Configuração de ferramentas do lado do cliente

Para adicionar uma ferramenta do lado do cliente ao seu agente de conversa:

1. No designer de agentes, selecione Adicionar ferramenta.

2. Selecione a categoria Ferramentas do lado do cliente .

3. Preencha os seguintes campos:

   • Nome da ferramenta — Um nome exclusivo para a ferramenta. Deve começar com uma letra ou sublinhado e conter apenas letras, dígitos, espaços e sublinhados.
   • Descrição — Descreva o que a ferramenta faz e quando usá-la. Essa descrição orienta a decisão do agente de chamar a ferramenta.
   • Esquema de entrada — Um objeto de Esquema JSON que define os parâmetros que o agente passa para o cliente ao chamar a ferramenta.
   • Esquema de saída — Um objeto de Esquema JSON que define a estrutura do resultado que o cliente retorna ao agente.

   

4. Selecione Criar.

Após criar a ferramenta, você pode definir configurações adicionais no painel de propriedades da ferramenta:

• Edite o nome da ferramenta, a descrição e os esquemas.
• Aplique proteções para impor políticas de runtime.
• Habilite as confirmações de chamada de ferramenta para exigir a aprovação do usuário antes da execução.

Esquemas de entrada e saída

Ambos os esquemas são obrigatórios e devem ser objetos de Esquema JSON válidos. Eles definem o contrato entre o agente e o cliente:

• O esquema de entrada especifica quais dados o agente envia ao cliente quando chama a ferramenta. O agente preenche os valores de entrada com base no contexto da conversa e na definição do esquema.
• O esquema de saída especifica quais dados o cliente retorna ao agente após executar a ferramenta. O agente usa esse resultado para continuar seu raciocínio.

Exemplos de esquemas

Para uma ferramenta que lê tarefas de um painel de projeto:

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 saída:

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

Comportamento em superfícies pré-construídas

Em superfícies pré-construídas, como Gerenciamento de instâncias e Incorporação de iFrame, as ferramentas do lado do cliente exibem um formulário para o usuário com base no esquema de saída. O usuário preenche os campos manualmente e envia o resultado de volta para o agente.

O valor total das ferramentas do lado do cliente é realizado em superfícies personalizadas criadas com o UiPath TypeScript SDK, onde o aplicativo host lida com chamadas de ferramentas programaticamente — lendo dados, disparando ações ou interagindo com sistemas locais sem entrada manual do usuário.

Como as ferramentas do lado do cliente funcionam no runtime

Quando o agente chama uma ferramenta do lado do cliente durante uma conversa:

1. O agente decide usar a ferramenta com base no contexto da conversa e na descrição da ferramenta.
2. Se as confirmações de chamada de ferramenta estiverem habilitadas, o usuário revisa e aprova a entrada proposta antes que a ferramenta prossiga.
3. O runtime envia a chamada da ferramenta — incluindo o nome da ferramenta, valores de entrada e esquemas de entrada/saída — para a superfície do cliente.
4. A superfície do cliente executa seu manipulador registrado para a ferramenta usando a entrada fornecida.
5. O cliente retorna o resultado ao runtime.
6. O agente recebe o resultado e continua seu raciocínio.

Confirmações de chamadas de ferramentas

Você pode exigir a confirmação do usuário antes que uma ferramenta do lado do cliente seja executada. Isso é útil para ferramentas que realizam ações com efeitos colaterais visíveis, como criar uma tarefa, atualizar um registro ou navegar para fora da página atual.

Para habilitar a confirmação para uma ferramenta do lado do cliente:

1. Selecione a ferramenta do lado do cliente no designer de agentes.
2. Nas propriedades da ferramenta, habilite Exigir confirmação.

Quando habilitado, o agente pausa antes de executar a ferramenta e mostra ao usuário os parâmetros de entrada propostos. O usuário pode aprovar, modificar as entradas ou rejeitar a chamada de ferramenta.

Exemplo: assistente de planejamento de projetos

Considere um assistente de planejamento de projetos incorporado a um aplicativo de gerenciamento de tarefas. O agente tem duas ferramentas do lado do cliente:

• Read_board_tasks — Lê as tarefas atuais do painel de tarefas do usuário no aplicativo host.
• criar_task — Cria uma nova tarefa no painel do usuário.

Leitura de dados do cliente: quando um usuário pergunta "Em que devo trabalhar em seguida?", o agente chama read_board_tasks. O aplicativo host lê o estado do painel e retorna os dados da tarefa. O agente então analisa as tarefas e sugere uma ordem de prioridade com base no status, prazos e dependências.

Gravação de dados para o cliente: quando o usuário pede "Adicionar uma tarefa para revisar o relatório do terceiro trimestre até sexta-feira", o agente chama create_task com o título, descrição e data de vencimento. Se a confirmação estiver habilitada, o usuário revisará primeiro os detalhes da tarefa proposta. O aplicativo host cria a tarefa no painel e o agente confirma que ela foi criada.

Limitações

• A execução da ferramenta no lado do cliente depende da disponibilidade e da capacidade de resposta da superfície do cliente. Se o cliente se desconectar durante a execução da ferramenta, a chamada de ferramenta pode falhar.
• A superfície do cliente deve registrar um manipulador para cada ferramenta do lado do cliente que o agente define. Se um manipulador estiver ausente, a chamada de ferramenta retornará um erro ao agente.