AI Agent Screen Reference

Appian Designer provides a streamlined screen for creating, managing, and optimizing your AI agents. Use this screen to configure AI agent behavior, test functionality, and monitor performance. This reference explains each interface element and its purpose.

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

Create AI Agent dialog

When you click NEW > AI Agent in the Build view, the Create AI Agent dialog appears. The dialog includes the following fields:

Field	Description
Name	The name of the AI agent.
Description	An optional description to help identify the AI agent's purpose.
Agent Type	The type of AI agent to create. Choose Process Agent to automate routine tasks without interruption within a process model, or Chat Agent to engage users through natural conversation in an interface. Agent type cannot be changed after creation.

After you click CREATE, the AI agent opens in the Build tab where you configure its instructions, tools, inputs, and outputs.

Tabs

The screen includes these main tabs that organize your work.

• Build
• Monitor

Build

The Build tab provides a unified workspace for creating, configuring, and testing AI agents. The interface uses a split-pane layout with the Configure panel on the left and the Test panel on the right. This layout lets you view your AI agent's complete configuration alongside step-by-step test results in a single workspace.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Configure panel layout

The Configure panel organizes AI agent settings into two main areas:

• Instructions field: This field occupies the top of the Configure panel. The Instructions field includes an internal scrollbar for long text and remains visible at all times, even when you work with tools, inputs, or outputs in the tabbed section below it.
• Tabbed container: This container sits below the Instructions field and holds the Tools, Inputs, and Outputs sections. To define properties, click the + button in each tab to open a modal.

Markdown rendering in the Build tab

The Instructions field supports Markdown formatting to help you structure and style your content. The Instructions field displays raw Markdown syntax by default to allow for immediate editing. To see how the rendered Markdown displays, click the Preview tab.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Test panel states

The Test panel operates in two states depending on whether a test is running. The Test panel applies to process agents. For chat agents, see Test console for chat agents.

Empty/Ready state

The Test panel displays the Empty/Ready state when no test is running and no results are loaded. The Empty/Ready state includes:

• Load Test Case dropdown, prominently displayed at the top of the panel.
• Clear Input Values button to reset all input fields.
• Auto-generated input fields based on the AI agent's configured inputs.
• Run Test button. You cannot run tests while unsaved configuration changes exist.

Running/Result state

The Test panel displays the Running/Result state after you click Run Test. The Running/Result state includes:

• Inputs used (read-only), showing the input values at the time the test started.
• Step-by-step tool calls and the AI agent's thinking process. Parallel tool results stream in as each tool finishes, rather than appearing together after the whole batch completes.
• Final outputs with Markdown rendering.
• Stop button for canceling the running AI agent.
• Save as Test Case button to preserve the configuration for reuse.
• New Test button to reset the Test panel back to the Empty/Ready state.

Parallel tool call display in the run stream

When the AI agent executes multiple tool calls in parallel, the live test panel displays each tool call as its own card and updates each card independently as its tool completes. The parallel tool call display includes:

• Grouped step: All concurrent tool calls share the same step ID and appear together as one step in the run stream.
• Progressive results: Each card populates and transitions from running to completed the moment its own tool finishes, in completion order. A finished tool shows a completed state while slower tools in the batch keep running, and you can expand its card for details without waiting for the rest.
• "Parallel" tag and duration badge: Each card shows a Parallel tag while its tool runs. On completion, the tag is replaced by a duration badge that shows the tool's total duration, such as "5s". Expand the card to see the full duration breakdown.
• Agent reasoning before the batch: The AI agent's reasoning text appears once, before the batch, explaining why it ran the tools in parallel.
• Individual card interaction: Click any tool call card in the group to view its results or error messages.

Sequential tool calls display no Parallel tag. Progressive results and the Parallel tag apply to the live test panel run stream only. Non-streaming views, such as the Monitor tab run details, show tool results after the full batch completes. For parallel execution constraints, see Parallel tool execution.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Tool call card details

Expand a tool call card to view the full execution data for that tool call:

• Tool name: The name of the tool the AI agent called.
• Tool UUID: The unique identifier for the tool call.
• Reasoning: Why the AI agent chose to call this tool.
• Inputs and outputs: The values the AI agent passed to the tool and the values the tool returned.
• Duration: A breakdown of how long the tool call took, split into Reasoning (time the AI agent spent deciding to call the tool), Execution (time the tool spent running), and Total Duration (the sum of the two).

Each tool call card shows its own data, so a card in a parallel batch reports timing for that individual tool rather than the whole batch.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Configure panel (left)

The Configure panel lets you view, create, and manage AI agent settings including instructions, inputs, outputs, and tools.

Test panel (right)

The Test panel lets you validate your AI agent's behavior by providing input values and observing how your AI agent responds. The Test panel supports simple form fields for basic data types or expressions for complex types like records, CDTs, and maps. The Load Test Case dropdown allows you to quickly reuse saved test configurations. When you save a test case, the expressions are also saved, so you can reuse and modify them in future tests.

If you configure an input as an array using the Array (multiple values) checkbox, you must use constant or expression options to define your test lists. Static values are not available for array inputs.

The side-by-side layout of the Configure and Test panels eliminates the need to switch between separate views, creating a more direct feedback loop for building and refining AI agents. For step-by-step guidance, see Create and Configure an AI Agent and Monitor AI Agents.

Advanced

The Advanced tab contains a Model Selection section where you configure which AI model and provider powers your AI agent. New agents default to Auto, which uses the latest model from the configured provider with automatic fallback.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Test console for chat agents

Chat agents have a dedicated test console embedded in the Build tab that lets developers test conversational interactions without creating a SAIL interface first. The test console provides a full chat experience—send messages, view streamed responses, and inspect the agent timeline—all within the AI agent design object.

Test console behavior:

• Conversations with follow-up messages: The test console maintains conversation context across multiple messages within a test session. Developers can send follow-up messages and the chat agent responds with awareness of prior conversations.
• Fresh conversation per test: Each test starts a fresh conversation. The test console does not provide session switching.
• Excluded from session picker: Test sessions created from the AI agent object configuration are excluded from the a!agentChatField() session picker in production interfaces. End users do not see developer test sessions.
• Debug mode: All debug mode features are available in the test console, including tool inputs and outputs and the agent timeline.
• Inputs: If the chat agent has configured inputs, an input grid appears before the first message. Inputs are passed to the agent via the inputs parameter, following the same pattern as process agents.

How the chat agent test console differs from the process agent Test panel:

Capability	Chat agent test console	Process agent Test panel
Interaction model	Conversational chat with follow-up messages	Single run with defined inputs and outputs
User input during run	Users send follow-up messages between responses	No mid-run interaction
Session management	Fresh conversation per test, no session switching	Load Test Case dropdown for saved configurations
Timeline	Inline timeline per response	Step-by-step run history

Monitor

The Monitor tab lets you track how AI agents are performing over time. The Monitor tab displays key metrics for each AI agent, including the AI agent run status, number of tool calls, successful completions, and average run duration. These metrics help you measure efficiency, spot trends, and identify areas for improvement.

The run history uses a timeline layout that displays each step chronologically, including tool calls, AI agent reasoning, and outputs. The timeline replaces the previous card-based display and provides a clearer view of how the AI agent processed each request.

Stop status in run history

Runs stopped by a user or developer display with the status "Cancelled by User" in the Monitor tab. The "Cancelled by User" status indicates that someone clicked the stop button during an active agent response. The stopped run is preserved—it is not deleted—and the conversation can continue after stopping.

The run detail view accessed from the Monitor tab also includes a Stop button for canceling active AI agent runs. For monitoring best practices, see Monitor AI Agents.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Inputs and outputs

Inputs and outputs define the data your AI agent receives and returns. Configure inputs and outputs directly in the Inputs and Outputs sections of the Configure panel on the Build tab. When configuring these variables, specify whether each variable accepts a single value or multiple values.

Array (multiple values)

The Array (multiple values) checkbox lets input or output variables accept or return a list of values instead of a single value. Selecting the Array (multiple values) checkbox changes the variable signature from a single data type to a list of that data type.

For example:

• A Document input without the checkbox accepts one document.
• A Document input with the checkbox accepts a list of documents.

The array capability lets you pass multiple items directly to your AI agent or receive structured lists as outputs without building complex looping logic. The AI agent screen formats list values for better readability.

Tools

Tools are executable actions that let the AI agent take an action, such as running a process, retrieving records, or calling an external service. The +ADD Tool dialog organizes tools into three sections: System Tools, Custom Tools, and External Tools.

System tools

System tools are AI agent capabilities that Appian provides. Unlike custom tools, system tools don't require you to create a process model or expression rule. New AI agents start with zero system tools enabled—you must add each system tool explicitly.

Tool	Description
Query Visual Document	Evaluates both text and visual elements in scanned or image-heavy documents, interpreting layout, hierarchy, and spatial relationships.
Query Spreadsheet	Extracts structured data from spreadsheet files (XLS, XLSX, XLSM, CSV), always returning JSON output.
Query Document (Text)	Executes dynamic prompts against document content for text-based extraction or summarization.
Smart Search on Document and Folder	Finds specific information across multiple documents in a folder by searching for relevant content using natural language queries.
Read Full Document	Loads the entire document text into the AI agent's context for deep reasoning across sections.
Query Records	Queries synced record types with a!queryRecordType(). Supports filtering, sorting, and aggregating data, but not record type relationships. Use for straightforward retrieval of record data.
SQL Query Records	Queries synced record types with SQL. Supports filtering, sorting, aggregation, and joining data across record types. Can't query record types that use record-level security expressions. Use for advanced queries, like multi-step aggregations or custom joins. If both Query Records and SQL Query Records are enabled, the agent will prefer SQL Query Records and fall back to Query Records.

Enabling a system tool does not, by itself, give the AI agent data to act on. If a system tool acts on a resource—for example, Query Records acts on a record type, and Read Full Document acts on a document—you must also add the corresponding resource. See Resources.

For detailed guidance on how your AI agent selects among enabled document tools, see Working with Documents in AI Agents.

Custom tools

Custom tools are Appian design objects that you configure to give the AI agent a specific capability.

Tool	Description
Process Model	Starts a process model in Appian to perform a series of predefined tasks or workflows.
Expression Rule	Uses expression rules or decisions to provide logic or data.
AI Agent	Collaborates with another AI agent to complete a task, providing a way to orchestrate a modular, multi-agent workflow.

External tools

External tools connect the AI agent to services outside Appian.

Tool	Description
MCP Server	Connects to an external MCP server to give the AI agent access to third-party tools. When you select this option, you choose an MCP connected system, then select specific tools from that server.

Resources

Resources are passive data objects that give the AI agent context. Unlike tools, resources don't execute actions on their own. You must also enable a corresponding system tool so the AI agent can act on the resource.

Resource	Description
Record Type	Gives the AI agent access to data in a record type. Enable the Query Records system tool so the AI agent can retrieve this data.
Document	Provides the AI agent with context from a single document. Enable a system document tool, such as Read Full Document or Semantic Search on Document and Folder, so the AI agent can read or search this document.
Document Folder	Gives the AI agent access to multiple documents stored in a folder. Enable a system document tool so the AI agent can search or read the folder's contents.

System document tools

System document tools are the system tools that handle document reading, visual analysis, spreadsheet extraction, and semantic search.

Available system document tools

The following system document tools are available to AI agents:

Tool	Description
Query Document (Text)	Executes dynamic prompts against document content for text-based extraction or summarization.
Query Visual Document	Evaluates both text and visual elements in scanned or image-heavy documents, interpreting layout, hierarchy, and spatial relationships.
Query Spreadsheet	Extracts structured data from spreadsheet files (XLS, XLSX, XLSM, CSV), always returning JSON output.
Read Full Document	Loads the entire document text into the AI agent's context for deep reasoning across sections.
Semantic Search on Document and Folder	Finds specific information across multiple documents in a folder by searching for relevant content using natural language queries.

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

How system document tools appear in the interface

System document tools do not activate automatically. Each system document tool appears as a selectable card in the System Tools section of the +ADD Tool dialog. You select one or more tools using individual checkboxes, or select Select All to enable every system tool, then click ADD. Enabled system document tools appear as removable cards on the AI agent configuration screen, the same as custom tools.

Once enabled, the AI agent selects among the enabled system document tools based on the task and your instructions. For step-by-step instructions, see Add a system tool. For guidance on tool selection behavior, see Working with Documents in AI Agents.

Developer feedback

Developer feedback allows you to rate AI agent outputs directly within evaluation results. Feedback captures structured quality judgments on the overall AI agent run and on individual tool calls.

Feedback controls

Developer feedback appears on each test result in the Evaluate tab drill-down view and in the Test panel after a run completes. A feedback control also appears on each individual tool call card. The feedback includes the following elements:

Element	Description
Thumbs up / Thumbs down	A binary quality judgment on the AI agent run. Required to submit feedback. Positive feedback (thumbs up) marks the run as a strong example for future reference.
What went wrong checkboxes	Optional checkboxes that identify the type of failure. Available options: "Wrong output", "Made up information", "Too many steps", "Got stuck", "Took too long", "Failed to recover from error", "Other". Select up to five. Appears after thumbs-down.
Free-text comment	An optional text field for additional context about the rating.

Feedback targets

Developer feedback can target either the whole run or a single tool call:

• The whole run: Feedback targets the overall outcome of the entire AI agent run, including whether the final output meets expectations.
• An individual tool call: You can submit feedback on a single tool call from that tool's card, including a tool that ran as part of a parallel batch. Per-tool feedback is associated with the specific tool call, not the whole run, so feedback on one tool does not affect the other tools in a batch.

Strong examples

When you give a thumbs-up rating, the AI agent run is automatically marked as an ideal outcome. Strong examples create a library of reference outputs.

Feedback