An AI Field Agent is a prompt attached to one field that writes its answer into that field, on demand or whenever the fields it references change. A Workspace Administrator enables the feature in AI Control Center; then a Solution Manager opens Field Settings on a supported field and configures the agent on the AI Field Agent tab.

Plan Availability	Team, Professional and Enterprise (the plans with SmartSuite AI on the pricing page); the 14-day free trial runs on Professional.
Permissions	Workspace Administrators enable AI Field Agents and manage connections in AI Control Center. Solution Managers configure an agent on a field. Members run an agent from Grid view, the record page or a Record Details widget.
Platform	Web.
Related Reading	AI Field Agents AI Control Center: Providers and Models AI Platforms and Models Categorize records with AI.

What do I need before I start?

AI Field Agents turned on for the workspace in AI Control Center (a Workspace Administrator does this).
A connection enabled for AI Field Agent on this solution. The SmartSuite Trial connection with 100 free requests is there from the start; your own provider key continues after that.
A field of a supported type: Title, Text, Text Area, SmartDoc, Number, Single Select, Multiple Select, Status, Link, Address or Date.

Note: for a Date field with time enabled the agent writes both the date and the time. For an Address field it writes the street, city, state, postal code and country. For Single Select, Multiple Select and Status fields it maps its answer to the field's existing options.

How do I enable AI Field Agents for the workspace?

Open the profile menu in the upper-right corner and select Workspace Administration.
Go to AI Control Center > AI Field Agents.
Turn on Enable AI Field Agents.
Optional: turn on Internet Search support so agents can add web context. It is off by default.
Read Free AI requests remaining to see how many of the 100 trial requests are left.

Important: only Workspace Administrators see these settings. Turning the feature off deactivates every agent and returns the fields to standard behavior; the configurations are kept and come back when the feature is turned on again.

How do I add an agent to a field?

Open Field Settings on a supported field.
Select the AI Field Agent tab.
Turn on Enable AI Field Agent.
In the prompt, write the instruction and insert at least one field reference with the field selector; the prompt is rejected without one. Rich text such as bullets and bold is allowed.
Under Connection, choose the connection the agent runs on. The list shows only the connections an Administrator enabled for AI Field Agent on this solution.
Optional: under the prompt, click Add Files, select the files and click Upload to attach reference material that is sent on every run.
Optional: turn on Run Automatically so the agent runs whenever a referenced field changes.
Optional: turn on Internet Search. The toggle appears only when the workspace allows it and the selected model supports search.
Click Update Field. The agent is ready to run.

What makes a good prompt?

Name the fields the answer depends on, for example: Based on {{Issue Description}} and {{Priority Level}}, summarize the root cause and the recommended next step.
Say what shape the answer takes: one sentence, a number from 1 to 100, or one of the field's options.
For a Single Select, Multiple Select or Status field, describe each option in the field settings; the option descriptions and numeric values are sent with the prompt.
Keep deleted fields out of the prompt. A missing field reference breaks the prompt and the agent stops running until you fix it.

Which files can the agent read?

Static files are attached in the agent settings and sent on every run: a policy, a classification framework or a product catalog. Dynamic files come from a Files and Images field inserted into the prompt; the agent sends the files stored in that field for the record it is processing. Supported inputs are PDF, CSV, Excel and image files, under 50 MB per file and 50 MB in total per request. Attachment options appear only when the selected model supports files and images.

How do I run an agent?

An agent runs in one of three ways: on demand from the field, automatically when a referenced field changes, or not at all while you stop it.

Run it by hand

Open the record in Grid view, on the record page or in a Record Details widget and run the agent from the field. A spinner shows while the run is pending; the value appears in the field when the run succeeds.

Run it automatically

With Run Automatically on, the agent runs whenever a referenced field changes and the result is applied without anyone clicking. Runs happen only when a referenced value changes, so existing records keep their current value until a referenced field is edited or you run the agent on them by hand.

Stop a run

While an agent is generating, an X icon replaces the spinner; hovering shows Stop agent. Clicking it cancels the run and returns the field to its regular state. If the model's response arrives later it does not change the field, and the stopped run still counts as one request because it was already sent.

What do the states and indicators mean?

What you see.	What it means.
A spinner in the field.	A run is pending.
A value with an AI indicator, and Updated by AI in the activity history.	The agent wrote the value. The activity history also logs it as an AI event.
Updated by a Member's name, and no AI indicator.	Someone edited the field after the agent wrote it.
A red indicator with hover text.	The run failed; the hover text names the error. See the table below.

How do I fix an error?

Errors show inline on the field with a red indicator; hover to read the message.

Message or symptom.	Cause.	What to do.
AI Agent Failed.	AI Field Agents are not enabled at the workspace level, or the agent's configuration has a problem.	Ask a Workspace Administrator to check Enable AI Field Agents, then reopen the AI Field Agent tab and check the prompt and the connection.
No AI requests left.	The connection's requests are used up; on the SmartSuite Trial connection that is 100.	An Administrator adds a connection with your own provider key in AI Control Center > Providers and Models and enables it for AI Field Agent on this solution; then select it under Connection.
Invalid API key.	The key does not validate with the provider. Invalid keys disable agents until corrected, and Administrators get one digest email per failure cycle.	An Administrator replaces the key in the connection and tests it.
Model error.	The provider returned an error.	Run the agent again. If it repeats, an Administrator tests the connection in AI Control Center or switches the connection to another model.
A message that the prompt is broken, and the agent does not run.	A field referenced in the prompt was deleted or is missing.	Edit the prompt and replace the missing reference.
The connection is not in the drop-down.	The connection is not enabled for AI Field Agent on this solution.	An Administrator edits the connection and enables AI Field Agent for the solution.
No attachment options in the agent settings.	The selected model does not support files and images.	Choose a connection whose model shows PDF and image support in AI Platforms and Models.
No Internet Search toggle.	Internet Search support is off for the workspace, or the model does not support search.	An Administrator turns on Internet Search support, and you choose a model that supports it.
A file upload is refused.	The file is over 50 MB, or the total for the request would exceed 50 MB.	Split or compress the file.
The agent did not run on its own.	Run Automatically is off, or no referenced field changed.	Turn on Run Automatically, or edit a referenced field; existing records do not run until one does.
Every agent stopped at once.	A Workspace Administrator turned AI Field Agents off.	Turn the feature back on; the configurations are preserved.

If an error continues after these checks, contact Support through the in-app chat with the solution and field names, the connection name and the exact message.

Frequently asked questions

Which field types can hold an AI Field Agent?

Title, Text, Text Area, SmartDoc, Number, Single Select, Multiple Select, Status, Link, Address and Date.

Does a stopped run count against the free requests?

Yes. The request was already sent when you clicked Stop agent, so it counts even though the field does not change.

What happens when I duplicate a field or a table with an agent?

Duplicating the field keeps the prompt configuration and the underlying automation, and duplicating a table applies the AI configuration to the new table.

Can an agent search the internet?

Yes, when a Workspace Administrator has turned on Internet Search support and the selected model supports it. The per-field Internet Search toggle appears only then; it is off by default.

Where do I see that a value came from AI?

The field shows an AI indicator and the record's activity history shows Updated by AI. If someone edits the field afterwards, the activity shows that Member's name instead.

How many free requests does a workspace get?

100 on the SmartSuite Trial connection, with no API key. Administrators read the remaining count under AI Control Center > AI Field Agents.

Last verified 24 Oct 2026.

AI Field Agents: configure, run and troubleshoot