Canais

Coloque seus agentes no Telegram, no WhatsApp, no Slack e em outros lugares. Como os canais funcionam, quem pode falar com eles e como arquivos e repasses são entregues.

Um canal conecta um dos seus agentes a um lugar onde as pessoas já conversam. Alguém envia uma mensagem, o Pepe executa o agente vinculado (chamando ferramentas e lendo a resposta de volta), e a resposta é entregue no mesmo canal. Você não escreve nenhum código de ligação. Você adiciona uma conexão, aponte-a para um agente e pronto, funciona.

Tudo nesta página pressupõe que você já tem pelo menos um agente definido. Se ainda não tem, veja primeiro o guia de agentes.

Três maneiras de configurar

Como o resto do Pepe, os canais podem ser gerenciados de três maneiras, e esta página mostra cada uma onde ela se aplica:

1. A linha de comando pepe.
2. O painel web (a seção “Channels” lista seus bots e conexões, e te guia na hora de adicionar um).
3. Por chat. Um agente que tem a ferramenta de gerenciamento certa pode criar e revincular bots do Telegram, entregar arquivos e encerrar uma conversa, tudo em linguagem comum. Essas ações são protegidas, então leia as notas “Faça por chat” mais abaixo para saber o passo exato de confirmação.

Se você está vindo de outro runtime de agentes, o pepe migrate importa os canais que já existem lá, em vez de você adicionar cada um na mão.

Duas formas de canal

Os canais diferem apenas em como uma mensagem chega até o Pepe:

• Telegram é um bot de que o próprio Pepe busca as mensagens, então nada do seu lado precisa ficar acessível na internet. Adicione um token, vincule a um agente, execute o gateway.
• Canais por webhook (WhatsApp, Slack, Discord, Microsoft Teams, Google Chat e uma rota de entrada genérica) recebem mensagens que a plataforma entrega em um endereço no seu servidor, então o Pepe precisa estar acessível pela internet. O Pepe expõe uma URL por conexão. Você a registra uma única vez com o provedor.

Todo canal por webhook, qualquer que seja a plataforma, é servido pelo mesmo endpoint de entrada:

/webhooks/:project/:provider/:slug

:project é o projeto ao qual a conexão pertence, e é default quando você não cria projetos adicionais. :provider é o nome da plataforma, e :slug é o nome que você deu à conexão. Adicionar um provedor nunca adiciona um endpoint novo.

Estes são os canais por webhook que já vêm com o Pepe, e o que cada um precisa:

O Chatwoot também está disponível, como um plugin de canal em vez de uma conexão nativa. Ele fica na frente do WhatsApp, do widget web e de outros, e traz repasse nativo para um humano. Os plugins de canal são configurados na aba Integrations do painel, e não na Channels.

Notas de configuração por canal

• Slack. Crie um app, adicione um escopo de bot token, ative as Event Subscriptions e aponte a request URL para a URL da conexão. O Pepe responde sozinho ao desafio url_verification. Adicione os eventos message.channels e app_mention. O signing secret verifica cada requisição. Veja Slack.
• Discord. Isso usa o endpoint de Interactions, e não um bot de gateway, então ele responde a comandos de barra. Adicione um comando com uma opção de texto e depois aponte a “Interactions Endpoint URL” do app para a URL da conexão. A public key do app verifica a assinatura Ed25519. O comando é confirmado na hora e a resposta chega como follow-up. Veja Discord.
• Microsoft Teams. Registre um bot no Azure e aponte o messaging endpoint dele para a URL da conexão. O Pepe responde ao serviceUrl da activity com um token gerado a partir das credenciais do app. O JWT do Bot Framework que chega é validado, então o endpoint aceita POSTs vindos diretamente da Microsoft. Veja Microsoft Teams.
• Google Chat. Configure o endpoint de webhook (HTTP) do app para a URL da conexão e forneça um access_token OAuth da Chat API. As respostas são publicadas de volta no espaço. Mantenha o endpoint atrás de um proxy. Veja Google Chat.

Vinculação, sessões e os dois modos

Cada conexão (e cada bot do Telegram) nomeia um agent. Essa é a vinculação. Cada remetente distinto ganha a própria conversa, então o contexto é mantido por pessoa sem que você gerencie nada.

Uma conexão por webhook também tem um mode que muda como o runtime se comporta:

Suporte é o padrão seguro para qualquer coisa que o público possa alcançar. Combine com um agente restrito (só ferramentas seguras, já que não há uma pessoa do seu lado para aprovar uma ação arriscada) e, se quiser, um tempo limite de sessão ociosa. Admin é para um canal que só você usa, onde os comandos de barra e a memória são úteis.

Alguns campos ajustam isso por conexão:

• agent: o agente ao qual esta conexão está vinculada.
• mode: support ou admin.
• trainers: quem pode transformar uma conversa em memória. ["*"] é todos, [] é ninguém, uma lista são apenas aqueles remetentes, ausente é o padrão (todos).
• session_ttl_min: minutos de inatividade antes de a conversa ser descartada.
• ephemeral: quando verdadeiro, o histórico não é levado entre mensagens.
• commands: se os comandos de barra são atendidos (ligados por padrão no admin).

Como uma conexão aparece na configuração

Não há banco de dados. As conexões vivem em ~/.pepe/config.json sob webhooks, indexadas por slug. Os segredos são escritos como ${ENV_VAR} e lidos em tempo de execução, nunca expandidos em disco. Uma conexão de suporte do Slack aparece assim:

{
  "webhooks": {
    "support": {
      "provider": "slack",
      "agent": "helpdesk",
      "mode": "support",
      "config": {
        "bot_token": "${SLACK_BOT_TOKEN}",
        "signing_secret": "${SLACK_SIGNING_SECRET}"
      }
    }
  }
}

Você pode editar esse arquivo à mão, mas a linha de comando e o painel o mantêm válido para você.

Enviar arquivos

Um agente pode entregar um arquivo para quem está conversando. Ele produz o arquivo do jeito que preferir (por exemplo um passo bash que consulta um banco de dados e escreve um .xlsx), e então chama a ferramenta send_file com o caminho:

{
  "path": "/tmp/report.xlsx",
  "caption": "Aqui está o relatório desta semana."
}

O Pepe descobre em qual canal a conversa está e entrega o arquivo ali. O agente nunca precisa de ids de chat nem de tokens. O Telegram envia como documento. O WhatsApp, o Slack e o Discord sobem como mídia nas APIs deles. Se o canal atual não puder receber anexos (o Microsoft Teams e o Google Chat enviam só texto), a ferramenta informa isso de volta ao agente em vez de falhar em silêncio.

Faça pela conversa

A entrega de arquivos é, ela mesma, uma capacidade pela conversa. Qualquer agente com a ferramenta send_file faz isso no momento em que você pede. Você diria:

Puxe os cadastros da semana passada e me mande a planilha.

O agente roda o passo que monta o arquivo, e então chama send_file com o caminho resultante. Não há uma barreira de confirmação separada no send_file; ele só entrega no próprio canal da conversa atual, resolvido a partir da sessão, então ele não consegue vazar um arquivo para mais ninguém.

Encerrar uma conversa

Um agente de suporte pode fechar a própria conversa depois que uma troca termina, para que a próxima mensagem daquela pessoa comece do zero. Um agente com a ferramenta end_session faz isso pela conversa:

Obrigado, era só isso.

O agente envia primeiro a resposta final, e então chama end_session, que limpa o contexto da conversa em andamento. O conhecimento aprendido dele fica intacto. Só a conversa atual é reiniciada. Isso é útil em um canal em modo support onde cada troca deveria ser independente.

Roteamento entre agentes

Além de vincular um canal a um agente, um agente que tem a ferramenta set_route pode mudar quais agentes podem mandar mensagem para quais, pela conversa. O roteamento é direcionado, então permitir que o agente A escreva para o agente B não permite que B escreva para A. Como ela edita a configuração, passa pela trava de permissão: você confirma a mudança antes de ela valer. Você diria:

Deixe o agente de triagem repassar para o agente de faturamento.

O agente chama set_route com to: "billing" (e from assume por padrão aquele com quem você está falando), ou action: "deny" para remover uma rota. Na linha de comando, a mesma coisa é pepe agent route triage billing.

O que não vem embutido

Signal, IRC e iMessage precisam de uma conexão persistente ou de uma ponte específica da plataforma, que não cabe no modelo de webhook, então por enquanto estão fora de escopo. Um canal novo sempre pode ser acrescentado como um plugin de canal.

Servir tudo

Um único comando serve a API HTTP compatível com OpenAI, o WebSocket, o painel, a rota de webhook e cada bot do Telegram configurado:

pepe serve --port 4000

A porta também é lida da variável de ambiente PORT. Adicione --tunnel para abrir um túnel público e testar canais por webhook sem seu próprio proxy reverso. Defina PEPE_PUBLIC_URL para que as URLs de retorno que você registra com cada provedor apontem para seu host real.