Custom Agents

How to create custom AI agent personas in ContextQA to calibrate test execution behavior for specialized application domains such as Salesforce, accessibility testing, or localization.

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.

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

# 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.

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

{
  "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
• AI Test Generation
• Running Tests
• MCP: list_custom_agents

70% less human effort with AI test generation and self-healing. Book a Demo → — See AI generate, execute, and maintain tests for your application.