Construindo uma Habilidade personalizada – Blip | Blip Help

Índice:

Depois de realizar as configurações iniciais do seu Agente (Saiba mais aqui), é possível realizar a criação de uma habilidade.

‘Habilidade’ é uma funcionalidade que flexibiliza o uso do produto para especialistas, permitindo a criação de ações personalizadas executadas por um agente de IA. Com ela, é possível redirecionar a interação para outro chatbot que executará tarefas específicas. Essa funcionalidade é útil em casos de uso que exigem ações externas, como agendamentos, busca de informações em APIs e outras integrações.

Requisitos

Pré-requisitos técnicos:

Permissões para criar, editar e gerenciar chatbots.
Acesso ao AI Agent.
Configuração de endpoints externos para os bots de execução.

Como Funciona

O usuário interage com o AI Agent, que então aciona uma Habilidade. Essa ação faz com que o AI Agent redirecione o usuário para outro bot responsável por executar a ação externa. Esse bot pode solicitar mais informações do usuário ou apenas processar a ação e retornar com a resposta por meio do próprio AI Agent.

Fluxo de operação:

O AI Agent identifica a necessidade de uma ação.
A habilidade é acionada.
A interação é redirecionada para outro chatbot ou API.
O resultado é retornado ao usuário ou processado pela IA.

Criação de uma Habilidade

Ativação e Configuração de Habilidades:

Navegue até a seção de Habilidades e em seguida Gerenciamento de Habilidades no painel de controle do AI Agent.
1. Clique em "Criar Habilidade".
Defina e salve um nome para sua habilidade
Clique em "Criar nova habilidade"
Adicione tarefas para sua habilidade

Clique em "Adicionar tarefa"
Defina um nome e descrição/função da tarefa
Adicione uma ação para esta tarefa.
1. Selecione a integração que contém a ação desejada
2. Seleciona a ação deseja

Clique em "salvar" para concluir sua tarefa
Clique em "ativar" para poder testar sua Custom Skill em desenvolvimento
1. Para publicar sua Custom Skill em produção, vá à página inicial e clique em "publicar"

Criação de integração

Clique em "nova integração":
1. Defina nome e descrição da integração
2. Selecione o tipo chatbot
3. Clique em "adicionar ação"
  1. Defina nome, orientação, serviço e os parâmetros desta ação

Gerenciamento de Habilidades

Nos ‘Três pontinhos’ de uma Habilidade criada é possível: ’Editar, excluir e habilitar/desabilitar Habilidades já existentes.

Gerenciamento de Integrações

Na opção ‘Integrações’ é possível consultar as integrações existentes e realizar as seguintes opções: ‘Editar’ e ‘Excluir’.

Observação: Para excluir uma integração é necessário remover todas as ações da mesma.

Gerenciamento de Ações:

Dentro de uma ‘Integração’ é possível consultar as ações existentes e realizar as seguintes opções: ‘Editar’ e ‘Excluir’.

Exemplos de Uso

Agendamento de Consultas: Um usuário conversa com o AI Agent e solicita o agendamento de uma consulta. A Habilidade redireciona a solicitação para um bot especializado que acessa a agenda via API e realiza o agendamento.
Consulta de Informações em API Externa: Um cliente pede uma informação específica que está em uma base de dados externa. A habilidade aciona o bot que realiza a busca via API e retorna a informação diretamente ao usuário.

Melhores Práticas

Defina nomes e descrições claras para cada Habilidade, facilitando a manutenção e identificação.
Utilize parâmetros padronizados para garantir consistência e evitar conflitos entre skills.
Teste as skills com diferentes cenários para garantir que o redirecionamento e a execução sejam fluidos.

Resolução de Problemas

Ação não redireciona corretamente: Verifique se os endpoints externos estão configurados corretamente.
O bot não executa a ação: Revise os parâmetros enviados e as permissões de acesso da skill ao bot externo.
Problemas com integração de APIs: Confirme se a API está respondendo corretamente e se os dados estão sendo formatados como esperado.

Documentação Técnica: Habilidades para Agente de IA

Processo de integração e comunicação entre o Agente de IA e a aplicação builder para Habilidades. Como o Agente de IA envia solicitações para o bot builder e como o bot builder retorna respostas, incluindo respostas do usuário para fornecer contexto adicional.

Estrutura de Integração

Contato de Envio para o Bot Builder

Quando o Agente de IA identifica que uma ação deve ser executada, ele envia uma solicitação para o bot builder. O contrato para o envio da solicitação deve seguir o formato JSON abaixo:

{

  "name": "retrieve_products",

  "parameters": {

    "Marca": {

      "eq": "nome_marca"

    }

  },

  "tool_call_id": "call_id"

}

Campos

name: Nome da ação a ser executada. Por exemplo, retrieve_products.
parameters: Parâmetros necessários para a execução da ação. Exemplo dado com o parâmetro Marca.
tool_call_id: Identificador único para a chamada da ferramenta, utilizado para correlacionar a solicitação com a resposta.

Como extrair dados da ação enviados pelo agente de IA em seu Bot Builder.

A mensagem enviada pelo agente de IA será recebida como entrada do usuário, seguindo o padrão mostrado acima. Para capturar esses dados, sugere-se adicionar um script à ação de saída do bloco inicial do fluxo. O parâmetro de entrada dessa ação será o próprio input do usuário

Exemplo de criação do Script para extração dos dados enviados pelo Agente de IA:

function run(jsonString) {

 try {

  // Parse o JSON

  const jsonObj = JSON.parse(jsonString);

 

   // Extraindo os valores

   const toolCallId = jsonObj.tool_call_id;

   const actionName = jsonObj.nome;

   const parameters = jsonObj.parameters;

   const resultObject = {

      name: actionName,

      parameters: parameters,

      toolCallId: tool_call_id

   };




   // Retornando os valores em um objeto

   return resultObject;

 } catch (error) {

   console.error("Erro ao processar o JSON:", error);

   return null;

 }

}

Fluxo de Dados

1. Solicitação do Agente de IA para o Bot Builder
  O Agente de IA envia a solicitação ao bot builder utilizando o contrato JSON especificado. O bot builder processa a solicitação com base no nome da ação e nos parâmetros fornecidos.
2. Processamento no Bot Builder
  O bot builder processa a solicitação e gera uma resposta apropriada, considerando tanto o contexto quanto às respostas do usuário.
Retorno de Dados para o Agente de IA
Após o processamento, o bot builder retorna os dados para o Agente de IA no formato JSON definido abaixo.

Formato de Retorno Esperado

O retorno do bot builder será feito para o Agente de IA e deve seguir o formato JSON especificado usando o serviço de redirecionamento do Builder:

Possíveis contratos de retorno:



[

  {

    "tool_call_id": "call_id",

    "content": "conteudo para contexto",

    "role": "tool"

  },

  {

    "content": "resposta do assistente",

    "role": "assistant"

  },

  {

    "content": "resposta adicional do usuário",

    "role": "user"

  }

]

Campos

- tool_call_id: Identificador único da chamada da ferramenta. Deve corresponder ao valor enviado na solicitação inicial.
- content: Conteúdo relevante para o contexto ou resposta. Pode incluir dados processados ou informações adicionais necessárias.
- role: Papel associado ao conteúdo:
  - tool: Informações contextuais ou processadas pela ferramenta.
  - assistant: Resposta final do assistente.
  - user: Resposta adicional do usuário, se aplicável. Esse campo contextualiza a IA com a interação do usuário.

Exemplo de criação do Payload de retorno para o Agente de IA no Builder



const run = (resultObject, apiBodyResponse) => {

    

    return [

   {

       "tool_call_id": `${resultObject.tool_call_id}`,

       "content": `${apiBodyResponse}`,

       "role": "tool"

   }

]

}

Regras de Formatação

Campo Obrigatório: O primeiro item da lista deve sempre conter:


{

  "tool_call_id": "call_id",

  "content": "conteudo para contexto",

  "role": "tool"

}

Este campo é essencial para associar a resposta ao contexto da chamada inicial.

Resposta do Assistente: Para evitar que a IA envie uma mensagem intermediária, a resposta final do assistente deve ser o último item da lista:


[

  {

    "tool_call_id": "call_id",

    "content": "conteudo para contexto",

    "role": "tool"

  },

  {

    "content": "resposta do assistente",

    "role": "assistant"

  }

]

Quando a resposta do assistente é a última, a IA processa a resposta como final e não gera uma mensagem adicional.

Resposta Adicional do Usuário: Caso o usuário tenha respondido no fluxo do builder e a contextualização é necessária, a resposta do usuário deve ser adicionada como o último item na lista:



[

  {

    "tool_call_id": "call_id",

    "content": "conteudo para contexto",

    "role": "tool"

  },

  {

    "content": "resposta do assistente",

    "role": "assistant"

  },

  {

    "content": "resposta adicional do usuário",

    "role": "user"

  }

]

Isso garante que a IA tenha o contexto completo, incluindo as interações do usuário respondendo o usuário em seguida.

Exemplos

Exemplo 1: Retorno Completo com Contexto, Assistente e Resposta do Usuário

[

  {

    "tool_call_id": "12345",

    "content": "Informações sobre a marca X",

    "role": "tool"

  },

  {

    "content": "Os produtos da marca X são: Produto A, Produto B.",

    "role": "assistant"

  },

  {

    "content": "Estou interessado no Produto A.",

    "role": "user"

  }

]

Exemplo 2: Retorno com Contexto e Assistente Apenas

[

  {

    "tool_call_id": "12345",

    "content": "Informações sobre a marca X",

    "role": "tool"

  },

  {

    "content": "Os produtos da marca X estão listados.",

    "role": "assistant"

  }

]

Exemplo 3: Retorno com Contexto, resposta do Assistente e mensagem do usuário

[

  {

    "tool_call_id": "12345",

    "content": "Informações sobre a marca X",

    "role": "tool"

  },

  {

    "content": "Os produtos da marca X estão listados.",

    "role": "assistant"

  },

  {

    "content": "Estou interessado no Produto A.",

    "role": "user"

  }

]

Considerações Técnicas

Persistência do tool_call_id: O tool_call_id deve ser mantido consistente para garantir a correta associação do contexto entre solicitações e respostas.
Formato do Conteúdo: Certifique-se de que o conteúdo esteja claro e formatado corretamente para facilitar a interpretação pelo Agente de IA.
Sincronização de Papéis: A ordem dos papéis (tool, assistant, user) deve ser cuidadosamente observada para assegurar que a resposta final seja adequada e completa.

Para mais informações, acesse a discussão sobre o assunto em nossa comunidade ou os vídeos no nosso canal. 😃