---
id: agencias/contexto-por-cliente-ia
industry: Marketing agencies
usage: widely used
effort: medium
grain: One set of documents per client (scope, funnel, spend, tables and pitfalls) plus the global ones
---

# Per-client context for the AI agent

The agent answers about each client using that client's rules and tables, and says it does not know instead of making things up.

## Executive summary

**For:** Agencies that use an AI agent to answer questions about many clients.

**What it solves**

- The agent never mixes one client's data or rules with another's.
- Each client is measured by the definition agreed with the agency.
- When data is missing, the agent says so instead of estimating.

**Why it matters:** Another client's number in a report is the kind of mistake that loses the account. With the right context, the agent becomes the brain of client service: it answers the account manager, builds reports and explains each client's rules without depending on whoever set up the project.

**Business questions it answers**

- How did client X do in paid media this month?
- How many leads did client X get in August and what was the CPL by their rule?
- What was client Y's cost per SQL last quarter?
- Which of client Z's rules have not yet been validated with them?
- Build client X's monthly presentation for the closed month.

**What you need**

- Each client's sources connected and organized by layer
- Each client's definitions: lead, sale, main event, taxes and scope

**What you get**

- A routing document per client and platform
- A global contract with rule precedence
- An agent that answers by each client's rules
- The list of what still needs validating with each client

## Detailed

### The problem

Each agency client has its own funnel, conversion event, taxes, CRM and vocabulary. Without separate context, the AI agent uses another client's table because the name looks similar, applies the global rule on top of an agreed exception, or estimates a number that does not exist. The answer looks right and reaches the client wrong.

### Business rules

1. **Resolve the client before querying.** The order is: 1) client named in the current request; 2) conversation context, only when there is exactly one active client and no ambiguity; 3) otherwise, the client stays unresolved and the agent asks. A question covers one client only. Queries that combine clients only when explicitly requested. (Avoid: Infer the client from the table that looks most like the question.)
2. **Routing per client, interpretation in the global docs.** Each client has a routing document per platform that states its source, layer and physical tables. That document only resolves where the data lives: it does not redefine KPI, result, grain or deduplication. The global documents say how to interpret the data and hold no client physical names. (Avoid: One central map with every client, table and rule mixed together.)
3. **Written precedence.** When two rules conflict, this order applies: 1) explicit user request; 2) validated client rule; 3) global agency rule; 4) generic platform interpretation. A global rule never silently overrides a validated client exception. (Avoid: Apply the global result rule to a client that agreed on a different event.)
4. **Another client's resource is not evidence.** Another client's table is not proof, even with the same name, structure, metrics and connector, or when its document shows up by similarity. Do not reuse a validated join, observed grain or available history from another client. (Avoid: Copy the join that worked for the neighboring client.)
5. **Every term is defined within the client's scope.** A lead can be a digital deal created in the CRM, a contact with a valid conversion in marketing automation, or a conversion reported by the platform when there is no CRM. The same word (lead, MQL, sale) changes from client to client. Use the vocabulary of the report the client already receives and write the definition in their document. (Avoid: One lead definition for the whole portfolio.)
6. **Every document has a status, owner and date.** Fixed header: STATUS (validated, partially validated, surveyed in the data and not validated), scope, owner and date of last review. When answering with an unvalidated rule, the agent warns that the rule is the agency's and is pending validation with the client. (Avoid: A rule surveyed by the agency presented as agreed with the client.)
7. **What is out of scope is written down.** Declare what is not part of the analysis: a reactivation funnel built from imports, revenue from the old customer base when the agency only handles the new slice, the client's own campaigns in the shared account. Never divide the client's total revenue by the agency's budget. (Avoid: ROI calculated with the company's entire revenue.)
8. **No data means the answer is that there is no data.** A client with no CRM connected has no sales, MQLs or close rate in the data: the right move is to say so, not to approximate. No number is estimated, rounded for convenience or inferred. If a report is missing information, the agent asks before filling it in. (Avoid: Estimate sales from platform conversions.)
9. **An old count loses to the query.** Rules are stable; counts (active clients, layers, connectors) are a snapshot of a date and go stale within days. If a number in the document diverges from the query, the query is the truth. Before flagging a divergence, check the date of the source's last run. (Avoid: Answer about the portfolio with the number written in the document.)
10. **Write for reading in chunks.** The agent may retrieve only an excerpt. Each block must stand on its own: a descriptive title with the client's name, one concept per block, terms defined before they are used, and explicit references to table and field. (Avoid: A long document that depends on the previous paragraph.)

### Who wins when two rules conflict

From strongest to weakest. With no resolved client, none apply.

- **1st** → Explicit user request (`in this conversation`)
- **2nd** → Validated client rule (`STATUS: VALIDATED`)
- **3rd** → Global agency rule (`global semantic contract`)
- **4th** → Generic platform interpretation (`connector default`)
- **No client** → Ask before answering (`client_scope unresolved`)

### Definitions

| Metric | Definition |
|---|---|
| Client scope | exactly one client per question; combine clients only on explicit request |
| Routing document | one per client and platform; lists source, layer and physical tables; does not define metrics |
| Global document | interpretation rule valid for the whole portfolio until replaced by a validated exception |
| Validated exception | client rule confirmed with the client, with an owner and review date; beats the global rule |
| Unvalidated rule | surveyed in the data by the agency; can be used, always with the pending warning |
| Lead (per client) | the definition declared in the client's document; the agency has no universal definition |
| Out of scope | data present in the warehouse that is not part of the client's analysis, listed in the overview document |

### Pitfalls

- **The neighbor's table.** Clients with tables sharing the same connector prefix and similar names led the agent to answer with another client's data. How to avoid: Routing per client and a written ban on using another client's resources.
- **Global rule on top of the exception.** A client that agreed on a custom event as the result got a CPL calculated from the global rule's standard lead. How to avoid: Precedence in the global document and the exception marked as validated.
- **Made-up ROI.** Almost all of the client's revenue was repeat purchases from the existing base; dividing it by the media budget produced an absurd return. Revenue coming from marketing was a tiny fraction. How to avoid: Written scope: only revenue from people who were marketing leads counts.
- **Estimated sales without a CRM.** For a media-only client, the agent approximated sales from platform conversions. How to avoid: An overview document stating that the question has no answer in the data.
- **Context generated by automation without curation.** Documents written by an agent showed up duplicated, with test probes and a "generic market overview" in the middle of the client's context; the generic benchmark became the answer. How to avoid: Automation only updates marked blocks; generic content stays out of the client document.
- **Inventory that goes stale.** Layers and connectors changed within a few days and the warehouse copy of the portfolio lagged by up to 24 hours; the document and the query diverged. How to avoid: A date on every count and the query as the truth.

### Acceptance test

- [ ] Asking for the same metric for two clients with similarly named tables, each answer uses only that client's own source and layer.
- [ ] A question with no client, in a conversation without a single client, gets a question back and no number.
- [ ] For a client with a validated result exception, the agent's cost per result matches the client's official report (difference below 1%).
- [ ] For a client with no CRM, "how many sales did we have this month" is answered as nonexistent data, with no estimate.
- [ ] Every client document has STATUS, owner and review date in the header.

### Context document

```text
Per-client context contract
- Every question covers exactly one client. Resolve in this order: client named in the request; conversation context only if there is a single active client; otherwise, ask which client it is.
- Never pick a client by similar name, same platform or similar tables.
- The physical location (source, layer, tables) comes from the "<client> Routing" document for each platform. The global documents say how to interpret, not where the data is.
- Another client's resource is not evidence, even with the same table, metric and connector.
- Precedence: 1) explicit user request; 2) validated client rule; 3) global agency rule; 4) generic platform interpretation. A global rule never overrides a validated exception.
- Lead, MQL, SQL and sale are defined in each client's document. Use that client's definition.
- If the rule used has status "not validated", say the rule is the agency's and is pending with the client.
- With no connected data (e.g. a client with no CRM), say the question has no answer in the data. Never estimate.
- Counts written in the documents are a snapshot of a date; if they diverge from the query, the query wins.
- Combine clients in one answer only when the user explicitly asks.
Per-client exceptions:
- <client>: lead = <definition>; status: <validated | not validated> on <date>.
- <client>: out of scope: <funnel, revenue or campaigns that are excluded>.
- <client>: no CRM connected; sales and MQL questions have no answer in the data.
```

### Variations

- **Physical isolation:** One table or layer per client for agents exposed to the end client; in the notebook, literal table names per client.
- **Shared source:** Multi-client sources (Google Business Profile, Business Manager) filtered by the client identifier declared in the document.
- **Agency as a client:** The agency itself, analyzed as a client, sits in a scope separate from the global rules it maintains.