Execute AI Agent Smart Service

The Execute AI Agent smart service allows you to run a configured AI agent from within a process model, enabling you to seamlessly integrate generative AI capabilities into your automated workflows. Use this smart service to pass data to the agent and receive structured output.

Properties

The Execute AI Agent smart service is configured using the following properties.

Setup tab

The Setup tab is where you select which AI agent the node runs. Use the type-ahead picker to search for and select an agent object directly.

• Agent: A type-ahead field that lists all of the agents you have access to, ordered alphabetically. Search by name to filter the list. Selecting an agent populates the Data tab with that agent's inputs and outputs.

  Note:  If you select an agent that isn't a process agent, an error appears. If an agent you expect to see does not appear in the list, you may not have access to it. See Security for how access is determined.

Data tab

The Data tab contains all the configuration options for running your AI agent. Use the Inputs tab to provide data the agent needs, and the Outputs tab to capture the results returned by the agent. The inputs and outputs shown on this tab are generated automatically from the agent you select on the Setup tab.

Inputs

The Inputs tab shows one individually typed node input for each input variable defined in the selected AI agent's configuration, plus one optional input for AI Action cost attribution.

• [Agent input variables]: Each input variable defined in the AI agent's configuration appears as its own node input, using the name and data type configured on the agent object. Provide a value for each required input.
• Usage Groups (List of Group): An optional input that associates this execution with one or more Appian groups for AI Action cost attribution. The system validates that each group exists. If you leave this input empty, the execution defaults to an empty list.

Outputs

The Outputs tab shows one individually typed node output for each output variable defined in the selected AI agent's configuration, plus five built-in outputs for execution status, cost tracking, and error handling.

• [Agent output variables]: Each output variable defined in the AI agent's configuration appears as its own node output, using the name and data type configured on the agent object. You do not need to index into a map to retrieve individual values.
• Success (Boolean): Returns true if the AI agent run completed successfully, or false if it did not. Use this output to branch process logic on run outcomes.
• Error Message (Text): The error message from the run, when applicable. This output can surface errors from the model, the agent service, an AI guardrail, or a tool the agent called.
• Run Summary (Text): The text of the agent's final assistant message. On a successful run, this is the agent's final response.
• Run ID (Integer): A unique identifier for the AI agent run. Use this ID to track and reference specific agent runs for monitoring or troubleshooting purposes.
• AI Actions Consumed (Integer): The number of AI Actions consumed by this run. Use this output together with Usage Groups to track and attribute AI actions spent at the process level.

Example: Outputting a record type

You can select a record type as an AI agent output. The AI agent automatically determines which fields are relevant based on context. If you need the AI agent to populate specific fields, be sure to include them in the AI agent's instructions.

Usage considerations

• The AI agent uses its configured model and provider at runtime, not necessarily the environment default. Model and provider selection is stored on the agent design object and configured in the Advanced tab. No smart service inputs or outputs are required for model selection.
• The AI model is prompted to provide all required outputs defined in the configuration, but this is not guaranteed on every run.
• Appian does not validate whether all required outputs are present in the AI agent's response before completing the run.
• Output data types are validated. If an output value from the AI agent cannot be cast to the configured data type, the smart service will fail.
• The smart service does not support MNI execution (Multiple Node Instances)
• When AI Guardrails are enabled and a Block action triggers during an agent run, the agent receives the administrator-configured block message and proceeds with different content. The agent does not stop or fail due to a guardrail block.

Replace an existing Execute AI Agent node

Nodes created before Appian 26.8 continue to run unchanged, using the Agent UUID and Agent Inputs/Agent Outputs map configuration. Appian does not automatically migrate or upgrade these nodes.

To use the new picker-based Setup tab and Data tab configuration described in the Properties section above, drag a new Execute AI Agent node onto the canvas and configure it. You cannot convert an existing node in place. Configure the agent, inputs, and outputs on the new node, then remove the old node if you no longer need it.

Feedback