AI Agent Reference

This page provides detailed reference information for AI agents. Use it to understand details about data connection limitations, security, and version management.

For foundational concepts, see About AI Agents. For configuration guidance, see Create and Configure an AI Agent.

Connect AI agents to your data fabric

This section describes how AI agents can interact with your data fabric and highlights important limitations.

Querying record data

AI agents can query data from a record type. Keep the following in mind:

• Only one record type can be queried at a time. Querying related records is not supported.
• Supported filter operators: =, <>, >, >=, <, <=, between, in, not in, is null, not null, starts with, not starts with, ends with, not ends with, includes, not includes. The search operator is not supported.
• Only AND and OR operators are supported in a!queryLogicalExpression.
• Analytical queries like avg or sum are not supported. To perform these operations, create an expression rule and use it as a tool.
• Smart search is not supported.

Writing record data

AI agents can only write to record types using the Write Records node in a process model.

Requirements for related record writes

You can write to a record type and its related record types in the same Write Records smart service node only if all of the following conditions are met:

• The record types share the same data source.
• The Write or delete option is selected in the relationship configuration.
• You are not using a custom record field as a common field.

Limitations

Keep these limitations in mind when writing record data with AI agents:

• Relationship types: Many-to-one relationships are not supported. Only one-to-one and one-to-many relationships are supported.
• Nested relationships: Not supported.
• Multiple record types: To write to multiple record types using separate static record type inputs, use separate process models. Writing to multiple record types in a single process model is not supported.

Date and datetime behavior

When writing records with an AI agent, keep the following behavior in mind when working with date and datetime fields:

• If the AI agent writes a datetime value into a date field, the time portion is removed.
• If the AI agent writes a date value into a datetime field, a 00:00:00 timestamp is appended, and the value is stored in the database in UTC.

Working with documents

AI agents can retrieve information from files stored in Appian using three system document tools: Semantic Search, Read Full Document, and Query Document. Additionally, AI agents can invoke AI DocCenter models through process model tools for high-accuracy extraction and classification.

The document strategy you choose directly affects your AI agent's accuracy, speed, and AI action consumption. For comprehensive guidance on document tools, selection criteria, cost tradeoffs, and best practices, see Working with Documents in AI Agents.

Document and folder array constraints

When using document or folder arrays as inputs, the following limits apply to prevent performance degradation:

• Max count: 75 documents or folders per AI agent run.
• Max size: 50 MB cumulative total per AI agent run.

For details on configuring array inputs, see Array (multiple values).

Record and primitive array constraints

When using record or primitive data type arrays as inputs or outputs, the following limits apply:

• Max count: 50 items per input/output variable.
• Nested arrays: Not supported.

Manage AI agent versions

Each time you save an AI agent, Appian creates a new version. This allows you to review a full history of changes and revert to a previous configuration if needed.

To view an AI agent's version history:

1. In the Build view, open an AI agent.
2. Click the settings menu and select Versions. A dialog appears with a list of all saved versions.
3. Click a version to open it in a new tab.

You can modify a previous version and save it, which will create a new version without overwriting the old one.

Deploy AI agents

You can export an AI agent from one environment and import it into another, just like any other design object. This is useful for moving AI agents between development, testing, and production environments.

See Deploy AI agents between environments for complete guidance.

Security

When an AI agent invokes a tool, user access determines whether the process continues or stops. The AI agent fails to start if the initiator doesn't have access to required tools.

For more details, see security for expression rules. For troubleshooting permission issues, see Troubleshooting AI Agents.

AI Agent tool behavior

When one AI agent calls another AI agent using the AI Agent tool, the following behavior applies:

• Execution: The sub-agent is invoked by the initiator of the main AI agent and must respect all access controls defined for that sub-agent.
• Timeout: The AI Agent tool has a 60-minute execution timeout.
• Error handling: Only errors up to two levels deep will be surfaced in the main AI agent's error message to prevent deep, recursive error tracing.
• Synchronous calls only: This feature only supports synchronous AI agent calls and does not support parallel or asynchronous execution of multiple AI agents.

AI Agent tool call display

When an AI Agent tool completes, the following information appears in the Test and Monitor tabs:

• Completion message: "I have collaborated with the AI agent . Expand 'See Details' to view the results."
• Expanded details: Shows the Tool UUID, Reasoning, Input (list of AI agent inputs), and Output (list of AI agent outputs).

Logging and auditing

Appian provides system-level audit logs for AI agent executions to support security and compliance requirements. These logs track all AI interactions and can optionally capture sensitive data like prompts and responses.

The AI Input/Output Log is off by default and must be enabled by an administrator. For complete details on audit log types, configuration, and retention policies, see Auditing AI Agent Usage.

Run limitations

AI agents have built-in protections to prevent excessive resource consumption and runaway processes.

Model limitations

AI agents use Appian-managed AI models and do not support models in customer provided AWS accounts.

Maximum tool calls

To prevent runaway AI agents from consuming excessive AI and system resources, Appian automatically stops an AI agent run when it reaches the maximum number of 30 tool calls. If you need to adjust this configuration, submit a support case.

When an AI agent reaches this limit:

• The AI agent execution stops before it attempts to execute the tool call that exceeds the limit.
• The AI agent run status becomes "System Canceled".
• An error message is written to the log indicating the AI agent was cancelled because it reached the maximum tool call limit.

This automatic protection is especially important in production environments where manual intervention may not occur immediately.

Process model tool timeout

Process model tools have a 3-minute execution timeout. If a process model tool takes longer than 3 minutes to complete, the tool call fails and the AI agent run may be affected. If you need to adjust this configuration, submit a support case.

Feedback