---
id: agencias/contexto-por-cliente-ia
industria: Agências de marketing
uso: muito usado
esforco: médio
grao: Um conjunto de documentos por cliente (escopo, funil, investimento, tabelas e armadilhas) mais os globais
---

# Contexto por cliente para o agente de IA

O agente responde sobre cada cliente com as regras e as tabelas daquele cliente, e diz que não sabe em vez de inventar.

## Resumo executivo

**Para quem:** Agências que usam um agente de IA para responder sobre vários clientes.

**O que resolve**

- O agente nunca mistura dados ou regras de um cliente com outro.
- Cada cliente é medido pela definição que combinou com a agência.
- Quando falta dado, o agente diz isso em vez de estimar.

**Por que importa:** Um número de outro cliente num relatório é o tipo de erro que custa a conta. Com o contexto certo, o agente vira o cérebro do atendimento: responde o gerente de conta, monta relatórios e explica a régua de cada cliente sem depender de quem montou o projeto.

**Perguntas de negócio que responde**

- Como foi o mês do cliente X em mídia paga?
- Quantos leads o cliente X teve em agosto e qual o CPL pela régua dele?
- Qual o custo por SQL do cliente Y no último trimestre?
- Quais regras do cliente Z ainda não foram validadas com ele?
- Monte a apresentação mensal do cliente X com o mês fechado.

**O que você precisa**

- Fontes de cada cliente conectadas e organizadas por layer
- As definições de cada cliente: lead, venda, evento principal, imposto e escopo

**O que você recebe**

- Um documento de roteamento por cliente e plataforma
- Um contrato global com a precedência das regras
- Um agente que responde na régua de cada cliente
- A lista do que falta validar com cada cliente

## Detalhado

### O problema

Cada cliente da agência tem funil, evento de conversão, imposto, CRM e vocabulário próprios. Sem contexto separado, o agente de IA usa a tabela de outro cliente porque o nome é parecido, aplica a régua global por cima de uma exceção combinada ou estima um número que não existe. A resposta parece certa e chega errada ao cliente.

### Regras de negócio

1. **Resolva o cliente antes de consultar.** A ordem é: 1) cliente citado no pedido atual; 2) contexto da conversa, só quando existir exatamente um cliente ativo e sem ambiguidade; 3) caso contrário, o cliente fica não resolvido e o agente pergunta. Uma pergunta trata de um cliente só. Consultas que combinam clientes só quando pedidas de forma explícita. (Evite: Deduzir o cliente pela tabela mais parecida com a pergunta.)
2. **Roteamento por cliente, interpretação no global.** Cada cliente tem um documento de roteamento por plataforma que diz a source, a layer e as tabelas físicas dele. Esse documento só resolve onde está o dado: não redefine KPI, resultado, grão ou deduplicação. Os documentos globais dizem como interpretar o dado e não guardam nomes físicos de cliente. (Evite: Um mapa central com todos os clientes, tabelas e regras misturados.)
3. **Precedência escrita.** Quando duas regras conflitam, vale nesta ordem: 1) pedido explícito do usuário; 2) regra validada do cliente; 3) regra global da agência; 4) interpretação genérica da plataforma. Uma regra global nunca sobrescreve em silêncio uma exceção validada de um cliente. (Evite: Aplicar a régua global de resultado num cliente que combinou outro evento.)
4. **Recurso de outro cliente não é evidência.** Tabela de outro cliente não serve de prova, mesmo com nome, estrutura, métricas e conector iguais, ou quando o documento dele aparece por semelhança. Não reaproveite join validado, grão observado nem histórico disponível de outro cliente. (Evite: Copiar o join que funcionou no cliente vizinho.)
5. **Cada termo é definido no escopo do cliente.** Lead pode ser negócio digital criado no CRM, contato com conversão válida na automação de marketing ou conversão reportada pela plataforma, quando não há CRM. A mesma palavra (lead, MQL, venda) muda de cliente para cliente. Use o vocabulário do relatório que o cliente já recebe e escreva a definição no documento dele. (Evite: Uma definição de lead para a carteira inteira.)
6. **Todo documento tem status, dono e data.** Cabeçalho fixo: STATUS (validado, parcialmente validado, levantado nos dados e não validado), escopo, dono e data da última revisão. Ao responder com regra não validada, o agente avisa que a régua é da agência e está pendente de validação com o cliente. (Evite: Regra levantada pela agência apresentada como acordo com o cliente.)
7. **O que fica fora está escrito.** Declare o que não entra na análise: funil de reativação montado por importação, receita da carteira antiga quando a agência só cuida da fatia nova, campanhas do próprio cliente na conta compartilhada. Nunca divida o faturamento total do cliente pela verba da agência. (Evite: ROI calculado com o faturamento inteiro da empresa.)
8. **Sem dado, a resposta é que não há dado.** Cliente sem CRM conectado não tem venda, MQL nem taxa de fechamento nos dados: o certo é dizer isso, não aproximar. Nenhum número é estimado, arredondado por conveniência ou inferido. Se falta informação para um relatório, o agente pergunta antes de preencher. (Evite: Estimar vendas a partir das conversões da plataforma.)
9. **Contagem velha perde para a consulta.** Regras são estáveis; contagens (clientes ativos, layers, conectores) são retrato de uma data e envelhecem em dias. Se um número do documento divergir da consulta, a consulta é a verdade. Antes de acusar divergência, confira a data da última execução da fonte. (Evite: Responder a carteira com o número escrito no documento.)
10. **Escreva para leitura em pedaços.** O agente pode recuperar só um trecho. Cada bloco precisa se sustentar sozinho: título descritivo com o nome do cliente, um conceito por bloco, termo definido antes de ser usado e referência explícita a tabela e campo. (Evite: Documento longo que depende do parágrafo anterior.)

### Quem vence quando duas regras conflitam

Da mais forte para a mais fraca. Sem cliente resolvido, nenhuma vale.

- **1º** → Pedido explícito do usuário (`nesta conversa`)
- **2º** → Regra validada do cliente (`STATUS: VALIDADO`)
- **3º** → Regra global da agência (`contrato semântico global`)
- **4º** → Interpretação genérica da plataforma (`padrão do conector`)
- **Sem cliente** → Perguntar antes de responder (`client_scope não resolvido`)

### Definições

| Métrica | Definição |
|---|---|
| Escopo do cliente | exatamente um cliente por pergunta; combinar clientes só a pedido explícito |
| Documento de roteamento | um por cliente e plataforma; lista source, layer e tabelas físicas; não define métrica |
| Documento global | regra de interpretação válida para toda a carteira até ser substituída por exceção validada |
| Exceção validada | regra do cliente confirmada com ele, com dono e data de revisão; vence a regra global |
| Regra não validada | levantada nos dados pela agência; pode ser usada, sempre com o aviso de pendência |
| Lead (por cliente) | a definição declarada no documento do cliente; a agência não tem definição universal |
| Fora de escopo | dado presente no warehouse que não entra na análise do cliente, listado no documento de visão geral |

### Armadilhas

- **A tabela do vizinho.** Clientes com tabelas de mesmo prefixo de conector e nomes parecidos levaram o agente a responder com dados de outro cliente. Como evitar: Roteamento por cliente e proibição escrita de usar recurso de outro cliente.
- **Régua global por cima da exceção.** Um cliente que combinou evento personalizado como resultado recebeu CPL calculado pelo lead padrão da regra global. Como evitar: Precedência no documento global e exceção com status validado.
- **ROI inventado.** Quase todo o faturamento do cliente era recompra da carteira; dividir pela verba de mídia gerava retorno absurdo. A receita vinda de marketing era fração mínima. Como evitar: Escopo escrito: só conta receita de quem foi lead de marketing.
- **Venda estimada sem CRM.** Em cliente só com mídia, o agente aproximou vendas a partir das conversões da plataforma. Como evitar: Documento de visão geral dizendo que a pergunta não tem resposta nos dados.
- **Contexto gerado por automação sem curadoria.** Documentos escritos por agente apareceram duplicados, com sondas de teste e um "panorama genérico do mercado" no meio do contexto do cliente; o benchmark genérico virou resposta. Como evitar: Automação só atualiza blocos marcados; o genérico fica fora do documento do cliente.
- **Inventário que envelhece.** Layers e conectores mudaram em poucos dias e a cópia da carteira no warehouse tinha até 24 horas de atraso; o documento e a consulta divergiam. Como evitar: Data em toda contagem e a consulta como verdade.

### Teste de aceitação

- [ ] Perguntando a mesma métrica para dois clientes com tabelas de nome parecido, cada resposta usa só a source e a layer do próprio cliente.
- [ ] Uma pergunta sem cliente, numa conversa sem cliente único, recebe uma pergunta de volta e nenhum número.
- [ ] Para um cliente com exceção validada de resultado, o custo por resultado do agente bate com o relatório oficial do cliente (diferença abaixo de 1%).
- [ ] Para um cliente sem CRM, "quantas vendas tivemos no mês" é respondida como dado inexistente, sem estimativa.
- [ ] Todo documento de cliente tem STATUS, dono e data de revisão no cabeçalho.

### Context document

```text
Contrato de contexto por cliente
- Toda pergunta trata de exatamente um cliente. Resolva nesta ordem: cliente citado no pedido; contexto da conversa só se houver um único cliente ativo; senão, pergunte qual é o cliente.
- Nunca escolha cliente por semelhança de nome, mesma plataforma ou tabelas parecidas.
- A localização física (source, layer, tabelas) vem do documento "<cliente> Roteamento" de cada plataforma. Os documentos globais dizem como interpretar, não onde está o dado.
- Recurso de outro cliente não é evidência, mesmo com tabela, métrica e conector iguais.
- Precedência: 1) pedido explícito do usuário; 2) regra validada do cliente; 3) regra global da agência; 4) interpretação genérica da plataforma. Regra global nunca sobrescreve exceção validada.
- Lead, MQL, SQL e venda são definidos no documento de cada cliente. Use a definição dele.
- Se a regra usada tiver status "não validado", diga que a régua é da agência e está pendente com o cliente.
- Sem dado conectado (ex.: cliente sem CRM), diga que a pergunta não tem resposta nos dados. Nunca estime.
- Contagens escritas nos documentos são retrato de uma data; se divergirem da consulta, vale a consulta.
- Combinar clientes numa resposta só quando o usuário pedir explicitamente.
Exceções por cliente:
- <cliente>: lead = <definição>; status: <validado | não validado> em <data>.
- <cliente>: fora de escopo: <funil, receita ou campanhas que não entram>.
- <cliente>: sem CRM conectado; perguntas de venda e MQL não têm resposta nos dados.
```

### Variações

- **Isolamento físico:** Uma tabela ou layer por cliente para agentes expostos ao cliente final; no notebook, nomes de tabela literais por cliente.
- **Fonte compartilhada:** Fontes multi-cliente (Google Meu Negócio, Business Manager) filtradas pelo identificador do cliente declarado no documento.
- **Agência como cliente:** A própria agência analisada como cliente fica num escopo separado das regras globais que ela mantém.