AI Agent Reference

The AI Agent Reference provides details about agent types, data connection limitations, security, and version management for AI agents.

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

Agent types

Every AI agent has a type that determines where and how it can be used. Agent type is selected at creation and cannot be changed.

Type	Purpose	Deployment method
Process agent	Executes tasks within a process model as part of a business workflow.	Execute AI Agent smart service
Chat agent	Communicates directly with end users through a live chat interface.	Agent chat component (a!agentChatField)

Runtime validation enforces type boundaries. A process agent cannot be used in the agent chat component, and a chat agent cannot be executed via the Execute AI Agent smart service.

Chat agent parameters

When a chat agent is deployed via the agent chat component, the following parameters are available:

Parameter	Description
agent	Reference to the AI agent that powers the chat. Use the agent! domain prefix.
inputs	Map of inputs passed to the chat agent, corresponding to inputs defined in Agent Studio.
title	The title that displays in the bar above the chat. Default: "AI Agent Chat".
height	Determines the component height. Valid values: "EXTRA_SHORT", "SHORT", "SHORT_PLUS", "MEDIUM", "MEDIUM_PLUS", "TALL", "TALL_PLUS", "EXTRA_TALL", "FILL" (default).
placeholder	Text to display in the input field when it is empty.
welcomeMessage	Text displayed in the chat area before the user sends their first message.
showSessionPicker	Determines if the session picker toolbar displays. Default: true.
showWhen	Determines whether the component is displayed on the interface. Default: true.
debugMode	Determines if tool inputs and outputs display for troubleshooting. Default: false.
outputsSaveInto	Saves the outputs received at the end of the AI agent run. Use save!value to reference the output variables.

For the full list of agent chat component parameters, see Agent Chat Component.

Chat agent feedback

Chat agents support the same feedback sources as process agents:

Feedback type	Chat agent	Process agent
Developer feedback (dev-time)	Feedback UI in chat test experience	Feedback UI in test pane
LLM grader (automated)	Same	Same
Dev/Ops feedback (production)	Same	Same

Chat agents appear in the same Monitor view and quality metrics as process agents.

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.

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.

MCP tool limitations

MCP tools connect AI agents to external systems through the Model Context Protocol. The following limitations apply to MCP tools. For setup and usage details, see MCP Tools for AI Agents.

Limitation	Details
Supported MCP primitives	Tools only. MCP resources and prompts are not supported.
Authentication methods	API key and OAuth 2.0 Client Credentials Grant only. Personal Access Tokens (PATs) can be configured using the API key method.
Server or tool count limits	No Appian-imposed limit on MCP servers or tools per agent.
Server unavailability at design time	If the MCP server is unavailable when adding tools, the AI agent displays an error. You cannot select tools until the server responds.
Server unavailability at runtime	If the MCP server is unavailable during execution, the AI agent receives an error during the tool call step.
Tool schema changes	If an MCP server removes a tool or changes a tool's name after you add it to an agent, you must reconfigure the affected tools manually. However, if only the tool's schema (definition or input schema) changes, the AI agent automatically picks up the latest tool definition at runtime.
Rate limiting	Appian does not limit MCP tool calls. External MCP servers may enforce their own rate limits.

Parallel tool execution

AI agents can execute multiple independent tool calls in parallel within a single reasoning step. Parallel execution uses a fan-out/fan-in model: the system dispatches all parallel calls simultaneously, waits for every call to complete, then sends consolidated results back to the AI model for the next reasoning step.

Maximum concurrent calls

Each reasoning step supports a maximum of five parallel tool calls. Sub-agent tool calls do not count toward this limit; the limit applies independently at each primary AI agent. If the AI agent attempts more than five concurrent calls, the system executes the first five and queues the remainder for subsequent steps.

Error handling for parallel tool calls

If one or more tool calls fail during parallel execution, the remaining calls still complete. Failed calls do not block successful ones. After all parallel calls finish, the system sends error messages for failed calls alongside successful results to the AI model. The AI model then determines the next action based on the combined results and errors.

You can click the error status on a tool call card in the Test or Monitor tab to view the specific error message.

Guiding parallel behavior

Parallel tool calling is enabled by default. You can add specific instructions to your AI agent to guide when tools should run in parallel versus sequentially. This can help yield more consistent results for tasks that require a particular execution order.

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 30-minute execution timeout. The AI agent executes process model tools asynchronously, which allows long-running processes to complete without blocking the AI agent. If a process model tool takes longer than 30 minutes to complete, the tool call fails and the AI agent run may be affected.

Parallel tool calls

AI agents can execute multiple tool calls in parallel when the tools are independent. The AI model determines which tool calls can run simultaneously based on whether the calls depend on each other's results.

Parallel tool call behavior:

• Maximum concurrent calls: Up to 5 tool calls can execute in parallel within a single AI agent run.
• Independence requirement: The AI model only parallelizes tool calls that do not depend on each other's output. If one tool call requires the result of another, the AI agent executes them sequentially.
• Error handling: If one or more parallel tool calls fail, each failed tool call displays its own error message in the run history. The AI agent evaluates the results of all parallel calls—including any failures—and determines its next action.
• AI agent tool limitation: Calls to other AI agents using the AI agent tool always execute sequentially, even when other tool types can run in parallel.

AI guardrails enforcement

AI agents respect environment-wide AI guardrails configured by administrators. Guardrails enforce content safety policies across all AI capabilities, including AI agents.

Behavior when guardrails block a request

When AI guardrails block an AI agent's request or response, the AI agent returns the default message configured in the Administration Console. The AI agent run completes with the guardrail response in place of the blocked content.

Developer feedback

AI agents support structured developer feedback during evaluation. Developers can record quality judgments directly on test results to track AI agent performance over time.

Feedback model

Developer feedback targets the AI agent run level, rating the overall outcome of an entire AI agent run. AI agent run feedback contributes to the Overall Accuracy metric in the Evaluate tab.

Strong examples

Runs that receive a thumbs-up rating can be saved as strong examples. Strong examples represent ideal AI agent behavior and serve as reference outputs.

Feedback persistence

Feedback data is attached to a specific AI agent run, which is linked to an AI agent version. When multiple developers rate the same run differently, all ratings are stored and metrics average across all feedback received.

Evaluation metrics

The Evaluate tab displays the following metrics derived from developer feedback:

Metric	Calculation
Overall Accuracy	Number of thumbs-up ratings divided by total number of feedback ratings received at the run level. Runs without feedback are not included in the calculation.
Average Test Time	Average AI agent run duration across all test cases in an evaluation.
Average AI Actions per Test	Average AI actions consumed per AI agent run in an evaluation.

Evaluation metrics appear only in the Evaluate tab for Appian 26.6.

Feedback