skip to content

[ agent view ]

raw .md[ view as human ]

Documentation Index

Fetch the complete documentation index at: https://e2e.com/docs/llms.txt Use this file to discover all available pages before exploring further.

Agents and personas

Configure several agents in one suite, pin tests to them, and run one flow as each persona.

An agent is a named entry in agents with its own model, instructions, and tools. Tests use default unless you select another agent. Name more agents to compare models or to run one flow as several personas.

Define named agents


const vocabulary = 'Plans are called tiers. Billing lives under Settings. "Approve" on an order refunds it.';

export default {
  targets: [{ engine: web(), app: { url: 'http://localhost:3000' } }],
  agents: {
    default: { model: gateway('openai/gpt-6-luna-fast'), context: vocabulary },
    thorough: {
      model: gateway('anthropic/claude-opus-5'),
      system: 'Verify every claim on screen before concluding a step.',
      context: vocabulary,
    },
    buyer: { model: gateway('openai/gpt-6-luna-fast'), system: 'You are a first-time buyer.', context: vocabulary },
    admin: { model: gateway('openai/gpt-6-luna-fast'), system: 'You manage orders and approve refunds.', context: vocabulary },
  },
} satisfies E2EConfig;

An entry holds the model, an optional judge, system, context, tools, budgets, and providerOptions. maxSteps caps the actions of one step and maxModelCalls its model calls: 25 by default, 100 at most. See the config reference.

Entries don't inherit from default. Give each one the model and context it needs, for example from a shared constant as above.

A custom executor goes under executor. The model, judge, context, and budgets still apply. system and tools are rejected, since the executor brings its own prompt and tools.

Instructions and vocabulary

systemcontext
AnswersHow should the acting agent work?What does this app call things?
Who reads itThe act loop onlyEvery model call: act turns and the judges behind assert, waitFor, and extract
Belongs herePersona, caution, what to verify before finishing, how to treat unexpected dialogsNames of screens and menus, where a feature lives, which button submits a form, domain terms
Set onagents.<name>.systemagents.<name>.context, at most 16 KiB

A judge never sees system, so "a step is done once the form closes" can't lower the bar for a verdict. Rule of thumb: true for any tester on this app goes in context, true for this tester on any app goes in system.

A test or group appends its own vocabulary to context with agentContext. Use it for facts only that test knows, such as seeded data or a feature flag that changes a label:


describe('billing', { agentContext: 'The seeded workspace is called "Acme Trial".' }, () => {
  test('upgrades the tier', async ({ agent }) => { /* ... */ });
});

Keep instructions out of agentContext: it reaches the judges too.

Under e2e run, every prompt also opens with the test's title path, such as Test: billing > upgrades the tier. The judges read it too, so name a test for what it covers, not for the verdict you expect.

Pick an agent per run

--agent chooses the agent for tests that don't select one. Several names run each test one time per agent:

<CodeGroup>
npx e2e run --agent thorough tests/checkout.e2e.ts
npx e2e run --agent buyer,admin
pnpm exec e2e run --agent thorough tests/checkout.e2e.ts
pnpm exec e2e run --agent buyer,admin
bunx e2e run --agent thorough tests/checkout.e2e.ts
bunx e2e run --agent buyer,admin
</CodeGroup>

Pin an agent in the suite

A test, a describe block, or one call can select an agent. The closest setting wins: call, then test, then enclosing groups, then run.


describe('checkout as a first-time buyer', { agent: 'buyer' }, () => {
  test('pays for one item', async ({ app, agent }) => { /* ... */ });

  describe('refunds', { agent: 'admin' }, () => {
    test('refunds the order', async ({ agent }) => { /* ... */ });
  });

  test('reorders, and the admin approves', async ({ app, agent }) => {
    await app.open('/orders');
    await agent.act('reorder the most recent order');
    // The admin's act call sees what the earlier steps of this test did.
    await agent.act('approve the pending reorder', { agent: 'admin' });
    await agent.assert('the reorder shows as approved');
  });
});

--agent doesn't replace an agent that a test selects. An unknown agent on a test or group fails during collection. An unknown agent on a call raises INVALID_ARGUMENT. Reports record the agent of each step.

One flow, several personas

<Video>
<video src="/images/personas.mp4" aria-label="Four agents, each a persona who reads one language, run the same localization tests. The Arabic run fails on a button left in English." muted loop playsInline controls />

Four personas, one per language, run the same localization suite.

</Video>

Select several agents to run the same test one time with each:


describe('checkout', { agent: ['buyer', 'admin'] }, () => {
  test('pays for one item', async ({ app, agent }) => { /* runs once per persona */ });
  test('applies a promo code', async ({ app, agent }) => { /* ... */ });
});

Each agent gets its own result and artifact directory. Terminal and JUnit test names include the agent, such as [admin].

--agent selects among the pinned agents and never adds one. Here, --agent admin runs only admin. --agent thorough matches neither, so both still run.

A serial group runs as one unit per agent, and its members share the group's pin. A setup test pins at most one agent.

Each agent records its own replay cache entries, keyed by its name and context. buyer never replays the steps of admin, and a changed agentContext records again.

An agent is not a signed-in user. For signed-in personas, pair each agent with a session in a separate describe block. See Authentication.

Make the agent yours

When a step fails or uses too many calls, open its report, or run with --debug to see the transcript. Fix the instruction first, using the labels on screen. When the problem affects several tests, fix the agent: vocabulary in context, instructions in system, or a tool for an operation such as seeding a cart through a test API. To compare models or providerOptions, run the same tests with --agent <name>.

Next

<CardGroup cols={2}>
<Card title="Project tools" icon="wrench" href="/tools">

Give the agent a test API or a device toolkit.

</Card>
<Card title="Custom executors" icon="gears" href="/executors">

Change how the agent chooses and performs actions.

</Card>
</CardGroup>