Guia de Configuração de Adaptadores Multicanal do OpenFang: Leve seu Agente a qualquer lugar

Slug: openfang-channel-setup-guide Categoria: usage-guides (Guias de Uso) Palavras-chave: Configuração de canal OpenFang, Adaptador OpenFang, OpenFang WhatsApp Telegram Intenção de busca: Informativa (usuários que desejam conectar o Agente a diferentes plataformas) Contagem de palavras: ~1800 palavras Idioma: pt

O que é um adaptador de canal?

Um adaptador de canal (Channel Adapter) é a ponte entre o OpenFang e plataformas externas. Cada adaptador é responsável por converter mensagens de plataformas externas para um formato unificado que o OpenFang compreende, e por converter as respostas do Agente de volta para o formato nativo da plataforma.

A filosofia de design do OpenFang é "escreva a lógica do Agente uma vez e execute em mais de 40 plataformas". Você não precisa reescrever o Agente para cada plataforma — basta configurar o adaptador de canal correspondente.

Atualmente, o OpenFang suporta mais de 40 adaptadores de canal, cobrindo categorias como mensagens instantâneas, redes sociais, ferramentas de colaboração, e-mail e APIs personalizadas.

Conceitos fundamentais dos adaptadores de canal

Todos os adaptadores de canal compartilham os seguintes princípios de design:

• Formato de mensagem unificado: Independentemente da origem, as mensagens são convertidas para o formato padrão de Mensagem do OpenFang.
• Sandbox independente: Cada adaptador de canal é executado em um sandbox isolado; uma falha em um canal não afeta os outros.
• Hot-loading: Não é necessário reiniciar o Agente após adicionar ou modificar configurações de canal.
• Limite de taxa (Rate limiting): Proteção integrada para evitar o acionamento de limites de API das plataformas.

Configuração de adaptadores de canal comuns

Adaptador CLI

O CLI é o adaptador mais básico, ideal para desenvolvimento, depuração e uso local:

[channels.cli]enabled = truehistory_size = 1000              # Número de registros de histórico de sessãoprompt_style = "rich"            # plain / rich / minimal

O adaptador CLI funciona imediatamente, sem necessidade de configuração adicional. Suporta entrada de múltiplas linhas, preenchimento de comandos e destaque de sintaxe.

Adaptador WhatsApp

O WhatsApp é uma das ferramentas de mensagens instantâneas mais utilizadas no mundo. Através da WhatsApp Business API, seu Agente pode interagir diretamente com os usuários no WhatsApp:

[channels.whatsapp]enabled = trueapi_version = "v18.0"phone_number_id = "${WA_PHONE_NUMBER_ID}"access_token = "${WA_ACCESS_TOKEN}"verify_token = "${WA_VERIFY_TOKEN}"[channels.whatsapp.features]media_support = true             # Suporte para envio de imagens/arquivosreply_buttons = true             # Suporte para botões interativosmax_message_length = 4096typing_indicator = true          # Exibir "digitando..."

Passos de configuração:

1. Crie um aplicativo WhatsApp no Meta for Developers.
2. Obtenha o Phone Number ID e o Access Token.
3. Configure a URL do Webhook (endereço do seu servidor OpenFang + /webhook/whatsapp).
4. Insira as informações acima na configuração do OpenFang.

Adaptador Telegram

O Telegram é uma das plataformas de comunicação mais populares na comunidade técnica, com configuração simples e API amigável:

[channels.telegram]enabled = truebot_token = "${TELEGRAM_BOT_TOKEN}"allowed_users = []               # Deixe vazio para permitir todos os usuáriosadmin_users = ["@your_username"][channels.telegram.features]inline_queries = true            # Suporte para consultas inlinemarkdown_support = truefile_upload = truemax_file_size_mb = 50

Passos de configuração:

1. Converse com o @BotFather no Telegram para criar um Bot.
2. Obtenha o Bot Token.
3. Insira o Token no arquivo de configuração.

Adaptador Discord

O adaptador Discord suporta os modos de servidor (Guild) e mensagens diretas (DM):

[channels.discord]enabled = truebot_token = "${DISCORD_BOT_TOKEN}"application_id = "${DISCORD_APP_ID}"[channels.discord.guilds]server_ids = ["1234567890"]      # IDs de servidores permitidos[channels.discord.features]slash_commands = true            # Suporte para comandos de barrathread_support = true            # Suporte para threadsembed_messages = true            # Mensagens com rich text (embeds)

Adaptador Slack

Ideal para cenários de colaboração em equipe corporativa:

[channels.slack]enabled = truebot_token = "${SLACK_BOT_TOKEN}"signing_secret = "${SLACK_SIGNING_SECRET}"app_token = "${SLACK_APP_TOKEN}"[channels.slack.features]socket_mode = true               # Usar Socket Mode (recomendado, sem necessidade de URL pública)thread_replies = truereaction_feedback = true

O Slack recomenda o uso do Socket Mode, que não requer a configuração de uma URL de Webhook acessível publicamente, sendo ideal para implantações em redes internas.

Adaptador Web Chat

Incorpore uma janela de chat do OpenFang em seu site:

[channels.webchat]enabled = trueport = 3000cors_origins = ["https://your-site.com"][channels.webchat.ui]theme = "auto"                   # light / dark / autologo_url = "/assets/agent-logo.png"welcome_message = "Olá! Sou o Agente OpenFang, como posso ajudar você?"placeholder = "Digite sua pergunta..."

Após a configuração, adicione isto ao seu site:

<script src="https://your-server:3000/widget.js"></script><script>OpenFangWidget.init({ position: 'bottom-right' })</script>

Execução multicanal simultânea

A arquitetura do OpenFang suporta nativamente a execução paralela de múltiplos canais. O núcleo do Agente mantém um estado de sessão unificado, e todos os canais compartilham o contexto:

# Ativar múltiplos canais simultaneamente[channels]cli.enabled = truewhatsapp.enabled = truetelegram.enabled = truediscord.enabled = truewebchat.enabled = true[channels.routing]strategy = "context_aware"       # round_robin / context_aware / prioritypreserve_context = true          # Manter contexto entre canais para o mesmo usuário

A estratégia de roteamento context_aware significa que: se um usuário iniciar uma conversa no WhatsApp e depois mudar para o Telegram, o Agente carregará automaticamente o contexto anterior.

Configuração de segurança de canal

Múltiplos canais significam uma superfície de ataque maior. O OpenFang oferece controle de segurança de canal granular:

[channels.security]per_user_rate_limit = 30         # Máximo de 30 mensagens por usuário/minutoper_channel_rate_limit = 100     # Máximo de 100 mensagens por canal/minutorequire_auth = ["discord", "slack"]public_channels = ["webchat"]authenticated_channels = ["whatsapp", "telegram", "discord", "slack"][channels.security.content_filter]block_urls = falseblock_attachments = falsemax_prompt_length = 4000

Recomendações de segurança importantes:

• Ative limites de taxa rigorosos para canais acessíveis publicamente (Web Chat).
• Em ambientes de produção, todos os canais, exceto o CLI, devem exigir autenticação do usuário.
• Audite regularmente os logs de acesso aos canais.

Monitoramento de status de canal

# Visualizar o status de todos os canaisopenfang channels list# Exemplo de saída:# Channel        Status    Messages/24h   Errors   Latency# cli            ✅ active       0           0         -# telegram       ✅ active     156          2       120ms# whatsapp       ✅ active      89          0       250ms# discord        ⚠️ degraded    43          5       500ms# webchat        ✅ active      12          0        45ms# Reiniciar um canal específicoopenfang channels restart discord# Visualizar logs detalhados do canalopenfang channels logs telegram --level debug

Perguntas frequentes

Próximos passos

• Guia de configuração de fluxo de trabalho de automação do OpenFang: Orquestre Agentes multicanal em fluxos de trabalho automatizados.
• Melhores práticas de segurança do OpenFang: Proteja suas implantações de Agentes multicanal.