Troubleshooting AI Agents

AI agents are powerful tools, but sometimes runs can fail. This guide provides a compact quick path plus detailed guides so you can quickly identify the root cause and apply the correct fix.

Investigate failing AI agent runs

To troubleshoot a failing AI agent run:

1. Reproduce the issue on the Test tab using a saved test case. This ensures your inputs are controlled and repeatable. Use expression mode to define complex data types like records, CDTs, and maps.
2. From the Monitor tab, collect context for reference: Request ID, agent version, inputs used, tools invoked, and timestamps.
3. Open the failing run and select the error to view details and category:
   • System Error: This is likely a platform or system object. Try again; if it persists, escalate to an administrator.
   • Tool Execution Error: This is a user-configured object (process model, rule). You can try to fix this.
4. Follow the link in the error details to the failing object (process instance, rule, query).
5. Apply the matching quick fix from below, then re-run with the same test case and confirm in the Monitor tab.
6. Validate the fix in the Test tab with the same saved case.
   1. Confirm step history and outputs.
   2. Save/rename the test case for future regression checks.
   3. In the Monitor tab, verify status, tool-call count, duration, and requester.
7. If it's fixed, keep the test case for regression. If not, escalate to an administrator and include the Request ID, agent version, failing object, timestamps, and screenshots.

Quick fixes

Use this table to quickly identify and resolve common issues. For more detailed guidance, see How to solve common issues with AI agents.

Symptom	Likely cause	Quick fix
Run fails immediately; permission message	Initiator lacks access to a required tool	Grant initiator access to all tools the AI agent may call; re-run.
Status shows "User Canceled"	You manually stopped the run	This is expected behavior when you click Stop. Review the steps completed before cancellation to identify issues. See Stop a running AI agent.
Status shows "System Canceled"	AI agent exceeded maximum tool calls (default: 30)	Review your AI agent's instructions and tool configuration to prevent excessive tool calls. See Run limitations.
Test fails with expression error	Invalid expression syntax in test input	Check the inline error message in the expression editor; confirm your expression is valid before running the test.
Early step throws null/type error	Missing or invalid inputs	Correct names/types; re-test with saved case.
Tool runs, then fails to format output	Output type mismatch	Align tool output to the configured output type.
Process tool shows node exception/timeout	Logic/timeout inside process model	Inspect instance vars; add error handling; avoid deep subprocess chains.
Expression evaluation error	Bad params or unsafe nulls in a rule	Unit-test rule with same inputs; add guards/defaults.
Record query empty/operator error	Unsupported operator or multi-record join attempt	Query one record type; use supported operators; move aggregations into a rule.
"Finds nothing" in document	Unsupported file, image-only PDF, too large/long	Use supported Appian docs with extractable text; mind size/page limits.

How to solve common issues with AI agents

This section provides detailed troubleshooting steps for specific types of failures. Each heading below represents a potential solution category that can help resolve different types of AI agent run failures.

Reproduce and collect context

• Reproduce in the Test tab with a saved test case; keep inputs stable across runs.
• Use expression mode to define test data for complex data types like records, CDTs, and maps. This allows you to create realistic test scenarios that reliably reproduce failing runs.
• From the Monitor tab, capture: Request ID, agent version, inputs used, tools invoked, timestamps.

Interpreting error details

• System Error (platform/system object): Retry once; if it persists, escalate with the items listed in When to escalate.
• Tool Execution Error (your objects): The failure is in a process model, rule, query, or document step. Follow the error link to fix.
• User Canceled: You manually stopped the AI agent run by clicking the Stop button. The agent stopped between steps, after any running tool completed.
• System Canceled: The AI agent run was automatically stopped because it reached the maximum number of tool calls (default: 30). This protects against runaway agents consuming excessive resources.

Jump to the failing object

• From the error panel, open the linked process model instance or expression rule.
• For process issues, drill into Process Activity to view node errors, PVs, and timing.

Access and security issues

• Symptom: The AI agent run fails immediately with a permission/access error.
• Fix: Ensure the initiator (or calling process) has access to every tool the AI agent may invoke. Re-run.
• Why it happens: Pre-execution checks block the run if any required tool is inaccessible.

Missing or invalid inputs

• Symptom: Early step error; nulls or wrong types.
• Fix: Verify required inputs and data types on the AI agent; correct names/defaults. Re-run with the same saved test case.

Output formatting and type mismatches

• Symptom: Tool executes, then fails when formatting to the configured output type.
• Fix: Align the tool's actual output structure with the AI agent's configured output type, or adjust the output definition accordingly. For list-based outputs, ensure the AI agent generates properly formatted data that can be parsed into the expected list structure.

Process model tool failures

• Symptom: Tool Execution Error; process instance shows node exceptions or timeouts.
• Fix:
  • Open the failing instance; inspect node inputs/outputs and PVs.
  • Implement proper error handling in your process models to prevent errors.
  • Add sensible defaults; shorten long waits.
  • Avoid deeply nested subprocess chains; surface errors earlier.
  • Important: The default tool execution timeout is 3 minutes. Do not assign long-running process model tools to the AI agent.

Expression rule tool errors

• Symptom: Expression evaluation error, invalid parameters, unexpected nulls.
• Fix:
  • Open the rule from the error panel; unit-test with the same inputs used by the AI agent.
  • Add null guards and defaults; simplify complex expressions or split them into helper rules.

Record type query issues

• Symptom: Empty results or operator errors.
• Fix:
  • Each query targets one record type (no related record types).
  • Need aggregations (sum, avg)? Wrap them in an expression rule and call that as a tool.
  • Smart search is not supported for record query tools. Write your own smart search query using an expression rule tool.

Document and folder tool issues

• Symptom: Agent "finds nothing" in a file; no explicit error.
• Fix:
  • The source must be an Appian document of a supported type.
  • Image-only PDFs (no embedded text) won't be read.
  • Full-document read supports PDFs up to ~20 pages; total size ≤ 100 MB; English content only.
  • Unsupported files are skipped (no error).
  • Guidance: The AI agent automatically chooses the document method (fact lookup vs whole-document reasoning vs extraction).

When to escalate

Escalate only if the error persists after a retry. Include the following details:

• Request ID, failing object/tool, timestamps
• Screenshot of the error panel
• A brief summary of what you already tried

Best practices

The best way to avoid troubleshooting is to design your AI agents with reliability in mind from the start. These practices help prevent common issues and make debugging easier when problems do occur.

• Start with a minimal AI agent that performs a simple intake or triage task, then add tools and complexity gradually.
• Name your inputs clearly and avoid creating multiple tools that do the same thing. This helps the AI agent select the correct tool unambiguously.
• When calling an AI agent from a process model, use the Execute AI Agent smart service to pass structured data and capture outputs for easier downstream debugging.

See the Best Practices for Designing AI Agents for more helpful tips. For testing guidance, see Monitor AI Agents.

Feedback