Agentes Inteligentes SipPulse AI

Este documento é o guia de referência central para compreender, configurar e operar Agentes na plataforma SipPulse AI. Ele detalha conceitos fundamentais, funcionalidades e melhores práticas para maximizar o potencial dos seus Agentes.

O que é um Agente SipPulse AI?

Um Agente na SipPulse AI é uma entidade de software sofisticada que atua como um orquestrador inteligente. Utilizando um Modelo de Linguagem Grande (LLM) como seu "cérebro" computacional, um Agente é projetado para:

1. Conduzir Diálogos Coerentes: Manter conversas naturais e contextualmente relevantes com os usuários
2. Gerenciar Memória e Contexto: Reter informações de interações passadas para informar respostas futuras, garantindo continuidade
3. Executar Ferramentas (Tool Calls): Interagir com sistemas externos e internos de forma autônoma, como APIs, bases de conhecimento (RAG), e funcionalidades de telefonia (SIP)

Esta capacidade de integrar diálogo, memória e ação em um fluxo unificado distingue fundamentalmente um Agente de um LLM "puro".

LLM vs. Agente SipPulse AI

Compreender a distinção entre um LLM "puro" e um Agente SipPulse AI é crucial para arquitetar soluções eficazes:

Característica	LLM "Puro" (Tradicional)	Agente SipPulse AI
Propósito Principal	Geração de texto com base em um prompt	Orquestração de tarefas, diálogo e execução de ferramentas para atingir objetivos
Execução de Ferramentas	Pode sugerir a chamada de uma função (geralmente em JSON ou texto), mas não a executa	Executa ativamente APIs, RAG, SIP e outras ferramentas configuradas
Memória e Contexto	Geralmente sem estado. O histórico da conversa precisa ser enviado explicitamente a cada chamada	Mantém e gerencia ativamente o histórico e o contexto da conversa
Orquestração de Fluxo	O desenvolvedor controla o fluxo lógico, decidindo quando chamar o LLM e quando executar código externo	O Agente, guiado por suas instruções, decide autonomamente quando e como utilizar cada ferramenta
Acesso a Dados	Limitado ao conhecimento com o qual foi treinado e ao que é fornecido no prompt atual	Pode conectar-se dinamicamente a bases de dados internas, APIs de terceiros, calendários, sistemas CRM, etc.
Autonomia	Baixa. Reage a cada entrada de forma isolada	Alta. Pode realizar múltiplos passos para resolver um problema ou completar uma tarefa

Dica Estratégica

Ao usar um LLM "puro" para tarefas que exigem interação com o mundo exterior (ex: buscar dados de um pedido), seu código precisa:

1. Interpretar a intenção do usuário
2. Pedir ao LLM para formatar os parâmetros para uma API
3. Extrair esses parâmetros da resposta do LLM
4. Chamar a API externa
5. Receber a resposta da API
6. Injetar essa resposta de volta no LLM para que ele formule uma resposta ao usuário

Com um Agente SipPulse AI, você define o schema da ferramenta (ex: "buscarStatusPedido" com parâmetro "numeroPedido"). O Agente lida com a extração de parâmetros, a chamada da ferramenta e a utilização do resultado de forma transparente e integrada ao fluxo da conversa.

Boas Práticas

Adotar estas práticas pode melhorar significativamente a eficácia, confiabilidade e manutenibilidade dos seus Agentes:

Comece Simples e Itere

• Por quê: Tentar construir um Agente excessivamente complexo desde o início pode levar a dificuldades de depuração e resultados imprevisíveis
• Como: Inicie com um conjunto mínimo de instruções claras e uma ou duas ferramentas essenciais. Teste exaustivamente e adicione complexidade gradualmente

Mantenha Instruções Focadas

• Por quê: Instruções muito longas ou com informações desnecessárias podem confundir o LLM, aumentar a latência e os custos
• Como: Priorize o uso de tool calls para buscar informações dinâmicas em vez de "colar" grandes volumes de dados diretamente nas instruções

Priorize a Clareza nas Instruções de Ferramentas

• Por quê: O Agente depende da descrição das ferramentas para entender quando e como usá-las. Descrições ambíguas levam a erros
• Como: Seja muito claro sobre o propósito da ferramenta, os parâmetros que ela aceita e o que ela retorna. Forneça exemplos se possível. Não é preciso repetir a descrição da ferramenta nas instruções do Agente, pois ela já está disponível para o LLM

Teste Rigorosamente antes de Implantar

• Por quê: Agentes podem interagir com sistemas críticos e dados sensíveis. Testes inadequados podem levar a erros custosos em produção
• Como: Utilize a plataforma para interagir com o Agente em um ambiente de teste. Simule uma variedade de cenários, incluindo casos de borda e entradas inesperadas. Verifique se o Agente responde corretamente e executa as ferramentas conforme esperado

Teste diferentes modelos

• Por quê: Diferentes modelos têm capacidades e limitações distintas. O que funciona bem em um modelo pode não funcionar em outro
• Como: Teste seu Agente com vários modelos disponíveis na plataforma. Compare o desempenho em termos de precisão, latência e custo. Escolha o modelo que melhor atende às suas necessidades

Importar e Exportar Agentes

A plataforma permite exportar e importar configurações de agentes em formato JSON, facilitando backup, compartilhamento e migração entre organizações.

Exportar um Agente

Para exportar a configuração de um agente:

1. Navegue até Agentes no menu lateral
2. Localize o agente desejado na lista
3. Clique no menu de ações (⋮) do agente
4. Selecione Exportar Agente
5. Um arquivo JSON será baixado com o nome do agente (ex: Secretária.json)

O que é exportado:

• Nome e descrição do agente
• Instruções do sistema
• Configurações do modelo LLM
• Parâmetros (temperatura, top_p, max_tokens)
• Configurações de voz (TTS)
• Ferramentas configuradas (APIs, RAG, built-in)
• Análises pós-conversa

O que NÃO é exportado:

• ID do agente
• Configurações de deploy (WhatsApp, SIP, Chat Widget)
• Histórico de conversas
• Dados da organização

Importar um Agente

Para importar um agente a partir de um arquivo JSON:

1. Navegue até Agentes no menu lateral
2. Clique no botão Importar
3. Selecione o arquivo .json do agente
4. O formulário de criação será preenchido com as configurações do arquivo
5. Revise as configurações e faça ajustes se necessário
6. Clique em Criar para salvar o novo agente

Dica

Use a funcionalidade de importar/exportar para:

• Backup: Mantenha cópias de segurança de agentes críticos
• Compartilhamento: Compartilhe configurações de agentes com colegas ou outras equipes
• Migração: Mova agentes entre organizações ou ambientes
• Versionamento: Salve versões diferentes de um agente durante o desenvolvimento

Atenção

Ao importar um agente, as configurações de deploy (WhatsApp, SIP, Chat Widget) não são incluídas. Você precisará configurar novamente os canais de deploy após a importação.