Conector gb-agent

O conector gb-agent é uma integração do Switchbord que permite que um serviço externo de agente de clientes (GBCA) proponha respostas para conversas de entrada. O conector envia uma resposta estruturada ao Switchbord, o worker a persiste na linha de rascunho da mensagem, e a inbox a renderiza como um card que o operador pode aceitar, editar, descartar ou revisar — dependendo do veredito do agente. Esta página é voltada ao operador. Ela explica o que o conector faz, como a inbox o apresenta e — mais importante — o que o conector não pode fazer.

​

Duas variantes de card

Toda resposta do conector carrega um campo route. A inbox renderiza uma de duas variantes de card com base nessa rota.

​

draft_reply — mensagem proposta

O agente está confiante o suficiente para sugerir uma resposta pronta para envio. O operador vê o card de rascunho de IA já existente:

• Cabeçalho: ✨ AI draft · proposed horário
• Badges de metadados: route, intent, confidence, e opcionalmente destination/dateWindow/partySize
• Corpo: o texto da mensagem proposta
• Ações: Accept & send, Edit, Reject

Este card permanece inalterado em relação a versões anteriores do Switchbord.

​

human_review — prévia de handoff

O agente não tem confiança suficiente (ou a política não permite envio automático) e está devolvendo a conversa para um humano. O operador vê o novo card âmbar de prévia de handoff:

• Cabeçalho: 🧭 Agent handoff preview · proposed horário
• Badges: route (Human review), connector (gb-customer-agent), e opcionalmente o tipo de handoff
• Seções (cada uma exibida apenas quando preenchida):
  • Handoff packet — tipo, fila recomendada, tarefas abertas, verificação necessária, limite de dry-run
  • Proposed review actions — chips somente para revisão (sem handlers de clique, sem efeitos colaterais); cada um rotulado como “Review-only”
  • Evidence references — até 5 visíveis, links somente https, IDs em estilo mono para evidências sem link
• Ações: apenas Dismiss (sem Accept/Send, sem botão de criação de tarefa de operador, sem botão de atribuição de fila)

O card é somente leitura por design. Tudo que o operador faz a seguir acontece pelos controles padrão da inbox do Switchbord — atribuir fila, alterar status, enviar uma resposta manual, escalar. O conector nunca executa nenhuma dessas ações em nome do operador.

​

Feature flag

O card de prévia de handoff é controlado pela feature flag inbox.gbAgentHandoffPreview.

• Padrão: DESLIGADA (OFF) em todos os workspaces.
• Ativar por deployment: defina a variável de ambiente NEXT_PUBLIC_FLAG_INBOX_GB_AGENT_HANDOFF_PREVIEW=1 no projeto apps/app da Vercel. A flag entra em vigor no próximo deploy.
• Quando DESLIGADA: rascunhos com route === "human_review" continuam a renderizar o badge fino “Human review” dentro do card de rascunho existente. Nada mais muda.
• Quando LIGADA: a Variante B é renderizada para esses rascunhos.

Veja Operations → Feature Flags para o catálogo mais amplo de flags.

​

O limite de dry-run

Por padrão, o conector gb-agent é restrito a propor — não a agir. Isso é reforçado em três camadas (UI, worker e schema de resposta) e é o contrato para Draft with me manual, rascunhos connector iniciados manualmente, handoffs human_review e modo proativo quando proactive_draft_auto_send_first=false: A única exceção intencional é o opt-in explícito documentado abaixo: proactive_draft_auto_send_first=true pode aceitar e despachar o primeiro rascunho proativo draft_reply bem-sucedido de trigger Flow/keyword pelo mesmo RPC accept_message_draft_for_dispatch usado pelo operador. Fora desse caminho restrito, os efeitos continuam sendo ações manuais do operador dentro do Switchbord. Se você vir qualquer outra ação autônoma da inbox como resultado de uma resposta do conector, isso é um bug — por favor, registre-o.

​

”Draft with me” (assistência por streaming, por conversa)

Separadamente das duas variantes de card acima, o composer tem um gatilho “Draft with me” — um único pill violeta (SparklesIcon) na borda direita do composer, controlado pelo mesmo modo de acesso draft_with_me do restante da superfície do conector (/api/inbox/gb-agent/access). Clicar nele transmite via streaming um rascunho com contexto completo para a conversa aberta e o mantém em espera em uma barra de status minimizada acima do composer; nada é enviado automaticamente em nenhum momento.

​

Execuções em segundo plano, por conversa

Desde a v0.18.30, uma execução do Draft with me é vinculada à sua conversa, e não ao componente montado do composer. O estado da execução (status, fase, trace, texto final do rascunho, motivo do handoff) vive em um store em nível de módulo (gb-agent-draft-runs-store) indexado pelo id da conversa. Na prática, isso significa que:

• Trocar para outro chat enquanto um rascunho está sendo gerado não cancela a execução — ela continua transmitindo em segundo plano e ainda estará lá (concluída, encaminhada ou com falha) quando o operador voltar.
• Toda linha de conversa, o cabeçalho do chat aberto e a faixa de abas (veja Funcionalidades Avançadas da Inbox) exibem um badge de status BotMessageSquare em tempo real, tingido conforme a execução daquela conversa específica — violeta/pulsando durante o streaming, verde quando um rascunho está pronto, âmbar em um handoff de revisão humana, vermelho em caso de falha, e oculto quando ocioso.
• Somente o controle explícito ✕ / Stop cancela uma execução. Desmontar o composer (ao navegar para outro lugar) não interrompe mais a execução.
• Iniciar uma nova execução para a mesma conversa substitui o que estava sendo executado antes.

​

Barra de status minimizada

O painel (v0.18.17) nunca cobre o chat — ele é renderizado como uma barra fina com um ponto de status colorido e uma revelação de clique para expandir: Expandir a barra revela o texto da resposta em streaming, um trace colapsável de raciocínio/uso de ferramentas e (enquanto ativo) um controle Stop, além do ✕ sempre visível que descarta a barra por completo (cancelando uma execução ainda em streaming). panelDismissed e panelExpanded são redefinidos a cada troca de conversa e a cada nova execução, então uma barra obsoleta nunca vaza entre chats. Se uma nova mensagem de entrada chegar durante a execução, um banner âmbar descartável de “contexto obsoleto” avisa o operador que o rascunho em andamento pode estar respondendo a uma mensagem desatualizada — a execução não é cancelada automaticamente.

​

Cadeia de fallback

Desde a v0.18.20, uma execução do Draft with me é uma cadeia de tentativas, não uma única requisição: streaming → nova tentativa de streaming com backoff com jitter → fallback determinístico sem streaming draft-run. O operador sempre termina com um rascunho utilizável em espera ou com uma falha explícita e amigável — nunca com um composer silenciosamente vazio. Enquanto a cadeia está processando novas tentativas ou o fallback determinístico, a barra expandida mostra uma dica de “tentando novamente…” / “recorrendo a alternativa…”, para que a espera seja explicada em vez de silenciosa.

​

Trilha de depuração Copy chat → draft

O botão Copy chat do painel de chat (canto superior direito, ícone de clipboard) grava uma exportação JSON estruturada na área de transferência contendo o contexto completo da conversa (v0.18.13). Desde a v0.18.33, se uma execução do Draft with me já tiver ocorrido para aquela conversa, a exportação também traz um bloco draftWithMe — omitido completamente quando nenhuma execução ocorreu (status é idle), de forma que conversas para as quais nunca foi gerado rascunho permaneçam limpas:

• finalDraftText e o ciclo de vida (status / phase, se o fallback determinístico foi usado)
• handoffReason quando a execução foi roteada para revisão humana
• traceEvents (labels, tipo de decisão/evento, status ok/warn) — o mesmo trace de raciocínio exibido na barra expandida
• sessionId e inboundMessageId para correlação com logs do lado do servidor
• lastError (mensagem, flag recoverable e — desde a v0.18.34 — um detail upstream sem conteúdo sensível, como AI_APICallError status=429 cause=RateLimitError, limitado a 200 caracteres) quando o estado final da execução foi uma falha

Isso permite que um operador capture um rascunho, além de tudo o que é necessário para investigar um problema, sem abrir as devtools.

​

Rascunhos proativos de Flow de campanha e auto-send-first

Independentemente do gatilho manual “Draft with me”, um workspace pode optar pela geração proativa de rascunhos (v0.18.12, BORD-818): o GB-Agent gera um rascunho em background e o coloca no composer antes de o operador abrir a conversa. Para os Flows de campanha GB, o formato real em produção é:

• Webhook Meta: type: "interactive", interactive.type: "nfm_reply", interactive.nfm_reply.name: "flow".
• Placeholder visível no corpo da mensagem: "Sent".
• Mensagem normalizada no Switchbord: body = "Sent", payload.messageType = "interactive", payload.replyKind = "interactive_flow", e payload.flowResponseRedacted presente.
• Conversas originadas de campanha geralmente têm label campaign/Campaign, mas o gatilho Flow deve usar payload.replyKind = "interactive_flow"; a keyword sent é apenas fallback para payloads degradados.

Conjuntos de toggles recomendados: Notas operacionais:

• proactive_draft_delay_seconds (0–300, padrão 10) espera depois da mensagem inbound antes de gerar. Um novo inbound cancela um job proativo ainda pending e reinicia o delay na mensagem mais recente.
• proactive_draft_label_filters é case-insensitive; campaign corresponde a labels como Campaign. Deixe vazio para permitir qualquer Flow completion.
• proactive_draft_auto_send_first é restrito: só o primeiro rascunho proativo draft_reply de trigger flow_completion/keyword em uma conversa pode ser aceito automaticamente. Jobs legados all_inbound, rascunhos human_review, conversas com draft já aceito, outbound humano, ou bloqueios do RPC degradam para draft-only.
• O auto-send ainda usa o mesmo RPC accept_message_draft_for_dispatch do botão Send do operador, preservando idempotência, auditoria, gates de consentimento/janela de serviço e outbox message.dispatch.

​

GB-Agent Insights

/insights tem uma aba GB-Agent (v0.18.16, BORD-741) — analytics de rollout e refinamento, somente leitura e por workspace, sobre responder_runs (a mesma tabela de telemetria em que o Draft with me e os rascunhos proativos escrevem). Não há gate de controle de custo aqui; a aba existe puramente para tornar visível o uso do GB-Agent. A aba apresenta:

• Tiles de resumo — requisições, conclusões, timeouts, falhas, além das taxas de conclusão/timeout/falha.
• Detalhamento de resultados — sent_unmodified, sent_modified, rejected, abandoned, timeout, failed, com a taxa de modificação derivada (sent_modified / (sent_unmodified + sent_modified)) e a taxa de rejeição.
• Distribuição de edit-distance — um histograma em faixas (0–10%, 10–25%, 25–50%, 50–75%, 75%+) de quanto do texto de um rascunho sent_modified o operador alterou antes de enviar, além da proporção média.
• Percentis de tempo até o envio — p50 / p90 / p99 / latência média de decisão do operador (time_to_action_ms).
• Agregações por modo e por operador/agente — o mesmo detalhamento agregado, agrupado por responder_type (Response AI vs. campanha) ou por agent_id.

A aba lê GET /api/insights/gb-agent, que aceita sinceDays (padrão 30, limitado entre 1–365) ou from/to explícitos, e compartilha os seletores SSR de canal/intervalo de datas com o restante de /insights. O acesso é controlado da mesma forma que o restante de /insights (requireOperationsAccess).

​

Configurando o conector

A configuração do operador é feita em Settings → Integrations → gb-agent. (Quando essa superfície for lançada por completo, a ajuda integrada ao produto cobrirá as etapas em detalhe; esta página é a fonte de verdade atual.) Configuração obrigatória:

1. Endpoint URL — o endpoint completo de draft-run para o qual o Switchbord envia o contexto da mensagem de entrada para avaliação. Para a produção do GBCA, use https://gb-customer-agent-production.up.railway.app/api/agent/draft-run, e não apenas a raiz do serviço. Deve ser https, sem userinfo, query string ou fragment.
2. Tool-surface token — armazenado como segredo do workspace no Supabase Vault, nunca retornado em nenhuma resposta de API. Rotacione pela UI do Vault.
3. Test connection — a página de Settings realiza um GET autenticado e seguro para o endpoint configurado e espera que o conector reporte uma capacidade draft_run antes de exibir sucesso.

​

Estados de triagem

Quando o gatilho da inbox está desativado, o badge informa o motivo:

​

Veja também

• Operations → Runbook — bloco de triagem do gb-agent
• Operations → Feature Flags — catálogo de flags
• Security → Vault Architecture — segredos de workspace
• Platform → Data Model — formato de message_drafts e responder_runs
• Features → Advanced Inbox Features — banner de conexão e abas de conversa que exibem o status do Draft with me