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.

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.

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

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

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

6. Click Create.

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

8. (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.

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

To test your AI agent:

1. In the Test panel, configure any Inputs needed for additional context. You can use the Load Test Case dropdown to quickly reuse saved test configurations.
2. Click RUN TEST. The test results display 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

You can review the history of each step the AI agent executed. Click See Details under each step to learn what happened in that part of the process.

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

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 at the top of the screen while the AI agent is running or in a processing state.

Result: The agent run status immediately updates to "User Cancellation Pending". If a tool is currently 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