> For the complete documentation index, see [llms.txt](https://learning.contextqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learning.contextqa.com/enterprise-application-testing/web-testing/ai-agent-step-controls.md).

# AI Agent Steps and Runtime Controls

Configure ContextQA AI agent steps with explicit outcomes, image quality, organization AI defaults, URL conditions, loops, and environment-backed runtime data.

> **Documentation owner:** [Deep Barot](https://contextqa.com/academy/) · **Last updated:** November 11, 2026

## Quick answer

Use an **AI Agent** step for an outcome that needs application context, keep deterministic assertions explicit, and configure image quality and AI behavior deliberately. Review URL conditions, loop stopping rules, and runtime-variable scope before execution. The organization default supplies AI behavior when a case or step does not override it.

## Key takeaways

* Describe an observable business outcome and a stopping condition.
* Use exact data and deterministic checks when they express the requirement.
* Keep prerequisites and runtime variables scoped to the intended execution.

## Write a reviewable agent task

1. Open the test's step editor and choose **AI Agent**.
2. Describe the starting state, allowed action, expected outcome, and stopping condition.
3. Refer to the selected environment's variables rather than embedding credentials or environment-specific literals.
4. Review the **High quality image** option for tasks that depend on fine visual details. Confirm the actual evidence is readable; the option does not guarantee a correct decision.
5. Review the effective AI action and save the step deliberately.
6. Run the case and compare the observed outcome with the requirement.

```
Find the order created by the prerequisite using its returned order ID.
Open its details and verify that the currency and total match the expected
values. Stop after reading the status; do not create or submit another order.
```

## Review organization AI defaults

Open **Settings → Organization → AI Configuration**. Review **Default AI Action** and the explanation shown below the selected option. For example, **Create step** describes suggesting fixes while waiting for approval. Save only when you intend to change the policy; inspect case-level behavior before relying on inheritance.

![Organization default AI action and its approval explanation](https://4255556216-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKlyaXxb76z3Dn47TrZkU%2Fuploads%2Fgit-blob-8baf602b7a86b651945a1b3880bbaa56be8ad610%2Forganization-ai-action.jpg?alt=media)

## URL conditions and loops

For a **URL contains** condition, provide the intended substring and verify the saved value before replay. Use a specific route fragment when a broad domain match would allow the wrong page. A URL match is a navigation check, not proof that the record or transaction is correct.

For **If** and **While** steps, review the condition, contained steps, and exit path. Avoid loops that can repeat a purchase, message, or record creation without an explicit stopping rule. Test both the true and false branches using controlled data.

## Runtime values and prerequisites

Capture an identifier from the setup step and pass that exact value to downstream checks. Verify it is available at the intended scope, including within prerequisite and step-group executions. A value from another run or role can make a test inspect the wrong record while appearing to succeed.

Use [Environment and Data](https://learning.contextqa.com/enterprise-application-testing/web-testing/environment-data-management.md) to manage shared configuration, selected profiles, and environment-specific values. A change to shared data should be checked against dependent cases.

## Common questions

### Should every assertion use AI?

No. Exact text, value, and URL checks can express deterministic requirements clearly. Use contextual or visual evaluation when the requirement needs it, and inspect ambiguous results.

### Does a high-quality screenshot prove the result?

No. It improves the input available for visual inspection; the expected-versus-actual result and application state still need review.

### What should I do if a prerequisite fails?

Inspect setup and the configured recovery policy. Do not count downstream cases that were skipped or never reached as passes. See [execution recovery](https://learning.contextqa.com/enterprise-application-testing/reporting/execution-journey-and-auto-fix.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://learning.contextqa.com/enterprise-application-testing/web-testing/ai-agent-step-controls.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
