> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conector gb-agent

> Como o conector de agente de clientes gb-agent apresenta rascunhos e handoffs de revisão humana na inbox do Switchbord, e o limite de dry-run que mantém isso seguro.

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](/pt-BR/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`:

| O conector **por padrão não pode**                 | O que acontece em vez disso                                                                     |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Enviar uma mensagem visível ao cliente             | O operador deve clicar em Accept & send (draft\_reply) ou compor manualmente (human\_review)    |
| Escrever no CRM / registros de contato             | A resposta do conector é metadado somente leitura; não existem caminhos de escrita              |
| Atribuir uma conversa a uma fila                   | O operador atribui manualmente pela UI de fila existente                                        |
| Marcar uma conversa como lida/não lida             | O operador altera o status pelos controles de inbox existentes                                  |
| Criar tarefas de operador                          | Nenhuma superfície de criação de tarefas é exposta; trabalho futuro é acompanhado separadamente |
| Abrir URLs externas automaticamente                | URLs de evidência são somente https, sem `target="_blank"` em fontes que não sejam https        |
| Expor seu endpoint, runId ou token de tool-surface | O mapper de UI remove todos os campos sensíveis a segredos antes de renderizar                  |

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.

<Info>
  A partir da v0.18.29, o Draft with me é o **único** gatilho de IA no composer — a antiga ação inline `BotMessageSquare` e sua duplicata compacta foram descontinuadas para que os operadores tenham um único ponto de entrada, sem ambiguidade.
</Info>

### 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](/pt-BR/features/inbox-advanced#abas-de-conversa-persistentes)) 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:

| Cor do ponto      | Significado                                                     |
| ----------------- | --------------------------------------------------------------- |
| Violeta, pulsando | Rascunho em elaboração                                          |
| Verde             | Rascunho pronto — clique para expandir e **Drop into composer** |
| Âmbar             | Encaminhado para revisão humana (sem rascunho utilizável)       |
| Vermelho          | Falha na geração                                                |

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:

| Resultado                                                | Settings → Integrations → GB-Agent                                                                                                                                                                                                                                                          |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Silêncio em submits de Flow                              | `proactive_draft_enabled = false` (master off). GB-Agent não faz nada quando `Sent` chega.                                                                                                                                                                                                  |
| Rascunho no composer, sem envio automático               | `enabled = true`, `mode_draft_reply_enabled = true`, `proactive_draft_enabled = true`, `proactive_draft_trigger_mode = flow_completion`, `proactive_draft_trigger_keywords = ['sent']`, opcional `proactive_draft_label_filters = ['campaign']`, `proactive_draft_auto_send_first = false`. |
| Enviar automaticamente a primeira resposta Flow completa | Mesmo que draft mode, mais `proactive_draft_auto_send_first = true` e o kill switch do worker não pode ser `GB_AGENT_PROACTIVE_AUTO_SEND_ENABLED=false`.                                                                                                                                    |

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`.

<Warning>
  Mantenha `proactive_draft_auto_send_first` desligado para o modo de revisão com rascunho no composer. Ative apenas quando o workspace quiser enviar automaticamente o primeiro rascunho Flow bem-sucedido; respostas seguintes continuam draft-only.
</Warning>

## 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:

| Estado                    | Significado                                                     | O que fazer                                                    |
| ------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------- |
| "Endpoint not configured" | Nenhuma URL ou token armazenado                                 | Configure em Settings → Integrations                           |
| "Endpoint unsafe"         | A URL configurada não é https ou contém userinfo/query/fragment | Substitua por uma URL https limpa                              |
| "Draft already queued"    | Já existe um rascunho pendente do conector                      | Resolva o rascunho existente primeiro (Accept, Edit ou Reject) |
| "No inbound message"      | Nenhuma mensagem de entrada disponível para avaliação           | Aguarde a próxima mensagem do cliente                          |

## Veja também

* [Operations → Runbook](/pt-BR/operations/runbook) — bloco de triagem do gb-agent
* [Operations → Feature Flags](/pt-BR/operations/feature-flags) — catálogo de flags
* [Security → Vault Architecture](/pt-BR/security/vault-architecture) — segredos de workspace
* [Platform → Data Model](/pt-BR/platform/data-model) — formato de `message_drafts` e `responder_runs`
* [Features → Advanced Inbox Features](/pt-BR/features/inbox-advanced) — banner de conexão e abas de conversa que exibem o status do Draft with me