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 the AI agent.
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.
shape	Determines the shape of the component container. Valid values: "SQUARED", "SEMI_ROUNDED", "FULLY_ROUNDED". Default: "SQUARED".
showBorder	Determines whether a border displays around the component. 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 query record data using the Query Records and SQL Query Records system tools. Query Records uses a!queryRecordType() to filter, sort, and aggregate data from the assigned record types, but it doesn't support record type relationships. SQL Query Records uses SQL to join data across related record types, which is best for advanced queries like multi-step aggregations or custom joins.

If both query tools are enabled, the agent will prefer SQL Query Records and fall back to Query Records.

The two tools share some behaviors and differ in others.

Both tools:

• Are scoped to the record types assigned to the AI agent. If a record type isn't added as a resource in the agent, neither tool can access it.
• Can only query synced record types. Unsynced and legacy record types aren't supported.
• Run as the authenticated user and enforce record type object security, record-level security, and field-level security, so the agent sees only data the user can access.
• Don't support real-time custom fields.

Query Records:

• When parallel tool calls are enabled or a cross-record-type join isn't possible, queries each record type separately and matches related records after retrieval, rather than running a single join.
• Supports these filter operators: =, <>, >, >=, <, <=, between, in, not in, is null, not null, starts with, not starts with, ends with, not ends with, and includes. The search operator isn't supported.
• Supports only the AND and OR operators in a!queryLogicalExpression.
• Doesn't support smart search.

SQL Query Records:

• Joins data across record types when the record types have a defined relationship in the data fabric.
• Can't query record types that use record-level security expressions. If both tools are added, the agent automatically falls back to Query Records for those record types.
• Uses the same underlying SQL API infrastructure as the data fabric tools on Appian MCP Server.

When a query fails, the AI agent receives an error message describing the failure, such as a syntax error it can self-correct, a timeout on an overly broad query, a permission-denied error, or an excluded record type.

Query Records and SQL Query Records executions appear as tool call cards in the Test and Monitor tabs. Expand the tool call card to view the query the agent submitted and the returned results or error.

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 conversion when writing records

When an AI agent writes records that contain date or datetime fields, the following type conversion behavior applies:

• 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 five system document tools: Semantic Search, Read Full Document, Query Document, Query Visual Document, and Query Spreadsheet. Additionally, AI agents can invoke AI DocCenter models through process model tools for high-accuracy extraction and classification.

The document tools available to your AI agent directly affect its 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).

Document tool supported file types and limits

Each system document tool supports specific file types with size and page limits. Use this table to determine which tool supports your file format and to understand the processing constraints.

Tool	File type	Max file size	Page limit	Max image size
Query Document (text mode)	PDF	25 MB	100 pages	N/A
Query Document (text mode)	JPEG, PNG	10 MB	N/A	10k x 10k pixels
Query Document (text mode)	TIFF (single-page)	10 MB	1 page	10k x 10k pixels
Query Document (text mode)	TIFF (multi-page)	10 MB	100 pages	4k x 4k pixels
Query Document (text mode)	DOCX	4.5 MB	N/A	N/A
Query Document (text mode)	HTML, MD, TXT	4.5 MB	N/A	N/A
Query Visual Document	PDF	24 MB	100 pages	N/A
Query Visual Document	JPEG, PNG	3.75 MB	N/A	8k x 8k pixels
Query Visual Document	TIFF (single-page)	3.75 MB	1 page	4k x 4k pixels
Query Visual Document	TIFF (multi-page)	18 MB	20 pages	4k x 4k pixels
Query Spreadsheet	XLS, XLSX, XLSM	10 MB	N/A	N/A
Query Spreadsheet	CSV	10 MB	N/A	N/A
Read Full Document	PDF	25 MB	20 pages	10k x 10k pixels
Semantic Search	PDF, DOC, DOCX, HTML, MD, TXT	50 MB cumulative	N/A	N/A

Query Spreadsheet additional limits:

• Maximum 2 million cells per file.
• Maximum 40,000 rows and 200 columns per sheet.
• Maximum 100 sheets per workbook.

For guidance on how your AI agent selects document tools and how to influence that selection, see Working with Documents in AI Agents.

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.

Variable indexing for Monitor search

Input and variable values are indexed at run creation time to support server-side search in the Monitor tab. The system converts input values into user-friendly text representations for indexing—document names rather than UUIDs, space-separated words rather than camelCase, and human-readable summaries for complex types.

The following indexing behaviors apply to input variables:

• Search scope: Only input variable values are indexed for search. You cannot search by output variable values.
• Retroactive indexing: Runs created before Appian 26.10 do not have input variable values indexed. Only runs created after upgrading to Appian 26.10 are searchable by input variable content.

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. The AI agent dispatches all parallel calls at the same time, waits for every call to complete, then sends the combined results back to the AI model for the next reasoning step.

Each tool records its own start and completion time, so the reported duration reflects the individual tool rather than the whole batch. In the Build tab test panel, this per-tool timing lets you see how long each tool took and distinguish parallel from sequential execution. Progressive display in the test panel—where each tool result appears as its tool completes—changes only what you see while the run is in progress. It does not change how the run executes: the run still waits for all parallel calls to complete before the next reasoning step. For the test panel display, see Parallel tool call display in the run stream.

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.

Per-tool timing and usage

Each tool call records its own duration, so you can identify which tool in a parallel batch is slow. Expand a tool call card in the test panel to see the duration broken into reasoning time, execution time, and total duration. A per-tool AI action breakdown is not available, because AI action usage is calculated per request, not per tool.

Stop a chat agent response

End users and developers can stop a running chat agent response immediately using the stop button. Stopping is an interrupt—it ends the current response without destroying the run or ending the conversation.

Stop behavior

When you click stop, the following happens:

• Scope: Stopping ends the current response only. The agent run survives with status "Cancelled by User." The user can continue the conversation by sending a new message.
• Mid-tool-call handling: If you click stop while a tool is executing, the tool call is interrupted and does not complete. The conversation state reflects where the agent stopped.
• Session continuity: After stopping, the conversation continues in the same session with full context from prior exchanges.
• Monitor visibility: Stopped runs appear in the Monitor tab with status "Cancelled by User." For details, see Monitor AI Agents.

Model and provider selection

AI agents use the model and provider configured by the developer in the Advanced tab of the AI agent object. Model selection determines which AI model powers the agent at runtime and how Appian behaves when a model is unavailable.

For step-by-step configuration instructions, see Select a Model and Provider. For the UI element reference, see AI Agent Screen Reference.

Provider and model configuration

Developers choose a cloud provider and either Auto or a specific model in the Model Selection section of the Advanced tab. The system only displays models that support AI agent capabilities (tool use).

• Cloud Provider: Any cloud provider enabled in the Admin Console AI Services screen. Includes the Appian provider and any third-party cloud providers (AWS, custom) configured by your administrator.
• Model: Either Auto or a specific model from the selected provider.

Auto

When you select Auto, Appian uses the latest model from your configured cloud provider with automatic fallback. Auto ensures AI agents always use the latest capable model without requiring manual updates when models change or are deprecated.

Auto is the recommended default for most AI agents. New AI agents and existing AI agents upgraded from earlier versions are automatically set to the Appian provider with Auto.

Runtime behavior

AI agents route model requests differently depending on the configuration:

• Auto (any provider): The system uses the latest model from the configured cloud provider at execution time, with automatic fallback if the highest-priority model is unavailable.
• Specific model with a third-party cloud provider: If the selected model is unavailable, the agent run fails with an error. No fallback occurs. To gain automatic model selection for third-party cloud providers, use Auto.

The following conditions apply to all configurations:

• No cross-provider fallback: The system never switches between providers. If the configured provider's models are all unavailable, the agent run fails rather than routing to a different provider.
• Provider disabled: If the configured provider is disabled in the Admin Console, agent executions fail immediately.

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 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. For details on parallel execution behavior, concurrency limits, and error handling, see Parallel tool execution.

AI action consumption optimizations

An AI agent run reduces the number of AI actions it processes in two ways. Prompt caching reuses the unchanging part of the prompt across steps of the same run and requires no configuration. Process model tool output filtering trims the variables a process model tool returns to the agent and is optional per tool.

Automatic prompt caching

Prompt caching reuses the unchanging part of an AI agent's prompt—the agent instructions and tool definitions—across steps of a single run. After the first step, the AI provider stores this static content in a cache and serves it from the cache on later steps, so the run does not reprocess it at full cost on every step. Prompt caching reduces AI action consumption on multi-step runs, where the same instructions and tool definitions would otherwise be sent again on every step.

Prompt caching automatically applies:

• No configuration: Prompt caching requires no setup. There is no caching option to enable and no cache settings to manage when you build an AI agent.
• No change to reasoning or output: Prompt caching does not change an AI agent's reasoning, tool selection, or output. Caching affects only how the prompt is processed, not what the AI agent produces.
• Graceful degradation: If the caching service is unavailable, the run completes normally. It does not fail or return an error.

Getting the most from prompt caching

Prompt caching works best when the same AI agent handles a steady flow of requests. Appian caches the unchanging part of the prompt for a short time after each request. The exact length of this window is not guaranteed, so do not design your agent around a specific cache duration. Treat the window as short, and keep related requests close together so each one reuses the cached content at a reduced cost. Use the following practices to maximize the benefit:

• Concentrate scheduled runs in time: If an AI agent processes records on a schedule, such as nightly compliance checks or periodic queue processing, configure your process to submit the requests close together rather than spreading them across hours. For example, a nightly job that processes 200 records within about 10 minutes keeps each request close enough to the last to reuse the cached content, while the same 200 records spread evenly across the day arrive too far apart and each pays the full cost. In this example, the 10 minutes is how long the job takes to run, not how long the cache lasts.
• Keep AI agent definitions stable: The cache resets whenever you edit an AI agent's instructions, add or remove tools, or change output variables. Make edits during off-hours when possible, and avoid frequent incremental changes to a production AI agent during high-traffic periods.
• Run an AI agent once before a large scheduled job: If a large volume of AI agent work is scheduled, such as end-of-month processing, trigger a single low-stakes AI agent run immediately before the scheduled work begins. This first run pays the one-time cost of filling the cache, so the requests that follow start with the cached content already in place.
• Favor steady traffic: An AI agent that handles continuous or near-continuous traffic, such as a support queue or a process that runs every few minutes, keeps the cached content available for reuse. Each request costs less because it reuses what the previous request cached, and the cache does not expire between requests.

Filter process model tool outputs

A process model tool returns its process variables to the AI agent after the process completes. Output filtering excludes selected process variables from that result before it reaches the AI agent, which reduces the AI actions each tool result adds to the run. Output filtering is applied after the process completes and before the result is sent to the AI agent. It applies to both successful and failed AI agent runs. Output filtering does not change how the AI agent runs—the process model executes identically whether or not filtering is on.

Output filtering is opt-in and is configured on each process model tool. Two AI agents that use the same process model can filter its outputs differently. For the configuration steps, see Filter process model tool outputs.

The Exclude input parameters and hidden variables from output setting excludes both of the following categories of process variables from a process model tool's results:

• Input parameters—process variables where Parameter? is set to Yes on the process model.
• Hidden variables—process variables where Hidden is set to Yes on the process model.

Output filtering reduces AI action consumption most on multi-step runs. A process model tool's result carries forward into every later step of that run, so the AI agent processes it again and again until the run ends. Trimming the result once removes that repeated cost from every step that follows.

When output filtering removes every variable from a tool's result—for example, when a process model only writes data and has no non-parameter outputs—the AI agent still receives a short message confirming whether the process completed or failed, instead of an empty result.

Output filtering has the following limitations:

• Output filtering applies to process model tools only. It does not apply to expression rule tools or other tool types.
• Filtered values are not preserved anywhere downstream. A value excluded from a tool result does not appear in the Test or Monitor tab, even when you expand the tool call card for details.

Output filtering and prompt caching are independent and compound. Prompt caching reduces the cost of the unchanging part of the prompt; output filtering reduces what a process model tool generates in the first place. A process model tool that returns a smaller result still benefits from prompt caching on the AI actions that remain.

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 can target two levels:

• Run level: Feedback rates the overall outcome of an entire AI agent run. Run-level feedback contributes to the Overall Accuracy metric in the Evaluate tab.
• Tool-call level: Feedback rates an individual tool call, whether it ran sequentially or as part of a parallel batch. Tool-call feedback is associated with the specific tool call, not the whole run.

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.

Feedback