Squads e Multi-Agente

No SquadOS, squad não é um objeto, uma página nem um tipo especial de agente. É um padrão de arquitetura: você cria agentes comuns, especializa cada um e conecta as saídas com a ferramenta Transferir Conversa.

O desenho mais comum tem um agente de triagem, especialistas e, se necessário, atendimento humano. Cada agente conserva seu próprio prompt, modelo, ferramentas, bases de conhecimento e configurações.

Quando separar agentes

Mantenha um agente único quando o escopo é coerente, o prompt continua claro e quase todas as conversas usam as mesmas ferramentas e conhecimentos.

Separe em vários agentes quando houver pelo menos uma fronteira operacional real, como:

• áreas com responsabilidades diferentes, por exemplo Vendas, Suporte e Financeiro;
• ferramentas ou bases que só um especialista deve usar;
• modelos, limites ou instruções muito diferentes;
• passagem obrigatória para uma pessoa em determinados casos ou horários.

Não crie um agente apenas para cada intenção. Mais transferências aumentam custo, pontos de falha e risco de perda de contexto. A divisão deve acompanhar quem decide e quem executa.

Desenhe a topologia antes de configurar

Liste cada agente e registre:

Papel	Recebe de	Resolve	Pode transferir para
Triagem	caixa de entrada	classificação inicial	especialistas ou humano
Especialista	triagem	um domínio definido	humano ou outro destino excepcional
Humano	agentes	exceções e decisões reservadas	fila ou responsável

Prefira um fluxo simples, com critérios de saída inequívocos. O SquadOS não oferece um editor visual de grafo nem valida ciclos persistentes. O agente que acabou de receber uma conversa não pode repassá-la a outro agente no mesmo turno, mas a ferramenta volta a ficar completa na próxima mensagem do cliente; por isso A → B e B → A ainda pode oscilar ao longo da conversa se os motivos forem vagos.

Monte o fluxo

1. Crie cada agente e defina um escopo exclusivo no prompt.
2. Abra o agente que encaminhará a conversa e acesse Ferramentas.
3. Adicione Transferir Conversa e selecione Adicionar contexto.
4. Em Quando transferir, descreva um único motivo observável na fala do cliente.
5. Se necessário, restrinja o motivo em Só quando por tag da conversa, tag do contato, canal ou caixa de entrada. Todas as condições configuradas precisam valer.
6. Em Para quem vai, defina faixas de horário e destino. A primeira faixa compatível ganha; Fora desses horários é usado quando nenhuma faixa cobre o momento.
7. Use Não transferir fora do horário quando o agente deve continuar atendendo. Sem isso, escolha outro agente, uma pessoa ou a Fila geral do time.
8. Salve a ferramenta e repita no agente de origem de cada ligação. Não existe uma configuração central do squad.

O modelo escolhe somente o contexto descrito em Quando transferir. Filtros, horário e destino são resolvidos pelo SquadOS. Consulte todos os campos em Transferir Conversa.

O que acontece em cada destino

Outro agente

Em conversas diretas, o agente de destino se torna o responsável e responde imediatamente com o próprio prompt, contexto organizacional, modelo e ferramentas. Se o agente de origem escreveu uma confirmação breve, essa mensagem pode ser entregue antes da resposta do especialista.

O destino pode escalar para uma pessoa no turno de entrada. Para impedir cascatas, ele não pode transferir para outro agente nesse mesmo turno; essa opção volta na próxima mensagem do cliente.

Pessoa ou fila

A IA é desligada na conversa e o atendimento entra na operação humana. Uma pessoa específica recebe a atribuição; na Fila geral do time, alguém precisa assumir. O webhook opcional da seção Avançado só se aplica quando existe destino humano e deve usar HTTPS.

Salas do Hub

Em Salas, a transferência não troca o dono da conversa inteira. Ela cria uma execução filha na mesma thread, e o agente de destino precisa participar da Sala. Há ainda um defeito confirmado na validação da configuração unificada que pode recusar destinos legítimos; valide esse percurso separadamente antes de depender dele.

Continuidade de contexto

As mensagens permanecem na conversa, mas não prometa que o agente de destino lerá todo o histórico. O runtime envia uma janela recente limitada pelo agente de origem e, no caminho de streaming, busca dez mensagens. O resumo que representa mensagens antigas é uma instrução de sistema do agente anterior e não é repassado na transferência.

Para uma passagem confiável:

• escreva o motivo com informação suficiente para orientar a próxima ação;
• mantenha fatos duráveis em Anotações, contato ou sistemas próprios, não apenas em mensagens antigas;
• não exija que o especialista recupere uma resposta que pode ter saído da janela;
• teste conversas longas, inclusive com dados importantes fornecidos no início.

Custo e controles relacionados

Uma passagem entre agentes pode consumir uma chamada do agente de origem e outra do destino. As duas usam seus respectivos modelos e entram no consumo da conversa. A entrega para humano não chama um segundo agente, embora ferramentas executadas antes do handoff possam ter custo ou efeito próprio.

A restrição de agentes configurada na caixa de entrada controla transferência manual feita por uma pessoa. Ela não substitui os destinos da ferramenta Transferir Conversa. A lista somente leitura Agentes que transferem, na área Gatilhos do agente de destino, também pode aparecer vazia para configurações feitas pela ferramenta unificada; confira sempre o agente de origem.

Checklist de validação

Use Testar Agente com a versão salva e cubra:

• uma frase que deve escolher cada contexto;
• uma frase parecida que não deve transferir;
• cada combinação relevante de filtros;
• dentro, fora e na borda das faixas de horário, usando o fuso da organização;
• destino inativo, arquivado ou removido;
• conversa longa, para verificar quais fatos chegam ao especialista;
• handoff humano e reativação posterior da IA;
• cada Sala usada pelo fluxo, separadamente das conversas diretas;
• custo, mensagem do agente de origem e primeira resposta do destino.

O painel de teste usa o runtime real: ele pode persistir mensagens, consumir créditos e executar ferramentas com efeitos externos. Use dados de teste seguros.