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 and its related records in the same Write Records smart service node only if all of the following conditions are met:

• The relationship configuration permits it.
• The records share the same data source.
• The related record type uses the same data source as the base record type.
• The Write or delete option is selected in the relationship configuration.
• You are not using a custom 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 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.

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 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.

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.

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