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

# Scan your agent

> Map your agent, approve what runs for real and what is mocked, and get a generated harness without touching your code.

The scan is where Plurai gets to know your agent and makes it ready to simulate. It:

* **Builds your agent's topology:** maps every tool, sub-agent, [knowledge base](https://docs.plurai.ai/concepts.md#param-knowledge-base) and data
  store your agent uses, and the [flows](https://docs.plurai.ai/concepts.md#param-agent-flow-graph) between them.
* **Decides what to mock:** which systems are [mocked](https://docs.plurai.ai/concepts.md#param-mocking) and which run live.
* **Wires the digital twin:** connects every mocked system to your [digital twin](https://docs.plurai.ai/concepts.md#param-digital-twin), so your
  agent's calls land there instead of in production.
* **Writes the harness:** the [harness](https://docs.plurai.ai/concepts.md#param-harness) that drives your agent in a simulation.

The scan requires no changes to your code, and it only sets up your digital twin. Scenarios and evals come
next, in [Build the suite](https://docs.plurai.ai/guides/build-the-suite.md).

[1 · Scan](https://docs.plurai.ai/guides/scan-your-agent.md)
→
[2 · Ground (optional)](https://docs.plurai.ai/guides/ground-in-production-traces.md)
→
[3 · Build the suite](https://docs.plurai.ai/guides/build-the-suite.md)
→
[4 · Run](https://docs.plurai.ai/guides/run-the-simulation.md)
→
[5 · Fix](https://docs.plurai.ai/guides/fix-and-keep-regressions.md)

**Runs** as part of `/simulate`, or on its own with `/simulation-scan-agent`.

## What you get

![Your digital twin in the report](https://mintcdn.com/plurai/V3XeGRFO5iyJejs5/images/report/scan.png?fit=max\&auto=format\&n=V3XeGRFO5iyJejs5\&q=85\&s=4a831f3b68ffe30f8525a594d0d470d7)

The Scan stage of the report: your digital twin, with every tool your agent calls and what is live or mocked.

If your agent answers from documents or a database, the Scan stage also shows **Your knowledge base**: every
document and passage the suite can test your agent on.

![Your knowledge base in the report](https://mintcdn.com/plurai/V3XeGRFO5iyJejs5/images/report/knowledge-base.png?fit=max\&auto=format\&n=V3XeGRFO5iyJejs5\&q=85\&s=01e17c1edc1d2acc051c44962a92c3d7)

Your knowledge base in the report: each document, broken into the passages scenarios ask about.

Behind the scenes, your knowledge base is turned into an encrypted corpus. Scenarios and evals are generated
from it, so they ask about what is really in your documents and check your agent's answers against it. See
[Test your knowledge base](https://docs.plurai.ai/guides/knowledge-base.md).

Files land in `plurai_sim/` next to your agent (or `plurai_sim/envs/<name>/` if you use [environments](https://docs.plurai.ai/guides/environments.md)).

| File | What it is |
| - | - |
| `simulate.py` | The harness. It drives your agent with mocked tools and simulated users. Node agents also get a `bridge/` folder. |
| `plurai.config.yaml` | Every tool with its mode (mock or real) and description, plus harness settings. See [Configuration](https://docs.plurai.ai/reference/config.md). |
| `simulation_prd.md` | The agent specification the suite is built from, including your system prompts quoted verbatim. |
| `scenario_variables.yaml` | The kinds of users and situations to test. |
| `test_mock_contract.py` | Acceptance tests for the mocked tools. Written only when at least one tool is mocked. |
| `artifacts/agent_findings.md` | Potential issues in your agent (see below). |
| `artifacts/pre_generation_findings.md` | Checks of the specification against your knowledge sources, with a **PROCEED** or **FIX FIRST** verdict. Runs only when your agent needs a knowledge corpus. |
| `artifacts/verification.json` | The results of the harness checks, summarized in the run integrity line. |

The scan also writes a managed block to your repo's `.gitignore` that keeps local state and extracted content out of git. See [What to commit](https://docs.plurai.ai/guides/environments.md#what-to-commit).

The specification is uploaded to the Plurai backend so the next stages can build from it. See [Data and privacy](https://docs.plurai.ai/security/data-and-privacy.md).

## Run the scan

> [!NOTE]
>
> You don't have to run this on its own. `/simulate <path-to-your-agent>` runs the scan as part of the full
> flow. Use the command below to run or re-run just this stage.

```bash theme={null}
/simulation-scan-agent <path-to-your-agent>
```

Or say it in chat: "Set up Plurai simulation for my agent in `<path-to-your-agent>`."

| Argument | What it does |
| - | - |
| `<path>` | Your agent's entry module. If you leave it out, the plugin asks for it. |
| `--force` | Re-analyze the agent even when a saved setup exists. |
| `--component "<name and what it does>"` | Test one sub-agent, tool or subgraph. Everything outside it is mocked. |

The scan needs a connection to the Plurai backend. See [Environment variables](https://docs.plurai.ai/reference/environment-variables.md).

## What happens

**1. The plugin reads your agent**

It follows your entry module and its imports: the agent graph, tools, sub-agents, checkpointer, context-loading steps and production dependencies. It also reads your system prompts and instruction files, local data the agent uses, knowledge sources, the endpoints in your code or config, and install notes in your README. From `.env` it reads only the name of your model-provider key, never the key.

**2. You review what's mocked**

The plugin draws your agent's **mocking map**: every system your agent touches, each marked **run for real** (live) or **mocked**, with a one-line reason. You get a summary such as "Mapped your agent — 🟢 4 run for real · 🟡 6 mocked" and a link to the map. When you run the scan on its own, nothing is generated until you approve it. Under `/simulate`, the scan takes its defaults, and you can change anything later in chat.

**3. The plugin writes the harness**

It generates `simulate.py`, `plurai.config.yaml` and the agent specification, runs its checks on the harness, and stages the files with `git add`. It does not commit: the commit is yours.

**4. You get the hand-off**

The scan ends with **Environment ready**, a link to the mocking map, and what to run next.

## The mocking map

The mocking map decides which systems your agent really calls and which it calls in your [digital twin](https://docs.plurai.ai/concepts.md#param-digital-twin) instead. It shows your agent in the center and every surface it touches: tools, sub-agents, retrieval (RAG), knowledge inlined in the prompt, and data stores. For each one it says why it is live or mocked. A surface is mocked for test control (its output isn't deterministic), to save resources, to avoid side effects, or for isolation.

* Every write to your systems is mocked by default. A live write needs your explicit opt-in, and the mocking map warns you about it.
* Reads can run live against the simulated world.

To change the mocking map, say so in chat, for example "run `lookup_invoice` for real" or "mock the CRM". The plugin redraws it and asks again.

The same approval can also ask you to:

* Confirm what the simulated user sees, and anything the simulation leaves out.
* Confirm that the knowledge your agent answers from is complete.
* Allow commands that affect your machine during scored runs (installing packages, writing outside the scenario folder, reaching the network): **Grant all** or **Grant none**.
* Decide how to handle a live write nothing resets between conversations: mock it (recommended), have the harness reset it, or keep it live and accept that conversations see each other's writes.

### Other questions you may see

* **A saved setup exists.** Choose **Use the saved setup** (fast), **Re-verify the saved bench**, **Re-analyze the agent** (use this when your agent changed), or **Focus on one component**.
* **Realistic documents.** If your agent reads or produces documents, the plugin may ask whether scenarios should include a realistic document instead of placeholder text.
* **Installing dependencies.** The plugin names any install command (`pip install`, `npm ci`, …) and waits for your yes before it runs it.

## Potential issues the scan records

While it profiles your agent, the scan notes things your agent can't currently do that the suite has to design around. Each one goes into `artifacts/agent_findings.md` as **potential — may be intended**, with the evidence, why it might be intended, what the suite does about it, and how to confirm it. The hand-off tells you how many it found:

> While profiling I recorded 2 potential issues in the agent — things it cannot currently do that the suite had to design around, and that may be intended.

The scan doesn't rank or fix them. Later stages add confirmed gaps to the same file.

## Supported agents

* **Python**: LangGraph, Claude Agent SDK, Google ADK, CrewAI, OpenAI Agents SDK, LlamaIndex, Strands Agents, LangChain, and custom agents with no framework, such as a plain OpenAI or LiteLLM tool loop.
* **Node (TypeScript or JavaScript)**: LangGraph.js, OpenAI Agents JS, Mastra, Vercel AI SDK, or a custom loop. The harness is still `simulate.py`; it drives your agent through a bridge and needs Node 22.15 or later.
* **Agent platforms**: Salesforce Agentforce (with a logged-in `sf` CLI), n8n, and Claude Code plugin commands and skills.

Other runtimes (Go, Java, Ruby, …) are refused by name. See [Agent frameworks](https://docs.plurai.ai/integrations/agent-frameworks.md) and [Node agents](https://docs.plurai.ai/integrations/node-agents.md).

> [!TIP]
>
> **No agent yet, or want to try it on a toy one first?** Clone a ready-to-run example from
> [500 AI Agents Projects](https://github.com/ashishpatel26/500-AI-Agents-Projects). Its `agents/` folder
> has self-contained LangGraph and CrewAI agents, such as the
> [customer support agent](https://github.com/ashishpatel26/500-AI-Agents-Projects/tree/main/agents/13-customer-support-agent).

## Next steps

> [card] [Ground in production traces](https://docs.plurai.ai/guides/ground-in-production-traces.md)
>
> Optional: base the simulation on real conversations.

> [card] [Build the suite](https://docs.plurai.ai/guides/build-the-suite.md)
>
> Stand up the mock environment and generate scenarios and evals.

> [card] [The scan in the report](https://docs.plurai.ai/report/scan.md)
>
> How the mocking map and findings appear in the report.

> [card] [How it works](https://docs.plurai.ai/how-it-works.md)
>
> The five stages end to end.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.