The AI Workflow Agent is an automation action that sends record data and files to an AI model and returns the answer for later steps. You write the prompt, choose the connection and decide the shape of the output.

Later actions can then write the answer into fields, send it by email or use it in conditions.

Example: when a vendor submits its security questionnaire, an automation runs the AI Workflow Agent on the record. It returns a Priority (High, Medium or Low) and a Review Due Date. An Update Record action writes both into the vendor's record.

Plan Availability	All plan types.
Permissions	Workspace Administrators set up AI connections in AI Control Center > Providers and Models. Administrators and Solution Managers add the action to automations.
Platform	Web
Related Reading	AI Workflow Agent: map the output and troubleshoot a run AI Control Center: Providers and Models Automation Actions explained Automation Limits.

My AI Workflow Agent step did not work: check these six things, in order

Administrators and Solution Managers edit the automation. Workspace Administrators manage the AI connections. If you have neither role, send this page and the automation name to one of them.

Prompt is invalid. The prompt is empty, or a required field is missing. Add the fields and write the prompt.
No active connection. An Administrator sets up the connection in AI Control Center and allows it for this solution and feature. See AI Control Center: Providers and Models.
The output does not fit. The Custom output type must match the field you map it to. See AI Workflow Agent: map the output and troubleshoot a run.
A Single Select value. The answer must match one of the target field's options exactly.
An object with no keys. An object needs at least one key. Objects without keys are dropped from the output.
The model cannot read the file. Some models do not take attachments or large data. See AI Platforms and Models.

Still stuck: open the chat button in the lower-right corner of SmartSuite and select Send a message. Include the automation name, the run time from Run History and the exact message.

Adding the action

Choose a trigger. It decides when the automation runs and which record it uses, such as When a Record is Created.
Add an action. Under Integrations, choose AI Workflow Agent.
Choose a connection.

Connections

The action needs an active AI connection. Administrators set connections up once in Workspace Administration > AI Control Center > Providers and Models. Each can serve many solutions and both AI agents.

Every workspace also has a SmartSuite Trial Connection with 100 free requests and no API key.

A connection allowed for a solution and feature shows for anyone who sets up the action there. Nobody re-enters a key for each automation. The steps to add one are in AI Control Center: Providers and Models.

Note: An Administrator can remove a connection at any time. SmartSuite warns first if automations use it.

Prompt

Mix plain text with values from the trigger or earlier steps. You can use:

Fields from a single record, such as Trigger: Questionnaire Answers.
Fields from several records, such as Find Findings: Severity.
Attachments and fields that hold several values.

To insert a field:

Select the blue + at the right of the Prompt box.
Pick a field from the list. To use another source, select the back arrow (<) at the top left, then the trigger or an earlier action.
Pick the field to insert.

The prompt text and the inserted values are sent to the model.

Example prompts:

Translate Trigger: Product Description to Italian.
Calculate the average of Action: Order Amount for the current month.

A longer prompt, for the policy team:

Respond as a corporate compliance expert. Evaluate this policy and recommend updates based on industry best practices. Policy: Policy Name. Purpose: Policy Purpose. Scope: Policy Scope. Statement: Policy Statement.

Here each field name stands for an inserted field.

Attachments

Select the blue + in the Attachments box.
Choose where the file comes from: a field from the trigger, a field from another action, or a file you upload.

SmartSuite sends the file to the model if the model takes files. Mention the file in your prompt.

Output

Choose how the answer comes back.

Simple: raw text, treated as a multi-line Text Area. Best for free-form answers.
Custom: named values with types, for later steps to use in fields and conditions.

To build a Custom output:

In the Output section, select the Custom tab.
Select Add Output.
Give each value a Name, a Type and, if you like, an Instruction that tells the model how to format it.

A Custom output can return a single value, a list of values, a JSON object or a list of JSON objects. Each value can be Text, Number, Yes/No, Date, Time, Date & Time, Email, URL, Phone, Single Select or Duration.

With Custom output, SmartSuite adds a system prompt that asks the model for JSON.

Warning: A Single Select value must match one of the target field's options exactly. If the field accepts Open, In Progress and Closed, the model must return one of those words as written.

Objects need keys

A JSON object needs at least one key in its structure. A description alone does not create a key. An object with no keys is dropped and never reaches later steps.

Example: a JSON object

{
    "Response Format": {
        "Type": "Object",
        "Name": "Response",
        "Properties": [
            {
                "Name": "Priority",
                "Type": "Single Select",
                "Instruction": "One of the following: High, Medium, Low"
            },
            {
                "Name": "Due Date",
                "Type": "Date",
                "Instruction": "Return in YYYY-MM-DD format"
            }
        ]
    }
}

Example: a list

{
    "Response Format": {
        "Type": "List",
        "Name": "Top Customers",
        "List Item": "String",
        "Instruction": "Return the top 5 customer names as an array"
    }
}

Formatting tips

Dates and times: ask for ISO 8601 so SmartSuite reads them.
Single Select: match the option exactly, including case and spelling.
Phone numbers: ask for one format, such as +1 (123) 456-7890.
Lists: ask for each item as an array entry, not a comma-separated string.

Instructions such as "Return in YYYY-MM-DD format." shape the answer but are not part of the output.

Using the output in later steps

Custom outputs are checked when you set them up and in test runs. They appear as variable pills in later steps and can be mapped into fields whose type matches. A mismatch shows a configuration error.

Use the output in:

Create, Update or Delete Record.
Send Email.
Find Records.
Conditional branching.
Looping.

In the vendor example, Update Record writes Priority into the Priority field and Review Due Date into the date field. The mapping guide is AI Workflow Agent: map the output and troubleshoot a run.

Frequently asked questions

Can I use more than one model in one automation?

Yes, one per action. Each AI Workflow Agent step has its own prompt, connection and output.

Can I switch the model later?

Yes. SmartSuite checks the new model against the prompt and output settings.

Can the AI Workflow Agent call tools or external MCP servers?

No. It sends the prompt and the inserted data to the model and returns the output. It does not call tools or MCP servers.

Does the step count as an automation action?

Yes. It counts toward your plan's automation actions, and the model call counts against the connection's requests or your provider's billing.

Can the agent read a PDF attached to the record?

Yes, if the model takes files. Add the file with the + under Attachments and mention it in the prompt.

Need more help? Ask the SmartSuite Community, where builders, administrators and the SmartSuite team answer questions about building on SmartSuite. For your account, billing or data, select the chat button in the lower-right corner of SmartSuite to reach support.

Last verified 1 Nov 2026.

Automation Action: AI Workflow Agent