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.

   Note:  Only simple types are configurable in the Test tab; record types, CDTs (Custom Data Types), and Maps cannot be set there.

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.
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.
• Only simple types are configurable in the Test tab (record types, CDTs, Maps are not).
• 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.

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.

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 Test and Monitor AI Agents.

Feedback