Create and Configure an AI Agent

This page walks you through the process of creating a new AI agent. By defining its goals, tools, and inputs, you can automate complex tasks and decision-making within your Appian applications. You'll learn how to define an AI agent's goals, add tools, and configure its inputs and outputs.

For foundational concepts, see About AI Agents. For best practices, see Best Practices for Designing AI Agents.

Before you begin: Prepare your tools and resources

AI agents rely on tools to take action—such as running a process, retrieving records, or calling other AI agents—and resources to provide passive context, such as record types and documents. AI agents can also use external tools hosted on MCP servers.

To ensure your AI agent runs smoothly, make sure the following are ready before you start building an AI agent.

1. Prepare process models

If your AI agent will perform actions (for example, create or update records), you'll need at least one process model configured as a tool.

• Use a clear, focused process that performs a single task without calling child processes.
• Include a record type input configured with a specific record type (not a process variable) if the AI agent needs to write to records.
• Add a Write Records node to the process model when the AI agent must create or update data.
• Avoid using multiple Write Records nodes for different record types in one process model.
• If you're using AI DocCenter, prepare a process model that calls the AIDC extraction process. You may need a lookup rule to find the appropriate extraction model key. You cannot add an AI skill directly as a tool.
• Avoid overlapping, similarly-named tools as this can confuse the AI agent.
• If your AI agent will collaborate with other AI agents, you can add those AI agents directly as tools without needing to wrap them in a process model.

2. Prepare resources and expression rules

Record types and documents are resources—passive data that gives the AI agent context but doesn't execute anything on its own. Expression rules are custom tools—they're executable on their own and don't require a separate resource.

• Record types: Add the record type as a resource, then enable the Query Records system tool so the AI agent can retrieve the data. Query Records can join data across multiple related record types automatically, without additional configuration.
• Documents and folders: Upload supported text-based files (.pdf, .docx, .csv, .txt, etc.) to Appian, then add the document or folder as a resource. Enable a system document tool, such as Read Full Document or Semantic Search on Document and Folder, so the AI agent can act on the resource.
• Expression rules: Create expression rules to store custom queries or logic. Add the expression rule as a custom tool—no separate resource is required.

Document tool considerations

AI agent system document tools are best for reading or retrieving context, not for trained extraction or classification. Keep the following in mind when preparing document resources:

• For high-accuracy extraction or classification: Use AI DocCenter models. Add a process model tool that calls the DocCenter extraction or classification process. The system document tools are not designed for this use case.
• For scanned or image-heavy documents: Enable the Query Visual Document system tool to interpret visual layout and structure.
• For spreadsheet data extraction: Enable the Query Spreadsheet system tool to return structured JSON output from Excel or CSV files.

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

3. Check access and naming

Ensure your AI agent can access its tools and that naming conventions support clear interpretation:

• Verify that the initiator of the AI agent has at least Viewer permission to all connected tools and their underlying objects.
• Use clear, descriptive tool names and input labels. For example, use budgetRequestRecord instead of record.
• Search for existing design objects before creating new tools to avoid duplicates.

4. Keep it simple

Start small by enabling only the tools the AI agent truly needs. Most AI agents perform best with fewer than 15 tools total, combining system tools, custom tools, and external tools. Once you've tested and confirmed your AI agent works well, you can always enable more tools later.

AI agents excel at cross-system orchestration. If your use case requires gathering data from multiple sources (CRM, support system, analytics platform) and taking action based on the combined context, AI agents can handle this complexity more effectively than traditional process models with complex branching logic.

Next: Create and configure an AI agent to define its goals, add tools, and set up inputs and outputs.

For more detail on tool behavior and limitations, see AI Agent Reference.

Create an AI agent

Create an AI agent that automates processes based on your instructions. To speed up configuration, you can add existing tools or build new ones directly during setup.

To create a new AI agent:

1. In the Build view, click NEW > AI Agent.
   

2. Configure the following properties:

   Property	Action
   Name	Enter a name that follows the recommended naming standard.
   Description	(Optional) Enter a brief description. This description is only used to help you identify what this AI agent does.
   Agent Type	Select the type of AI agent to create. Choose Process Agent to automate routine tasks without interruption, or Chat Agent to engage users through natural conversation as a virtual assistant.
   Tags	(Optional) Search for and select tags to apply to the object. If the tag you need doesn't exist yet, click Create New Tag to create a new tag without leaving the dialog.

3. Click CREATE.
4. Enter Instructions that give the AI agent detailed guidance to help it perform its work. You can use Markdown syntax to structure your instructions for better readability:
   • Use headers to organize instructions into logical sections.
   • Use bold text to emphasize key requirements or constraints.
   • Use bulleted lists to break down steps or conditions.
   • Use numbered lists for sequential instructions.

   The interface displays Markdown by default so that you can edit the syntax directly. Click the Preview tab when you need to see the rendered Markdown.

   Tip:  

   • Be clear and specific.
   • Describe steps or conditions the AI agent should follow.
   • Use plain language to ensure the AI agent understands the task.
   • Structure complex instructions with headers to help both you and the AI agent maintain a clear hierarchy.
5. Add tools to give your AI agent the ability to take action, and add resources to give it data to reference.
6. (Optional) In the Inputs and Outputs sections, click + ADD to define variables. Configure the following properties directly on the Build tab:
   • Enter a Name and Description.
   • Search for and select the data type. Data types can be Text, Integer, Decimal, Boolean, Date, Datetime, Time, Folder, Record Type, CDT, Map, User, and Group.
   • (Optional) Select the Is Required checkbox.

     Tip:  Mark an input or output as required if the AI agent needs it to start the task or continue the workflow.

   Note:  Input variable values are indexed for search in the Monitor tab. Developers can search the run history grid by input values to find specific AI agent runs without manually scanning each row.

7. Click SAVE AGENT.

Add tools to your AI agent

Tools give your AI agent the ability to take action, such as running a process, querying records, or calling an external service. The +ADD Tool dialog organizes tools into three sections: System Tools, Custom Tools, and External Tools. For a full description of each tool, see Tools.

Add a system tool

System tools are AI agent capabilities that Appian provides, such as the document tools and the Query Records tool. New AI agents start with zero system tools enabled.

To add a system tool to your AI agent:

1. Click +ADD Tool. The Add Tool dialog appears.
   

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

2. In the System Tools section, select the checkbox for each system tool you want to enable. To enable every system tool, select Select All.
3. Click ADD.

The enabled system tools appear as removable cards on the AI agent configuration screen. If a system tool acts on a resource—for example, Query Records acts on a record type—also add the corresponding resource.

Add a custom tool

Custom tools link your AI agent to a specific Appian design object, such as a process model, expression rule, or another AI agent.

To add a custom tool to your AI agent:

1. Click +ADD Tool.
2. In the Custom Tools section, select the design object you want the tool to use. This links the tool to the specific object the AI agent will access. The object's latest metadata automatically appears below the Tools section. You can navigate directly from a tool's configuration to its underlying design object by clicking the object's name.
   

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

3. Click ADD.

4. Repeat steps 1-3 to add multiple custom tools to the same AI agent.

   You are adding tools to a single AI agent, not creating separate AI agents for each tool. However, avoid assigning too many tools to your AI agent, as this can impact performance.

Filter process model tool outputs

By default, a process model tool returns every process variable to the AI agent after the process completes, including input parameters the agent already sent and intermediate variables the agent does not need. For a process model tool, you can filter the tool result so the AI agent receives only the variables that carry new information. Filtering lowers AI action consumption and keeps the agent's context focused. For the underlying behavior, see Filter process model tool outputs in the AI Agent Reference.

Output filtering is off by default and is configured on each process model tool, so two AI agents that use the same process model can filter differently. Filtering does not change how the process runs—it changes only what the tool returns to the AI agent.

Selecting the Exclude input parameters and hidden variables from output checkbox excludes both of the following categories of process variables from the 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.

To filter the outputs of a process model tool:

1. Add the process model as a custom tool, as described in Add a custom tool.
2. Select the Exclude input parameters and hidden variables from output checkbox.
3. Click SAVE AGENT.

Add an MCP tool

To add an MCP tool to your AI agent:

1. Click +ADD Tool.
2. Select the External Tools section.
3. Choose an MCP connected system. The available tools from the server display.
4. Select all tools or pick individual ones.
5. Click ADD.

For details on MCP tool setup and configuration, see MCP Tools for AI Agents.

Add resources to your AI agent

Resources give your AI agent passive data to reference, such as a record type, document, or document folder. 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. For a full description of each resource, see Resources.

To add a resource to your AI agent:

1. In the Resources tab, click +ADD.
2. Select a resource type: Record Type, Document, or Document Folder.
3. Select the design object for that resource type.
4. Click ADD.

If the resource requires a system tool to be usable, a tooltip on the resource card reminds you that adding a resource alone doesn't grant the AI agent the capability to act on it. For example, if you add a record type as a resource, also enable the Query Records system tool. If you add a document as a resource, also enable a system document tool such as Read Full Document or Semantic Search on Document and Folder.

Add document context

If your AI agent processes documents, add a document or document folder as a resource, then enable the system document tools your AI agent needs—including Query Visual Document and Query Spreadsheet. For details, see System document tools.

Select a model and provider

AI agents use the model you configure in the Model Selection section of the Advanced tab. By default, new agents use Auto, which uses the latest model from your default provider with automatic fallback.

To change the model:

1. In the Build view, open the AI agent and go to Build > Advanced.
2. In the Model Selection section, click the model card to open the Model Selection dialog.
3. (Optional) Use the Cloud Provider dropdown to filter by cloud provider. The admin-configured default provider is labeled "(default)".
4. (Optional) Use the Model Provider dropdown to filter by AI model provider (for example, Anthropic, OpenAI).
5. Select a model from the list, or select Auto to return to automatic model selection.
6. Click SAVE AGENT.

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

For details on runtime behavior, see AI Agent Reference. For the full UI element reference, see AI Agent Screen Reference.

Test your AI agent

After saving, test your AI agent to validate inputs, outputs, and tool interactions before deploying. The testing experience differs by agent type:

• Chat agents use a dedicated test console in the Build tab that supports conversations with follow-up messages. No SAIL interface is required.
• Process agents use the Test panel on the right side of the Build tab with a single-run model.

For best practices on designing testable AI agents, see Best Practices for Designing AI Agents.

Test a chat agent

Chat agents have a dedicated test console embedded directly in the Build tab. The test console provides a full conversational experience—send messages, view streamed responses (unless guardrails are enabled), and inspect the agent timeline—without creating a SAIL interface first.

To test a chat agent:

1. In the Build tab of the chat agent, locate the test console on the right side.
2. (Optional) If the chat agent has configured inputs, fill in the input grid that appears above the chat area, or select a saved test case to prepopulate the inputs. Inputs are passed to the agent when the first message is sent.
3. Type a message in the chat input and press Enter.
4. Review the agent's response and timeline. All debug mode features are available, including tool inputs and outputs.
5. Send follow-up messages to test conversations with follow-up messages. The chat agent maintains context across exchanges within the test session.
6. To start a fresh test, click New Test. Each test starts a new conversation—there is no session switching in the test console.

For the full test console interface reference, see Test console for chat agents.

Test a process agent

Process agents use the Test panel on the right side of the Build tab with a single-run model. Define input values, click Run Test, and review the step-by-step results.

Parallel tool calls

AI agents can execute multiple independent tool calls in parallel within a single reasoning step. Parallel tool calls are enabled by default.

When parallel tool calls are enabled:

• Automatic system prompt guidance: The system prompt encourages the AI agent to execute independent tool calls concurrently. You do not need to add explicit parallel instructions to your prompt.
• Progressive results in the Test panel: Parallel tool call results appear one at a time as each tool completes, so you can review early results while slower tools are still running. Each tool call displays its own card, each card shows the tool's own duration when it completes, and you can click a card to view results or error messages.
• No configuration required: Developers do not need to change AI agent configurations to benefit from parallel execution. The AI agent determines when tool calls are independent and groups them automatically.

For parallel execution constraints and error handling, see Parallel tool execution.

The Test panel has two explicit states: Empty/Ready and Running/Result.

Load a test case or enter inputs (Empty/Ready state)

The Test panel starts in the Empty/Ready state. In the Empty/Ready state, you can load an existing test case or provide new input values.

To set up a test:

1. (Optional) If you have saved test cases, select one from the Load Test Case dropdown at the top of the Test panel.
2. Configure any Inputs needed for additional context.
3. Click RUN TEST. The Run Test button is disabled when unsaved configuration changes exist. Save your AI agent configuration before running a test.

Review results (Running/Result state)

After you click Run Test, the Test panel transitions to the Running/Result state. The Running/Result state displays a summary of the AI agent's activity and a detailed step-by-step history of how it processed the request.

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

Tool execution details and agent output variables render Markdown by default. Each output surface includes a tab to switch between the rendered view and the raw text. Use the raw view to inspect the underlying syntax when rendered output looks incorrect.

You can review the history of each step the AI agent executed. Click a step to expand its details and learn what happened in that part of the process.

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

When the AI agent runs tool calls in parallel, each tool result appears on its own card as soon as that tool completes, so you can review early results while slower tools are still running. Each card shows the tool's own duration. For details on the parallel display, see Parallel tool call display in the run stream.

To rate a specific tool call, click the feedback control on that tool's card. You can rate a single tool call whether it ran sequentially or as part of a parallel batch. For the full feedback workflow, see Developer feedback.

Start a new test

After reviewing results, click New Test to reset the Test panel to the Empty/Ready state. The New Test button clears the previous results and input values so you can run a fresh test.

Version-aware test behavior

Saving a new version of your AI agent clears the Test panel to the Empty/Ready state. If a test is currently running when you save, the running test completes but the results are discarded when the panel resets. The previous test run belonged to the prior version and is no longer relevant to the updated configuration.

Configure test inputs

The Test panel provides flexible options for defining input values. You can use simple form-based inputs or write expressions for complex data types.

Input modes

Each input variable supports the following data types:

• Boolean.
• Date.
• Datetime.
• Decimal.
• Folder.
• Group.
• Integer.
• Text.
• Time.
• User.

Expression mode

For complex data types like Record Type, CDT, and Map, you must use expression mode. For simpler types, you can toggle between form-based input and expression mode. Expression mode supports all input data types: Boolean, Date, Datetime, Decimal, Folder, Group, Integer, Text, Time, User, Record Type, CDT, and Map.

When you use expression mode:

• Write any valid expression to define the input's test value.
• The expression editor validates your syntax in real-time and displays any errors inline.
• You can preview the evaluated result before running the test.
• When you save a test case, the system saves the expression itself, not just the resulting value.
• When you load a saved test case, the expression editor repopulates with the saved expression, allowing you to modify and reuse it.
• Variant types are not supported.

Stop a running AI agent

You can manually stop an AI agent while it's running to save time and resources when you notice it's heading off-track or consuming unnecessary AI actions.

Process agents: To stop a running process agent, click Stop in the Test panel while the AI agent is running or in a processing state.

Result: The AI agent run status immediately updates to "User Cancellation Pending". If a tool is executing when you click Stop, the tool completes before the AI agent stops. After the running tool completes, the AI agent stops and does not proceed to any subsequent LLM calls or steps. The final status becomes "User Canceled".

Chat agents: To stop a running chat agent response, click the stop button that appears during an active response. The stop button ends the current response only—it does not end the conversation. If a tool is executing when you click stop, the tool call is interrupted and does not complete. After stopping, send a new message to continue the conversation. Stopped runs appear in the Monitor tab with status "Cancelled by User." For details, see Stop button.

Next steps

After creating and testing your AI agent, you can:

• Integrate it into your applications by using it in process models.
• Deploy it to other environments using Deploy AI Agents Between Environments.
• Track performance over time using the Monitor tab.

For troubleshooting common issues, see Troubleshooting AI Agents.

Feedback