A Integração de API personalizada permite conectar módulos da IA da SleekFlow, como o AgentFlow, a sistemas externos usando os detalhes da API fornecidos por você.
Com uma integração de API personalizada, seu agente de IA pode recuperar dados externos, acionar ações ou atualizar registros durante as conversas com os clientes. Isso permite que o agente ofereça suporte a fluxos de trabalho que exigem dados empresariais em tempo real, em vez de depender apenas de respostas estáticas da Base de conhecimento.
Por exemplo, seu agente pode:
- Criar links de pagamento por meio do seu sistema interno.
- Recuperar dados de clientes ou de assinaturas em um CRM.
- Pesquisar produtos ou gerar links de reserva.
- Acionar fluxos de trabalho de back-end com base nas solicitações dos clientes.
Você pode configurar uma integração de API personalizada descrevendo o caso de uso da API, carregando uma documentação de API compatível, colando a documentação relevante da API no chat de configuração ou colando um comando cURL bruto no chat de configuração. O construtor de API personalizada usa as informações fornecidas para gerar um esquema editável.
Antes de começar
Antes de configurar uma integração de API personalizada, verifique se você tem:
- Acesso à aba Integrações na IA da SleekFlow.
- Uma compreensão clara do que deseja que o agente de IA faça com a API.
- A documentação da API, os detalhes do endpoint ou os detalhes da solicitação do endpoint que deseja conectar.
- A chave de API, o token bearer ou os detalhes do cabeçalho de autenticação, caso a API exija autorização.
Se a aba Integrações não estiver disponível ou estiver bloqueada, entre em contato com seu Gerente de Sucesso do Cliente para habilitar ou atualizar o acesso.
Você também deve preparar as informações da API necessárias para a configuração. Isso pode incluir:
- Um arquivo de documentação de API compatível.
- O texto relevante da documentação da API.
- Um comando cURL bruto.
- Uma breve descrição do caso de uso da API.
Os formatos de arquivo compatíveis incluem:
.JSON.YAML.YML.PDF
Cada arquivo carregado pode ter até 1 MB.
Se o Copilot sugerir um endpoint ou gerar um esquema para você, sempre revise os detalhes antes de salvar a integração. Verifique o endpoint, a URL base, os cabeçalhos de autenticação, as entradas, as saídas e as descrições dos campos para garantir que correspondam aos requisitos da sua API.
Como funciona a Integração de API personalizada
A Integração de API personalizada define o esquema de API que o AgentFlow pode usar.
Isso inclui:
- Entradas: dados enviados à API.
- Saídas: dados retornados pela API.
- Descrições: informações que ajudam o agente a entender o significado de cada campo.
- Fonte de dados: origem de cada valor de entrada.
- URL base: host da API usado em conjunto com os caminhos dos endpoints.
As configurações da integração de API personalizada e a configuração do Playbook do AgentFlow têm finalidades diferentes.
| Área | Integração de API personalizada | Playbook do AgentFlow |
|---|---|---|
| O que faz | Define a estrutura da API que o AgentFlow pode usar | Define como o agente usa a API durante uma conversa |
| Foco | Configuração técnica, como entradas, saídas e esquema | Lógica da conversa, como quando chamar a API, quais informações coletar e como responder |
| Exemplo |
Define um campo booking_date e seu formato
|
Instrui o agente a solicitar a data da reserva antes de chamar a API |
| Onde configurar | IA da SleekFlow → aba Integrações | IA da SleekFlow → AgentFlow → agente → Configuração → Ações e Playbooks |
| Resultado | Disponibiliza a API no nível da empresa | Controla qual agente pode usá-la e como ela será usada nas conversas |
A integração de API personalizada controla o que a API pode fazer e quais campos estão disponíveis. Para controlar quando o agente deve coletar informações, chamar a API ou usar a resposta da API, atualize o Playbook do AgentFlow.
Salvar uma integração não a habilita automaticamente para todos os agentes. Você deve habilitar a integração e seus endpoints para cada agente em Configuração → Ações e, depois, fazer referência à API nas instruções do Playbook.
Configurar uma integração de API personalizada
Use o construtor de API personalizada para criar uma integração com base nas informações de API fornecidas por você. Você pode descrever o caso de uso da API, carregar uma documentação de API compatível, colar a documentação da API no chat de configuração ou colar um comando cURL bruto.
A SleekFlow usa essas informações para gerar um esquema editável. Sempre revise o esquema gerado antes de salvar a integração.
Etapa 1: iniciar uma nova integração de API personalizada
-
Clique no
ícone na barra de navegação esquerda para acessar a página IA da SleekFlow.
-
Na página IA da SleekFlow, clique em Integrações na barra de navegação superior.
- Você será redirecionado para a aba Integrações.
-
Clique em Adicionar integração, no canto superior direito.
Isso abrirá o fluxo de configuração para conectar uma API externa. Use a janela de configuração conversacional à esquerda para definir sua integração.
Em vez de preencher manualmente um formulário, você pode orientar a IA fornecendo detalhes da API, descrevendo seu caso de uso ou colando uma solicitação de API existente.
O esquema gerado pelo Copilot será exibido na tela de esquema à direita. Sempre revise e refine o esquema gerado antes de salvar a integração.
Por exemplo, você pode descrever casos de uso como:
- Criar um link de pagamento para um cliente.
- Recuperar o status de um pedido no seu CRM.
- Pesquisar horários de reserva disponíveis.
- Atualizar o perfil de um cliente em um sistema externo.
A descrição ajuda o Copilot a entender a ação da API que você deseja configurar.
Para casos de uso de APIs públicas, o Copilot pode sugerir um endpoint relevante para você confirmar antes de gerar o esquema. Para APIs internas ou privadas, forneça a documentação da API, os detalhes do endpoint ou um comando cURL bruto para que o Copilot gere o esquema com base na configuração da sua própria API.
Etapa 2: adicionar informações da API
Você pode fornecer as informações da API de diferentes maneiras, dependendo do que já tiver disponível.
Opção 1: descrever o caso de uso da API
Use essa opção quando souber o que deseja que o agente faça e puder fornecer informações suficientes sobre a API para que o Copilot gere o esquema completo.
A API pode ser pública ou privada. Você deve fornecer a documentação da API, os detalhes do endpoint ou outras informações técnicas necessárias para configurar a solicitação. As informações que devem ser fornecidas dependem de o Copilot conseguir acessar ou não a documentação da API.
Para uma API pública
Compartilhe um link para a documentação relevante da API e descreva a ação que deseja configurar. Sempre que possível, use um link direto para o endpoint ou para a seção específica da documentação, em vez da página principal da documentação da API.
Por exemplo:
“Use esse endpoint da API da Stripe para criar um link de pagamento com base no produto selecionado e no e-mail do cliente: [link da documentação da API].”
Fornecer um link específico da documentação ajuda o Copilot a identificar o endpoint correto sem precisar pesquisar em toda a documentação do provedor da API.
Para uma API privada
Descreva a ação que deseja que o agente execute e forneça todos os detalhes disponíveis do endpoint, os parâmetros da solicitação, os requisitos de autenticação ou exemplos de resposta.
Por exemplo:
“Recupere um pedido no nosso sistema interno usando o ID do pedido do cliente.”
O Copilot pode fazer perguntas de acompanhamento antes de gerar o esquema, caso sejam necessárias mais informações.
Observação: evite inserir apenas uma solicitação ampla, como “Conectar à Stripe”. Grandes provedores de API podem oferecer centenas de endpoints, e o Copilot talvez não consiga identificar o endpoint correto sem um caso de uso específico ou um link para a documentação.
Opção 2: carregar a documentação da API
Use essa opção quando tiver a documentação da API em um formato de arquivo compatível.
Os formatos de arquivo compatíveis incluem:
.JSON.YAML.YML.PDF
Cada arquivo carregado pode ter até 1 MB.
Depois de carregar o arquivo, o Copilot analisará a documentação e a usará para gerar o esquema.
Opção 3: colar a documentação da API
Use essa opção quando já tiver a documentação do endpoint de API que deseja configurar.
Você pode fornecer a documentação de uma das seguintes maneiras:
- Compartilhando um link para a documentação relevante da API.
- Colando os detalhes relevantes do endpoint diretamente no chat de configuração.
Sempre que possível, compartilhe um link que abra diretamente o endpoint ou a seção específica da documentação, em vez da página principal da documentação da API.
A documentação deve incluir detalhes como:
- URL do endpoint.
- Método da solicitação.
- Cabeçalhos obrigatórios.
- Parâmetros de consulta.
- Parâmetros de caminho.
- Corpo da solicitação.
- Exemplo de resposta.
Essa opção é útil quando você deseja configurar apenas um endpoint específico ou quando a documentação completa da API contém informações que não são relevantes para a ação.
Opção 4: colar um comando cURL bruto
Use essa opção quando já tiver uma solicitação de API funcional proveniente da documentação da API, das ferramentas de desenvolvedor do navegador, do Postman ou de um repasse da equipe de engenharia.
Cole o comando cURL bruto no chat de configuração. O Copilot poderá usar o comando cURL para identificar os detalhes da solicitação e gerar o esquema.
Observação: inserir um comando cURL bruto é um método alternativo de configuração. Mesmo assim, você deve revisar o esquema gerado antes de salvar a integração.
Etapa 3: revisar e refinar o esquema
Depois que o Copilot gerar o esquema, revise os campos na tela de esquema antes de salvar a integração.
O esquema define como o AgentFlow entende e usa a API. Descrições claras dos campos e configurações precisas ajudam o agente a chamar a API corretamente durante as conversas com os clientes.
Para cada endpoint, revise as seguintes seções:
| Seção | O que revisar |
| URL base | Verifique se a URL base está correta. A URL base é o host da API usado em conjunto com o caminho do endpoint. |
| Caminho do endpoint | Verifique se o caminho do endpoint corresponde à ação que deseja que o agente execute. |
| Método da solicitação | Verifique se o método da solicitação está correto, como GET, POST, PUT ou DELETE. |
| Entradas | Verifique os campos que a API precisa receber. Certifique-se de que cada descrição explique claramente qual valor deve ser fornecido. |
| Fonte de dados | Escolha se cada valor de entrada deve ser coletado pelo chat ou definido como um valor estático. |
| Saídas | Verifique os campos retornados pela API. Certifique-se de que cada descrição explique claramente o significado do campo. |
| Expor à IA | Ative essa opção somente para os campos de saída que o agente deve usar ao gerar uma resposta. Desative-a para campos irrelevantes para a conversa, desnecessários para o agente ou que contenham informações confidenciais. |
Revisar a URL base
A URL base é exibida na tela de esquema após a configuração.
Revise-a cuidadosamente antes de salvar a integração, principalmente se sua API tiver ambientes diferentes, como homologação e produção.
A URL base funciona em conjunto com o caminho do endpoint para determinar para onde a solicitação de API será enviada.
Aviso: se a URL base estiver incorreta, as chamadas da API poderão falhar ou ser enviadas para o ambiente errado.
Revisar entradas e fonte de dados
Na seção Entradas, verifique os campos que a API precisa receber.
Para cada entrada, revise:
- Nome do campo.
- Descrição.
- Fonte de dados.
- Valor estático, se usado.
A descrição do campo deve explicar claramente qual valor é necessário. Isso ajuda o agente a mapear as informações do cliente para o campo correto da API.
Revisar saídas e a opção Expor à IA
Na seção Saídas, verifique os campos retornados pela API.
Ative Expor à IA somente para os campos que o agente deve usar ao gerar respostas para os clientes.
Desative essa opção para campos que:
- Não sejam úteis para a conversa.
- Sejam necessários apenas para processamento de back-end.
- Contenham informações confidenciais.
- Possam confundir o agente se forem expostos.
Dica: exponha apenas os campos de saída necessários para a resposta do agente. Isso ajuda a manter as respostas objetivas e reduz informações desnecessárias.
Observação: a configuração da integração define os campos e as descrições da API. Para controlar quando o agente deve coletar informações, chamar a API ou usar a resposta da API, atualize o Playbook do AgentFlow.
Etapa 4: definir como os valores de entrada são fornecidos
Na seção Entradas, use a coluna Fonte de dados para escolher como cada valor de entrada será fornecido. Você pode selecionar Coletar pelo chat ou Valor estático.
Coletar pelo chat
Selecione Coletar pelo chat quando o valor precisar ser obtido do cliente durante a conversa.
Use essa opção para informações que possam variar para cada cliente ou solicitação, como e-mail, data da reserva, preferência de produto ou número do pedido.
Ao usar Coletar pelo chat:
- Certifique-se de que a descrição do campo explique claramente quais informações são necessárias.
- Atualize o Playbook do AgentFlow para que o agente saiba quando solicitar essas informações ao cliente.
- Teste o agente para confirmar que o valor coletado é mapeado para o campo correto da API.
Valor estático
Selecione Valor estático quando o mesmo valor precisar ser enviado sempre que a API for chamada.
Use essa opção para valores fixos, como um parâmetro padrão do sistema, código de região, sinalizador interno ou identificador de canal.
Ao usar Valor estático:
- Insira o valor fixo no campo Valor.
- Verifique se o valor corresponde ao formato exigido pela sua API.
- Salve as alterações antes de testar a integração no AgentFlow.
Observação: a Fonte de dados controla a origem do valor de entrada. A descrição do campo explica o significado do valor. O Playbook do AgentFlow controla quando o agente deve coletar ou usar esse valor.
Etapa 5: salvar e publicar a integração
Antes de salvar, revise os detalhes da integração para garantir que estejam corretos.
Verifique se:
- O esquema do endpoint está correto.
- Cada entrada tem a descrição e a fonte de dados corretas.
- Os valores estáticos foram inseridos corretamente, se usados.
- As descrições das saídas estão claras.
- Somente os campos de saída apropriados estão expostos à IA.
Quando estiver tudo pronto, clique em Salvar.
Depois de salvar, a integração de API personalizada ficará disponível para os módulos compatíveis da IA da SleekFlow, como o AgentFlow.
Observação:
- Você pode editar e salvar novamente a integração depois que ela for criada. Após fazer alterações, revise e teste todos os Playbooks do AgentFlow que usam essa integração.
- Depois de salvar, a URL base continuará visível na tela de esquema e na página de detalhes da integração para referência futura.
- Se a URL base estiver incorreta, as chamadas da API poderão falhar ou ser enviadas para o ambiente errado.
Gerenciar sua integração de API personalizada
Você pode gerenciar sua integração de API personalizada depois de adicioná-la à SleekFlow.
Siga as etapas abaixo para gerenciar suas integrações de API personalizada:
-
Clique no
ícone na barra de navegação esquerda para acessar a página IA da SleekFlow.
- Na página IA da SleekFlow, clique em Integrações na barra de navegação superior.
-
Você será redirecionado para a página Integração de API personalizada, onde encontrará as APIs personalizadas adicionadas ao espaço de trabalho da SleekFlow.
Você pode abrir uma integração de API personalizada para revisar sua configuração, incluindo o nome da integração, as configurações de autenticação, a URL base, o esquema dos endpoints, as entradas, as saídas e os agentes atribuídos.
Editar uma API personalizada
Importante: alterações em entradas, saídas, descrições de campos, caminhos de endpoints ou nomes de comandos do Playbook podem afetar o comportamento do agente. Depois de editar uma integração, revise e teste a configuração do AgentFlow para garantir que tudo funcione conforme o esperado.
Depois de criar uma integração de API personalizada, você poderá atualizar sua configuração a qualquer momento. Isso permite refinar entradas, ajustar saídas ou atualizar a autenticação à medida que a API ou o caso de uso evoluem.
Para editar uma API personalizada:
- No painel de integrações de API personalizada, localize a API personalizada que deseja editar.
- Clique na API personalizada.
- Você será redirecionado para a página de detalhes da API personalizada.
Atualizar o nome da integração
Você pode renomear sua integração de API personalizada para representar melhor sua finalidade. Use um nome claro e descritivo para facilitar sua identificação ao selecionar a integração no AgentFlow.
Observação: atualizar o nome da integração não afeta a configuração da API nem a forma como ela é usada nas configurações existentes do AgentFlow.
Revisar a URL base
A URL base fica visível na página de detalhes da API personalizada.
Use esse campo para verificar qual host ou ambiente da API é usado pela integração. Isso é especialmente útil quando sua API tem ambientes diferentes, como homologação e produção.
Você não precisa mais solicitar que o agente construtor recupere a URL base depois que a integração for criada.
Aviso: se a URL base estiver incorreta, as chamadas da API poderão falhar ou ser enviadas para o ambiente errado.
Atualizar as configurações de autenticação
Na seção Autenticação, você pode configurar ou atualizar as credenciais da API.
- Clique em Atualizar chave para modificar sua chave de API ou token bearer.
- Certifique-se de que o método de autenticação corresponda aos requisitos da sua API.
As alterações feitas nessa seção afetam a autorização de todas as solicitações de API.
Editar o esquema dos endpoints
Na seção Esquema dos endpoints, você pode revisar os endpoints incluídos na integração de API personalizada.
Cada endpoint mostra o método da solicitação, o caminho do endpoint e uma breve descrição do que ele faz. Você pode expandir um endpoint para revisar sua configuração. Analise esses detalhes em conjunto com a URL base para garantir que a solicitação seja enviada ao endpoint correto da API.
Clique em Adicionar/Editar endpoints para atualizar o esquema dos endpoints, adicionar endpoints ou removê-los caso a configuração da API seja alterada.
Atualizar o nome do comando do Playbook
Cada endpoint tem um nome de comando do Playbook.
Esse é o nome do comando usado ao configurar a integração no AgentFlow. Use um nome claro e facilmente reconhecível que descreva a ação, como /get_available_slots ou /create_booking.
Se você renomear um comando que já esteja sendo usado por um agente, revise a configuração correspondente do AgentFlow para garantir que o agente ainda faça referência ao comando correto.
Editar entradas
Na seção Entradas, revise os campos que a API precisa receber.
Para cada entrada, você pode:
- Atualizar a descrição.
- Selecionar a Fonte de dados.
- Inserir um valor quando a fonte de dados estiver definida como Valor estático.
Dicas:
- Use Coletar pelo chat quando o agente precisar obter o valor do cliente durante a conversa.
- Use Valor estático quando o mesmo valor precisar ser enviado sempre que o endpoint for chamado.
As descrições das entradas devem explicar claramente qual valor é necessário. Isso ajuda o agente a mapear as informações coletadas para o campo correto da API.
Editar saídas
Na seção Saídas, revise os campos retornados pela API.
Para cada saída, você pode:
- Atualizar a descrição.
- Ativar ou desativar Expor à IA.
Ative Expor à IA para os campos que o agente deve poder usar nas respostas aos clientes. Desative essa opção para campos que não sejam úteis para a conversa ou que não devam ser disponibilizados ao agente.
Dica: exponha somente os campos de saída necessários para a resposta do agente. Isso ajuda a manter as respostas objetivas e reduz informações desnecessárias.
Revisar os agentes atribuídos
Na parte inferior da página, verifique Agentes atribuídos para ver quais agentes estão usando essa integração no momento.
Se um agente estiver listado, você poderá gerenciar como a integração é usada na configuração desse agente.
Salvar suas alterações
Depois de fazer as atualizações, clique em Salvar alterações na parte inferior da página.
As atualizações serão aplicadas à integração de API personalizada. Depois de salvar, revise e teste todas as configurações do AgentFlow que usam essa integração, principalmente se você tiver alterado nomes de comandos, detalhes de endpoints, entradas, saídas ou campos expostos.
Excluir uma API personalizada
Para excluir uma API personalizada:
- No painel de integrações de API personalizada, localize a API personalizada que deseja excluir.
-
Clique no
ícone ao lado da API personalizada.
-
Selecione Excluir.
- Uma mensagem de aviso será exibida. Clique em Excluir para confirmar a ação.