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
Open your ContextQA workspace.
In the left navigation, go to Custom Agents (route: /td/:versionId/custom_agents).
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
From the Custom Agents list, click + New Agent.
Enter a Name — a descriptive label (e.g., "Salesforce Lightning Agent", "Accessibility Auditor").
Enter the Description / System Prompt — plain-English behavioral instructions for this persona.
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:
Accessibility Auditor:
Financial Application Agent:
❌ 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
Open a test case and click Run.
In the execution settings panel, select a Custom Agent from the dropdown.
Click Execute.
Via the MCP server
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.
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
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
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.
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.
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.
# 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"
)
{
"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."
}
