# Custom Agents

{% hint style="info" %}
**Who is this for?** All roles — particularly SDETs and QA engineers who need domain-specific AI behavior for Salesforce, accessibility testing, financial applications, or other specialized domains.
{% endhint %}

A Custom Agent is a named AI persona with a domain-specific system prompt that shapes how the AI agent behaves during test execution. While the default ContextQA AI agent is calibrated for general web and mobile testing, custom agents let you tune the behavior for specialized application types, testing methodologies, or organizational conventions.

***

## When to Use Custom Agents

Use a custom agent when the default AI agent's behavior is not optimal for your domain:

| Scenario                       | What custom agent solves                                                                                           |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| Salesforce Lightning UI        | Teaches the agent to recognize Lightning component naming patterns, handle record pages, and navigate App Launcher |
| Accessibility testing          | Instructs the agent to flag missing ARIA labels, poor color contrast, and keyboard navigation issues on every page |
| Localization / RTL apps        | Calibrates the agent for right-to-left layouts and non-ASCII character handling                                    |
| Financial applications         | Encodes domain knowledge about currency formatting, decimal precision, and financial calculation validation        |
| Healthcare / EHR systems       | Trains the agent on clinical workflow patterns (patient records, order entry, clinical notes)                      |
| Internal tools with unusual UX | Encodes institutional knowledge about non-standard UI patterns specific to your internal applications              |

Custom agents are applied per execution — you choose which agent to use when triggering a test case or test plan.

***

## Accessing Custom Agents

1. Open your ContextQA workspace.
2. In the left navigation, go to **Custom Agents** (route: `/td/:versionId/custom_agents`).
3. The Custom Agents list shows all personas for this workspace.

> **Access note:** Custom Agents requires a plan with advanced AI features. Contact your workspace administrator if this option is not visible.

***

## Creating a Custom Agent

1. From the Custom Agents list, click **+ New Agent**.
2. Enter a **Name** — a descriptive label (e.g., "Salesforce Lightning Agent", "Accessibility Auditor").
3. Enter the **Description / System Prompt** — plain-English behavioral instructions for this persona.
4. Click **Save**.

The agent is now available for selection when executing test cases and test plans.

***

## Writing Effective Agent Descriptions

The agent description (system prompt) tells the AI how to behave throughout the test execution. Think of it as a job description for a specialized QA engineer.

### ✅ Effective agent descriptions

**Salesforce Lightning Agent:**

```
You are a Salesforce QA engineer specialized in testing Lightning Experience.
- When navigating Salesforce, use the App Launcher (grid icon in the top-left) to open applications.
- Record pages use a two-column layout; the related lists are in the right column.
- Lightning component IDs include random strings — match components by their visible label text, not by ID.
- Use the Global Search bar at the top for navigating to records. Enter a search term, wait for autocomplete, then select the correct record type.
- When creating or editing records, look for the "Save" button in the top-right of the record form.
- If Salesforce shows a "Mixed Content Warning" or "Enhanced Security" prompt, click Allow.
```

**Accessibility Auditor:**

```
You are an accessibility testing specialist. In addition to executing test steps, perform these checks on every page:
- Check that all images have meaningful alt text (not empty or "image").
- Verify that all interactive elements (buttons, links, form fields) are reachable via Tab key navigation.
- Flag any text that appears to have insufficient contrast against its background.
- Confirm that form fields have visible labels or aria-label attributes.
- Report any ARIA roles or aria-* attributes that appear misapplied.
Add accessibility findings as additional observations in your step results.
```

**Financial Application Agent:**

```
You are a QA engineer testing a financial services application.
- All monetary values should be formatted with two decimal places and appropriate currency symbols.
- When comparing calculated totals, allow for rounding differences of ±$0.01.
- When entering test amounts, always use even dollar values (e.g., $100.00, $250.00) unless the test case specifically requires fractional cents.
- When the application shows an "Are you sure?" confirmation before submitting financial transactions, always confirm.
- The "pending" state in transaction lists is expected and should not be treated as an error.
```

### ❌ Anti-patterns

* **Too short:** `"Test the application carefully."` — provides no actionable guidance.
* **Contradictory:** Including both "click Accept on all dialogs" and "dismiss unexpected dialogs" creates conflicting behavior.
* **Overly rigid selectors:** `"The submit button has ID btn-submit-9xa3"` — these IDs change and will cause failures after the next deploy.

***

## Using a Custom Agent in Test Executions

### Via the portal

1. Open a test case and click **Run**.
2. In the execution settings panel, select a **Custom Agent** from the dropdown.
3. Click **Execute**.

### Via the MCP server

```python
# Get available agent IDs
agents = list_custom_agents()  # returns [{id: "agent_abc123", name: "Salesforce Lightning Agent"}, ...]

# Execute with a specific agent
execute_test_case(
    test_case_id=18688,
    persona_id="agent_abc123"
)

# Execute a test plan with a custom agent
execute_test_plan(
    test_plan_id=42,
    persona_id="agent_abc123"
)
```

***

## Combining Custom Agents with Knowledge Bases

Custom agents and knowledge bases serve complementary purposes:

| Feature            | Purpose                                                                                | Scope                                  |
| ------------------ | -------------------------------------------------------------------------------------- | -------------------------------------- |
| **Custom Agent**   | *How* the AI behaves (domain expertise, testing methodology)                           | Applied per execution                  |
| **Knowledge Base** | *What* the AI should do when specific situations arise (close banners, use test cards) | Applied per workspace or per execution |

Best practice: Use the custom agent for domain-wide behavioral calibration, and knowledge base entries for specific recurring UI situations.

```python
execute_test_plan(
    test_plan_id=42,
    persona_id="agent_abc123",    # Salesforce domain expertise
    knowledge_id="kb_xyz789"      # "Close session warning modals"
)
```

***

## MCP Tools for Custom Agents

| Tool                                | Purpose                             |
| ----------------------------------- | ----------------------------------- |
| `list_custom_agents`                | List all agents and get their IDs   |
| `create_custom_agent`               | Create a new agent programmatically |
| `execute_test_case(persona_id=...)` | Apply an agent to a test case run   |
| `execute_test_plan(persona_id=...)` | Apply an agent to a test plan run   |

### Create via MCP

```json
{
  "name": "E-Commerce Checkout Agent",
  "description": "You are a QA engineer specialized in e-commerce checkout flows. When testing checkout: always use the test credit card 4111111111111111 with any future expiry date and CVV 123. When prompted about address verification, select the 'Use entered address' option. After submitting an order, wait up to 15 seconds for the order confirmation number to appear before considering the step failed."
}
```

***

## Managing Custom Agents

| Action          | How                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| Edit an agent   | Click the agent name → Edit description                                                                       |
| Delete an agent | Click the three-dot menu → Delete                                                                             |
| Test an agent   | Run a representative test case with the agent selected; review the execution video for behavioral differences |

***

## Related Pages

* [Knowledge Base](https://learning.contextqa.com/ai-features/knowledge-base)
* [AI Test Generation](https://learning.contextqa.com/ai-features/ai-test-generation)
* [Running Tests](https://learning.contextqa.com/execution/running-tests)
* [MCP: list\_custom\_agents](https://learning.contextqa.com/mcp-server/tool-reference/telemetry-and-agents)

{% hint style="info" %}
**70% less human effort with AI test generation and self-healing.** [**Book a Demo →**](https://contextqa.com/book-a-demo/) — See AI generate, execute, and maintain tests for your application.
{% endhint %}