Criando Agentes

O que é um agente no SquadOS?

Um agente reúne instruções, modelo de IA, ferramentas, conhecimento, formas de entrada e regras de segurança. É essa configuração que determina o que ele pode responder ou executar em uma conversa.

Criar o registro é apenas o começo. Um agente novo ainda precisa de um prompt claro, dos acessos corretos e de testes antes de atender clientes.

Antes de criar

Defina, em linguagem simples:

• qual problema o agente resolve;
• quem conversa com ele;
• quais informações ele pode consultar;
• quais ações ele pode executar;
• quando deve recusar, pedir ajuda ou transferir a conversa.

Você precisa da permissão agents.write (editar agentes). O botão de criação também pode ficar indisponível quando o plano atingiu o limite de agentes ativos, não há modelo padrão ou sua função não permite nenhuma categoria válida. O contador da página considera somente agentes ativos.

Criar manualmente

No menu do painel, abra Agentes e siga estes passos:

1. Selecione Novo Agente.
2. Preencha Nome do agente. Use um nome que identifique a função, como Assistente de Suporte ou SDR de Vendas.
3. Em Categoria inicial, escolha uma categoria ou Sem categoria. Para algumas funções com escopo restrito, escolher uma categoria permitida é obrigatório.
4. Selecione Criar Agente.

O SquadOS usa o modelo padrão da organização e cria o agente com prompt vazio, status ativo e entrada do Hub habilitada. Nenhum WhatsApp, Telegram, Instagram, widget, página pública ou API é conectado nesse momento.

Em telas maiores, o editor abre com o AgentMaker exibido para ajudar na configuração inicial. Em telas móveis, o editor abre sem esse painel automático. Você pode abrir ou fechar o AgentMaker pelo botão no topo do editor.

O agente já nasce ativo

Como o novo agente já aparece como ativo e pode ficar disponível no Hub, não o trate como pronto. Se a organização não quiser expor uma configuração incompleta, abra Avançado e desative o agente enquanto prepara e testa o conteúdo.

Se a criação mostrar erro, volte à lista e procure pelo nome antes de repetir. Hoje, o agente e suas entradas são gravados em etapas separadas; uma falha na segunda etapa pode deixar o agente criado apesar da mensagem de erro.

Outras formas de começar

• A Galeria de Agentes importa um modelo publicado para a organização. Revise prompt, modelo, ferramentas e categoria depois da importação; ela também cria o agente ativo e com Hub habilitado.
• Importar Skill é uma prévia exclusiva para superadministradores. Ela transforma um arquivo SKILL.md em um agente inativo para revisão e não instala automaticamente as ferramentas descritas no arquivo. Veja Ferramentas e Skills.

Identidade e retrato

O agente recebe um robô gerado a partir de uma semente. Para personalizá-lo, abra Prompt e selecione o retrato ao lado do nome.

O montador oferece seis grupos: Olhos, Topo, Peito, Corpo, Acento e Luz. Topo e Peito também aceitam Nenhum.

• Sortear cria outra combinação completa.
• Voltar ao aleatório remove as escolhas fixadas.
• Aplicar usa a combinação no formulário; Cancelar fecha sem aplicá-la.

O editor atual não oferece upload de imagem própria para o retrato de um agente comum.

As oito seções do editor

Cada item da barra lateral abre uma área independente:

• Prompt — nome, descrição e instruções do agente. Especifique papel, objetivo, contexto, limites, tom e critérios de transferência.
• Ferramentas — ações que o agente pode executar. Ative apenas o necessário e confira as permissões e contas exigidas. Veja Ferramentas Nativas.
• Conhecimento — bases vetoriais, blocos de contexto e AutoLearn. Conhecimento é conectado nesta seção; não é uma ferramenta adicionada pelo seletor. Veja Bases de Conhecimento.
• Caixas de Entrada — mostra por onde as conversas chegam. A conexão e a manutenção do canal acontecem na página Caixas de Entrada do painel. Veja Caixas de Entrada.
• Modelo — define o modelo de IA, o raciocínio quando suportado e parâmetros relacionados ao modelo.
• Multimodal — controla como imagens, arquivos e áudios recebidos são processados.
• Segurança — configura o guardrail contra jailbreak e injeção de prompt. Veja Guardrails.
• Avançado — reúne status ativo, categoria, histórico, tamanho da resposta, uso de ferramentas, temperatura, quebra de mensagens e ações de arquivamento ou exclusão. Veja Configurações Avançadas.

Cada seção mantém suas próprias alterações. Use Salvar na seção atual antes de trocar de página. Se você tentar sair com conteúdo pendente, o editor permite Descartar e continuar ou Continuar editando. O teste sempre usa a versão já salva, não o rascunho visível.

Configuração mínima recomendada

Antes do primeiro teste:

1. Em Prompt, escreva instruções autocontidas e salve.
2. Em Conhecimento, conecte somente as fontes necessárias.
3. Em Ferramentas, habilite apenas ações que o agente realmente deve executar.
4. Em Modelo, confirme o modelo e o custo esperado.
5. Em Segurança e Avançado, confira guardrail, histórico, limites e status.
6. Em Caixas de Entrada, confirme que nenhuma entrada externa foi conectada antes da validação.

Testar a versão salva

Selecione Testar Agente no topo do editor. O botão fica indisponível enquanto o agente está inativo.

O teste abre um painel dentro do próprio editor. No primeiro envio, o SquadOS cria uma conversa persistente do tipo direta com o agente; ela também pode ser encontrada no Hub. Pelo menu do painel, você pode retomar uma das 20 conversas de teste mais recentes desse agente ou iniciar outra.

Se houver alterações não salvas, o painel avisa que está usando a versão anterior. Selecione Salvar e testar para salvar a seção atual antes de conversar.

Teste pelo menos:

• uma solicitação principal completa;
• uma pergunta sem informação suficiente;
• uma pergunta fora do escopo;
• uma ação de cada ferramenta habilitada, sem usar dados destrutivos;
• uma resposta que dependa exclusivamente da base conectada;
• imagem, arquivo ou áudio, quando o agente aceitar esses formatos;
• recusa, transferência e limites de segurança.

Conectar canais

Depois de revisar o resultado, abra Caixas de Entrada no menu do painel e conecte o canal desejado ao agente. Cada caixa tem ciclo de vida, credenciais e estado próprios; criar o agente não publica automaticamente WhatsApp, Telegram, Instagram, widget, página pública ou API.

Consulte a Visão geral dos gatilhos para escolher o tipo e siga o guia da caixa correspondente.

Checklist antes de atender clientes

• O prompt foi salvo e testado com casos reais e fora de escopo.
• Bases e ferramentas respeitam o mínimo acesso necessário.
• Modelo, limites e custo esperado foram conferidos.
• Guardrail e comportamento de transferência foram validados.
• O agente está ativo somente quando deve receber conversas.
• Cada caixa conectada aponta para o agente correto.
• A equipe sabe onde acompanhar as Conversas.