# How-to — exercise an agent before real leads reach it

> **You want.** *"cómo pruebo el agente antes de lanzarlo"* · *"probar agente link de test preview
> sandbox conversación de prueba"* · *"conversaciones sintéticas replicant simular agente antes de
> producción"* · *"entorno de prueba playground testear agente herramientas custom tools"* ·
> *"where to view synthetic conversations test runs Studio UI"*.

## The honest answer: there is no sandbox, and you are asking two questions

**Nothing here is a separate environment.** A synthetic run drives the **live, deployed** agent
config against a simulated lead. There is no staging copy of an agent, no preview build, no
playground that holds unpublished changes. If you want to test an edit, you deploy it first and
then test — which is also why testing a *change* on a client's production agent means the change is
already live while you look at it.

And "is my agent ready" is two questions that need two different tools:

| The question | What answers it | Where |
|---|---|---|
| **Is it wired up?** Will a DM even reach it — account linked, triggers registered, agent enabled | `diagnose_agent`, then the launch gate | `knowledge/runbooks/not-live-yet.md` |
| **Does it say the right things?** Tone, flow, objections, does it send the link | `generate_synthetic_conversations` | here |

Do them in that order. Synthetic conversations reach the agent through the chat path, **not**
through a real Instagram or WhatsApp webhook — so a perfect synthetic run tells you nothing about
whether the account is linked or a keyword matches. An agent can score beautifully in simulation
and receive zero real messages, and that is the single most common way this goes wrong.

---

## The sequence

### 1. Deploy the config you intend to test — with `deploy_agent_sdk`

Synthetic runs read live config, so testing before deploying measures the previous version.

`deploy_agent_sdk` is **the** deploy path: it diffs each field against live, writes only what
changed, and re-fetches to verify. Read the report it returns rather than assuming it landed — a
deploy that reports no changes is the usual reason a "fix" tests identically to the version before
it. If the report and the behaviour disagree, `knowledge/runbooks/not-live-yet.md` is the runbook
for exactly that.

### 2. Scripted mode first — fixed messages, no simulated lead

Scripted mode replays exact user turns with **no user-side inference**: only the agent thinks. Use
it when you know what a lead types and want a deterministic read on what comes back.

```
generate_synthetic_conversations
  agent_id=<uuid>, env="prod",
  scripted_scenarios=[
    { name: "precio-directo", stage: "opener → precio",
      messages: ["hola", "cuanto sale?", "y si no me funciona?"] }
  ]
```

Deterministic in, deterministic out, so it is the right tool for "did my fix land" — run it before
and after a change and the difference is the change.

### 3. Personas — an LLM plays the lead

```
generate_synthetic_conversations
  agent_id=<uuid>, env="prod", language="Spanish", max_turns=10,
  personas=[
    { role: "warm_skeptical",
      goal: "entender el precio sin comprometerse",
      description: "Mujer, 40s, ya probó otros programas. Pregunta por precio y garantía. "
                   "Muestra interés real pero escéptico. Sostener 5+ turnos." }
  ]
```

`description` is where the behaviour actually comes from — a vague one produces a lead that agrees
with everything and proves nothing. Write the objection you are worried about.

### 4. Read the conversations, do not just count them

The call returns the conversations inline, in both structured turns and markdown, so there is no
second fetch to make over MCP — `get_synthetic_conversations` **no longer exists** there. To pull a
run up again later, keep the returned `test_run_ids` and use the REST endpoint that survives:
`GET /api/v1/synthetic-conversations/:runId`.

Read them yourself. A run that "passes" while the agent monologues, invents a price or answers a
question the lead never asked is a failing run, and no aggregate score will tell you that.

---

## The invariant

**What you tested is what is deployed — and only the half that lives in the agent.**

A green synthetic run proves the prompt, examples and v5Config behave. It proves nothing about
account linkage, trigger registration, contact limits, workflows or property automation, because
none of those sit on the path a synthetic conversation takes. Before calling an agent ready, pair
this with the launch gate in `not-live-yet.md`.

---

## How it goes wrong

### The default `env` is the one that fails

`env` defaults to **`stag`**, and on the prod-connected gateway `stag` fails with an IAM error.
Pass `env="prod"` explicitly. This bites every first-time caller because the default looks like the
safe choice and is the broken one.

### It returns zero conversations and no error

`min_turns` silently discards conversations shorter than the threshold — default 1 in scripted mode,
**3 with personas**. A persona that disengages after two turns is dropped, and if every one is
dropped you get an empty list. The response sets `warning` for exactly this case; read it, then
lower `min_turns` rather than assuming the agent said nothing.

### The agent behaves differently with real leads

Expected, and usually not a bug in either place. Simulated leads are more articulate, more patient
and more on-topic than real ones. Use synthetics to catch things that are wrong in *any*
conversation — a forbidden phrase, a missing link, a broken flow step — not to predict conversion.

### It passed in simulation and got no real messages

The channel half was never tested. See the table at the top; go to `not-live-yet.md`.

### Testing a client's agent changes the client's agent

There is no isolation. Deploying to test means the client's leads meet that version in the
meantime. On a live account, prefer scripted mode on a narrow scenario, and agree a window first.

---

## See also

- `knowledge/runbooks/not-live-yet.md` — the launch gate, and "I deployed and nothing changed"
- `knowledge/mcp-tool-reference.md` §Testing & synthetic — the full argument list
- `knowledge/best-practices-top10.md` — the quality contract to read a transcript against
- `knowledge/prompt-antipatterns.md` — the behaviours worth scanning a transcript for