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 actions

AI agents rely on existing Appian design objects—called tools—to access data, trigger processes, call other AI agents, or retrieve context. 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 record types, rules, or documents

If your AI agent will retrieve or reference data, prepare tools that provide structured or contextual information:

• Record types: The AI agent can only query one record type at a time. Related or aggregated queries must be handled in an expression rule.
• Expression rules: Create expression rules to store custom queries or logic.
• Documents and Folders: Upload supported text-based files (.pdf, .docx, .csv, .txt, etc.) to Appian. For guidance on choosing the right document strategy for your use case, 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 assigning only the tools the AI agent truly needs. Most AI agents perform best with fewer than 15 tools. Once you've tested and confirmed your AI agent works well, you can always add 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 add a new AI agent:

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

2. Configure the following properties:

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

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. Click ADD TOOL. The Add Tool screen appears.
   

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

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

   To add an MCP tool, select the External Tools tab, then choose an MCP connected system. The available tools from the server display. Select all tools or pick individual ones. For details, see MCP Tools for AI Agents.

   Tip:  Use MCP tools when the capability you need already exists on an external MCP server. Use native Appian tools when you need to interact with the data fabric, execute Appian-specific business logic, or need deterministic behavior.

7. Click Create.

8. Repeat steps 4-6 to add multiple 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.

9. (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, 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.

10. Click SAVE AGENT.

Test your AI agent

After saving, test your AI agent in the Test panel on the right side of the Build tab. Testing helps you validate inputs, outputs, and tool interactions before deploying.

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

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.
• Test pane display: Parallel tool calls appear as a grouped set within a single step in the Test panel. Each concurrent call displays its own card, and you can click individual cards 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

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. 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, CDT, and Map, you must use expression mode. For simpler types, you can toggle between form-based input and expression mode.

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.

To stop a running AI 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".

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