Deploy AI Agents Between Environments

Deploying AI agents from a development environment to testing and production follows the same import/export process as other Appian design objects. This page explains what moves between environments, what you need to prepare, and how to validate your AI agents after deployment.

Keep this key point in mind when deploying AI agents:

• An AI agent's configuration and behavior move with the object. The tools it uses (like process models, rules, records, documents, and folders) do not and must be present and accessible in the target environment.
• AI agents don't retrain after deployment. Their reliability comes from good prompts, well-scoped tools, and iterative testing and monitoring.

What moves

The following table details which parts of an AI agent move during deployment and what you need to ensure is present in the target environment.

Element	Deployment behavior	Details
AI agent configuration	Moves	This includes Instructions, configured Inputs and Outputs, and the list of assigned Tools.
Model and provider selection	Moves	The configured provider and model are stored as part of the AI agent configuration. The target environment must have the configured provider enabled and model available. See Import validation for model selection.
Tools (Process, AI Agent, Record Type, Rule, Document, Folder)	Must exist in target environment	Tools are separate design objects. Deploy them (and their dependencies) to the target environment and ensure AI agent initiators have access. Child AI agents configured as tools are displayed as precedents for the parent AI agent, and the parent AI agent is displayed as a dependent for each associated child agent. Standard impact analysis and delete checks will apply.
MCP connected systems	Must exist in target environment	If your AI agent uses MCP tools, include the MCP connected system in your deployment package. Verify that the MCP server URL and credentials are valid in the target environment.

Versioning

Each time you save, you create a new AI agent version. You can use the version history to track changes, compare behavior across releases, and revert if needed. When you deploy an AI agent, you move the latest version of its configuration.

Before you deploy

To prepare your AI agent for deployment, follow these steps:

1. Package dependencies:
   • Include the process models, expression rules, decisions, record types, documents, and folders referenced by the AI agent's tools.
   • Remove any overlapping or duplicate tools to reduce ambiguity. For example, if you have both a "Get Customer Data" rule and a "Customer Info" record type that return similar information, choose one.
2. Verify security:
   • Confirm the initiator (the user or calling process) in the target environment has the necessary permissions to every tool the AI agent may call. For example, the initiator needs Viewer access to record types, Initiator access to process models, and Editor access to documents.
3. Align inputs and outputs:
   • Keep input and output names clear and consistent with the objects that will use them, such as process variables, interfaces, or records.

Deploy between environments

To deploy an AI agent, follow these steps:

1. Export the AI agent (and its required tools) from the source environment using Appian's standard export process.
2. Import the package into the target environment.
3. Resolve dependencies:
   • Map any environment-specific references if needed, for example, hierarchy folders, groups, or constants.
   • Confirm the underlying design objects kept their expected UUIDs, or update tool links if you deliberately created new objects in the target environment.
4. Save and publish the imported AI agent.

Import validation for model selection

When you import an AI agent, Appian validates that the target environment supports the AI agent's configured model and provider. Import validation prevents AI agents from silently failing at runtime due to missing model configurations.

The following validation rules apply during import:

• Provider enabled and model available: Import succeeds. The AI agent runs with its configured model in the target environment.
• Provider disabled in target environment: Import fails. The administrator must enable the provider in the target environment's AI Services screen before re-importing.
• Provider enabled but specific model not available: Import fails. The administrator must enable the required model in the target environment, or the developer must select a different model and re-export.
• Unrecognized model ID: Import fails. This can occur when a model has been deprecated or removed from the provider.
• Auto with provider enabled: Import succeeds. Auto only validates that the provider is enabled—it trusts the runtime to select an available model.

When import fails due to a model validation error, the error message indicates which model must be enabled.

For details on how administrators configure models and providers, see AI Services.

Validate after deployment

After deployment, it's important to validate the AI agent's behavior:

1. Run saved test cases in the AI agent's Build tab to confirm that the inputs, tool calls, and outputs behave as expected in the new environment.
2. Monitor initial runs in the Monitor tab. Review the request status, tool-call counts, duration, and any errors.

For detailed testing and monitoring guidance, see Monitor AI Agents. For troubleshooting deployment issues, see Troubleshooting AI Agents.

Common validation checks

Here are some common items to check during validation:

• Permissions: The initiator can access all tools the AI agent may invoke.
• Process tools: Long-running nodes have sensible timeouts and error handling.
• Rule tools: Guard against nulls, and unit-test with the same inputs the AI agent uses.
• Record queries: Target a single record type. Move aggregations or joins into rules.
• Document tools: Provide text-based, supported files, and avoid scanned or image-only PDFs.

Learning and model behavior

• No automatic retraining: AI agents do not automatically learn or retrain on deployment. Their performance depends on the LLM configured by the platform, your prompt, and the tools you provide.
• Refine via iteration: Use structured testing and monitoring to improve AI agent behavior. You can adjust prompts, refine which tools are available to the AI agent, and modify inputs or outputs as you observe the results.

Make available through MCP

You can make an AI agent available as a Model Context Protocol (MCP) tool on Appian MCP Server. When enabled, external AI applications can send a prompt to your Appian AI agent and receive its response through natural language requests.

To make an AI agent available as an MCP tool:

1. Open the AI agent in Appian Designer.
2. Open the AI agent's properties dialog.
3. Select Make available as MCP tool.
4. Click SAVE.

Security for MCP tools

Appian MCP Server enforces the same object security and group membership as the Appian platform. The service account must be on the role map with at least Viewer access for the AI agent and all of its underlying tools for it to appear as an available MCP tool.

Limitations for MCP tools

The following limitations apply to AI agents used as Model Context Protocol (MCP) tools:

• Single-turn interaction only. MCP invocations are single-turn. The external AI application sends one prompt and receives one response. Multi-turn conversations are not supported through MCP.
• Context limitations. The AI agent receives only the prompt provided by the external AI application. Context from the user's conversation in the external AI application is not automatically passed to the Appian AI agent.

For the full developer guide, see Make Design Objects Available as MCP Tools.

Feedback