With agent instructions, you can enforce your team’s testing standards as they apply to test authoring, results analysis, and runtime recovery.
Agent instructions are user-defined rules that shape how the mabl agent carries out its tasks. Use them to embed business logic, application-specific nuances, and governance rules into the context agents carry into every task. For example:
“When creating variables, always use the naming convention
prefix_descriptive_name.”“For the checkout application, always verify the total price after adding items to the cart.”
"When analyzing failing test runs, begin responses with explaining whether the test is flaky."
Read on to learn more on managing agent instructions and guidelines for writing instructions that work.
Managing agent instructions
Agent instructions are located on the Agents > Settings page. Any user with editing permissions can create, edit, enable, or disable an instruction.
Scopes
By default, agent instructions apply at the workspace level. When you add or edit instructions, you can narrow its scope to one or more of the following areas:
- Capability: authoring or runtime recovery
- Application: one or more applications
- Environment: one or more environments
Enabling/Disabling
Use the on/off toggle on the agent settings page to disable an instruction without deleting it. Disabled instructions are saved but not sent to agents.
Guidelines for writing agent instructions
Writing effective agent instructions is about more than just filling the 1,000 character limit. The following section offers guidelines for getting the most out of your instructions.
Scope each instruction deliberately
When you add an instruction, ask two questions:
- Which capability does this belong to: authoring (test creation) or runtime recovery?
- Does it apply everywhere, or only to specific applications, environments, or test types?
Scoping your instructions deliberately will help the agent perform better. Scope instructions are also easier to maintain: if your application’s behavior changes, you’ll know which instructions to revisit.
- Worse: “Always verify the total price after adding items to cart.” - applied at the workspace level
- Better: “Always verify the total price after adding items to cart.” - scoped to the authoring capability and the Checkout application
Keep instructions relevant to the capability
Each agentic capability has a different job. The authoring agent generates test steps. The runtime recovery agent decides how to respond when a step fails mid-run. An instruction that’s useful for one could be noise for another.
When you scope an instruction to a capability, make sure the guidance matches that capability’s job:
- Authoring: how to interact with your app, naming conventions for variables, steps to include or avoid. Keep in mind the agent’s test authoring capabilities.
- Runtime recovery: how to respond to unexpected modals, pagination, or intermittent load issues.
Writing “use the naming convention prefix_descriptive_name for new variables” and scoping it to runtime recovery won’t do anything useful because the recovery agent isn’t creating variables. Keep the guidance aligned with what the agent is being asked to do.
Iterate on instructions as needed
Like all good AI prompting workflows, agent instructions benefit from thoughtful iteration. For example, you could start with a set of narrowly scoped instructions, observe how agents behave, and refine from there. To test whether a specific instruction is helping, try disabling temporarily to see if it’s making a difference.