Transform your debugging workflow with one-click root cause analysis and step-by-step remediation guidance
Key Takeaways
The ATF Troubleshooting Agent is an AI-powered capability introduced in the Zurich release as part of Now Assist for Creator. This agent transforms how developers diagnose and resolve Automated Test Framework failures by analyzing test results, logs, and metadata changes to deliver instant root cause analysis and actionable remediation steps. Instead of spending hours tracing through configurations and comparing test runs, developers can now click a single button to receive AI-generated insights explaining exactly what went wrong and how to fix it. This capability is particularly valuable for maintaining regression test suites where previously passing tests suddenly fail due to environmental or metadata changes that are difficult to trace manually.
What You'll Learn
- How the ATF Troubleshooting Agent accelerates test failure resolution
- Step-by-step activation and configuration process
- Real-world scenarios demonstrating AI-powered root cause analysis
- Best practices for integrating the agent into your development workflow
- Prerequisites and licensing requirements for Now Assist for Creator
The Challenge: Test Failure Debugging
Every ServiceNow developer who maintains Automated Test Framework suites has experienced this scenario: a regression test that has been passing reliably for months suddenly fails. The instinct is to start tracing through test steps and configuration, searching for the tiny environmental or metadata change that disrupted the previously successful test. This investigation process can consume hours of development time, pulling focus away from building new features and capabilities. The debugging challenge compounds when test failures become too time-consuming to investigate thoroughly. Development teams may begin skipping tests or accepting failures without resolution, which creates larger problems downstream when defects reach production. The Now Assist for Creator Store app release addresses this pain point directly with the ATF Troubleshooting Agent, an AI-driven capability that automates the investigation process and delivers actionable insights within seconds.
Understanding Test Troubleshooting Agent
The ATF Troubleshooting Agent operates as part of the Now Assist for Creator application, leveraging ServiceNow's generative AI capabilities to analyze failed test results. When invoked, the agent examines server logs, client logs, snapshot changes, and metadata differences between the last successful run and the current failed run. It synthesizes this information into a clear explanation of what went wrong and provides specific steps to resolve the issue.
Key Capabilities:
Root Cause Analysis — The agent examines test failure data and explains exactly what went wrong, presenting the information in terms that help developers understand and address the underlying issue rather than just the symptom.
Step-by-Step Remediation — Beyond diagnosis, the agent provides clear guidance including specific items to examine, configuration changes to make, and steps tailored to the particular failure scenario.
This capability builds upon the Failure Insight feature also introduced in Zurich, which provides a "diff" view comparing metadata between successful and failed test runs. The Troubleshooting Agent takes this further by interpreting the differences, correlating them with log data, and generating human-readable analysis with recommended actions.
Prerequisites
Before activating the ATF Troubleshooting Agent, ensure your environment meets the following requirements. The agent is part of the Now Assist for Creator application and requires proper licensing and plugin activation to function.
| Requirement | Details |
| Release | Zurich or later |
| Required Application | Now Assist for Creator from SN Store |
| Required Plugin | Generative AI Controller |
| Licensing | Creator Pro Plus |
Activating ATF Troubleshooting Agent
Activation of the ATF Troubleshooting Agent occurs through the Now Assist Admin Panel within ServiceNow. This process makes the agent skill available for use when triaging test failures.
Step 1: Navigate to the Admin Panel Access the Now Assist administration interface where AI skills are managed. Use the Application Navigator to find the configuration area. Navigation: All > Now Assist > Now Assist Admin
Step 2: Access the Creator Skills Section Within the Now Assist Admin panel, navigate to the Creator category where development-focused AI skills are organized. Navigation: Now Assist Admin > Creator
Step 3: Locate and Activate the Troubleshooting Agent Search for "Troubleshooting Agent" in the skill list. Select the skill and toggle the activation switch to enable it for your instance.
Once activated, the Troubleshooting Agent becomes available on all ATF test results that contain failure information. The system automatically exposes the triage capability when relevant test failure data exists.
Using the Troubleshooting Agent
With the agent activated, developers can invoke AI-powered analysis directly from failed test results. The workflow integrates seamlessly into the existing ATF interface, requiring minimal changes to established debugging practices.
Workflow Overview: Run ATF Test → Test Fails → Open Test Result → Click "Triage Test Failure" → Review AI Analysis
Step-by-Step Workflow: Begin by navigating to the Automated Test Framework module and locating the test that has failed. This might be through the Test Results list, a scheduled test suite execution, or a notification about a failed test run.
Open the test result record to view the failure details. On the test result form, you will see the "Triage Test Failure" button available for any test with a failure status. This button invokes the Troubleshooting Agent to analyze the failure.
Click the "Triage Test Failure" button to invoke the Troubleshooting Agent. The system begins analyzing the test failure by examining multiple data sources including the test step configuration, execution logs, form snapshots, and metadata changes since the last successful run.
After processing, which typically completes within 30 seconds, the agent presents its findings in a structured format. The output includes an executive summary of the failure reason, detailed analysis of contributing factors, and specific remediation steps tailored to the identified issue.
Integration with Test Failure Insight
The ATF Troubleshooting Agent complements the Failure Insight feature that provides direct metadata comparison capabilities. Failure Insight offers a "diff" view showing exactly what changed between successful and failed runs, while the Troubleshooting Agent interprets these differences and generates actionable recommendations. Developers can use both features together for comprehensive debugging. Start with the Troubleshooting Agent for quick diagnosis and recommended fixes, then use Failure Insight when deeper investigation of specific metadata changes is needed. The combination provides both automated analysis and detailed inspection capabilities.
Best Practices
Maximizing the value of the ATF Troubleshooting Agent requires thoughtful integration into development workflows and test maintenance practices. The following recommendations help teams realize the full potential of AI-assisted test debugging.
- Establish Triage Habits: Train development teams to invoke the Troubleshooting Agent as the first step when test failures occur, before manual investigation begins. This ensures AI assistance is used consistently and prevents teams from defaulting to time-consuming manual debugging for issues the agent could resolve quickly.
- Review and Learn: The agent's analysis provides learning opportunities about test dependencies and configuration relationships. When the agent identifies unexpected dependencies or configuration impacts, document these findings to improve test design and reduce similar failures in the future.
- Maintain Test Isolation: Tests that rely heavily on environmental configuration or shared data are more prone to failures from external changes. Use the insights from troubleshooting sessions to identify opportunities for better test isolation, such as creating test-specific data or explicitly setting values rather than relying on defaults.
- Track Resolution Patterns: Monitor which types of failures the agent resolves most effectively and where manual investigation is still required. This feedback helps optimize test design and identifies areas where additional agent capabilities might be valuable.
Important: Monitor usage against your subscription limits, particularly during periods of high test activity or major releases when multiple test failures may occur simultaneously.
Troubleshooting AFT Troubleshooting Agent
While the ATF Troubleshooting Agent is designed to simplify debugging, certain conditions can affect its availability or analysis quality. Understanding these situations helps ensure effective use of the capability.
If the "Triage Test Failure" button does not appear on test results, verify that the Troubleshooting Agent skill is activated in the Now Assist Admin panel and that the user has appropriate roles including atf_test_admin or atf_test_designer. Also confirm that the Now Assist for Creator application is properly installed and that the Generative AI Controller plugin is active.
When analysis results seem incomplete or do not identify the root cause, this may indicate that the failure involves factors outside the agent's current coverage area. The agent analyzes metadata, logs, and configuration data available within the platform. Failures caused by external integrations, network issues, or timing-related race conditions may require additional manual investigation.
Additional Resources
The following resources provide additional context for the ATF Troubleshooting Agent and related Now Assist for Creator capabilities.
Official Documentation: ServiceNow Product Documentation covers detailed configuration options and technical specifications at docs.servicenow.com under Application Development > ATF Troubleshooting Agent.
Now Assist for Creator Store Page: Review capability descriptions, licensing details, and version requirements at the ServiceNow Store (store.servicenow.com).
Platform Academy Session: The Platform Academy features a dedicated session on ATF with live demonstrations and expert guidance. Search for ATF content in the Platform Academy catalog for hands-on learning and deeper technical exploration.
Community Articles: The ServiceNow Community hosts discussions and additional tutorials about Now Assist for Creator capabilities including the ATF Troubleshooting Agent and related features like Failure Insight.
NOW Learning: Formal training courses covering ATF best practices and Now Assist capabilities are available through the NOW Learning platform.
Conclusion
The ATF Troubleshooting Agent represents a significant evolution in how ServiceNow developers maintain automated test suites. By applying AI to the traditionally manual process of test failure diagnosis, the agent reduces debugging time from hours to seconds while providing actionable remediation guidance. This capability is particularly valuable for enterprise environments with extensive regression test coverage where environmental changes frequently cause previously passing tests to fail. As part of the broader Now Assist for Creator portfolio, the Troubleshooting Agent demonstrates our investment in AI-assisted development tools that handle friction points in the development lifecycle. Combined with capabilities like Build Agent for application creation and the UI Builder Agent for page development, these tools enable development teams to focus on solving business problems rather than debugging configuration archaeology. For organizations running ServiceNow Zurich or later releases, activating the ATF Troubleshooting Agent provides immediate value for test maintenance workflows. The trial availability through PDIs and the ServiceNow Store makes it accessible for evaluation without subscription commitment, allowing teams to experience AI-powered test debugging before broader adoption.
