The Agent node runs a goal-directed AI agent that reasons over several turns and uses the tools of the extensions you make available to it. Unlike the AI Prompt node's single request, the Agent decides its own steps at run time to reach the goal you describe. This article is for workspace users with the Admin role or higher who build workflows in the Designer.
- What the Node Does
- Inline or a Saved Agent
- Configuration Fields
- Enhancing the Goal
- Choosing a Model
- How Extension Scope Is Resolved
- Grounding on Knowledge
- Structured Input and Output
- Unattended Runs
- Approval Gating and Auto-Approve
- Usage Credits
What the Node Does
Add an Agent node from the AI section of the palette. When the step runs, the agent works toward the goal you set, calling the tools exposed by the extensions you have selected and adapting its next step based on what each tool returns. It runs a multi-turn loop rather than a single prompt.
Inline or a Saved Agent
An Agent node can work in two ways:
- Inline — define the goal and extension scope directly on the node, for one-off use in this workflow
- Reference a saved agent — point the node at an installed catalog agent or one of your own custom agents by its slug. The saved agent supplies the goal, its extensions, and any input and output contract, and the node's extension picker pre-fills with the agent's extensions and stays editable.
Both installed catalog agents and your own custom agents resolve the same way, so a custom agent brings its goal, extensions, and input and output fields onto the node exactly as a catalog agent does. Agents are managed on the Agents page. See the articles on browsing and installing agents from the catalog and on creating custom agents.
Configuration Fields
-
goal— what you want the agent to accomplish, in natural language. The goal is required: publishing or testing the workflow is refused while an Agent node's goal is missing or contains only spaces, with the message "Agent node 'name' (id) has no goal. Describe what the agent should do." The goal supports{{ }}binding expressions, so you can fold in values from earlier nodes, and a goal built from a binding expression passes this check. The goal editor's Enhance button can fill in how to reach the goal with the node's extensions (see Enhancing the Goal). -
allowedExtensions— the extensions whose tools the agent may use (selected as Required extensions in the node). Keep the list focused; the Designer warns if the selected extensions expose more tools than the model's tool limit. -
model— shown in the node as Model (optional). Leave it blank, the default, to use your workspace's Default model if one is set, or otherwise the runner's default model; the field's placeholder reads Runner default either way. A model you name here is a request rather than a requirement (see below). -
timeoutSeconds— how long the agent may run, from 30 to 1800 seconds (default 600) -
autoApprove— whether the agent may run mutating tools without pausing for approval (see below)
An Agent node can run with no extensions and no saved agent, in which case it reasons without tools.
Enhancing the Goal
The Enhance button sits beside Find in the goal editor's toolbar. It checks your goal against the tools of the extensions this agent can use and adds the detail the agent needs to do the work with them. It is disabled while the goal is empty.
- Write the goal in your own words.
- Select Enhance. While it works, the toolbar shows Enhancing… and a Cancel button, and you can keep editing.
- Review the result. Your text stays exactly as you wrote it, and a ## Resolved against this agent's extensions section is added under it.
A strip of notes appears under the toolbar. It names the extensions the added section uses, lists under Not covered by this agent's extensions any actions none of them can do, and shows any notice about the result. If your goal already says what the agent needs, the notes say so and nothing is added. Select Dismiss to close the notes.
To take the change back, press Ctrl+Z once in the goal editor, or select Undo enhance in the notes. Undo enhance is offered only until you edit the goal further; after that, use Ctrl+Z. Running Enhance again on a goal that already has the section revises that section rather than adding a second one.
Enhance works with exactly the extensions this node's run will be offered:
- The node's own extension list, if it has one
- Otherwise, no extensions for an inline agent
- Otherwise, the saved agent's own extensions
When the node runs for no company, company-only extensions are left out, because a run for no company is never offered them, and the notes name the ones left out.
A {{ }} binding in the added section is kept only if your goal already uses it. Any other binding is turned into plain text, and the notes say so, because a binding the run can't resolve fails the step.
If you change the goal, or the node's extensions, saved agent, or company scope, while Enhance is running, the result is not applied, because it could name tools the run won't be offered. The notes tell you what changed; run Enhance again.
Choosing a Model
The runner that executes the step calls the AI provider configured on that runner, and each runner has a default model that is configured in the runner's Key Vault along with its provider. See the article on choosing the runner AI provider. Your workspace can also set one Default model, on the Settings > Model page, that replaces the runner's default for every agent that names no model.
The agent uses the first of these that is set:
- The model named on the saved agent or on the Agent node
- The workspace Default model, from Settings > Model
- The runner's default model
- Blank model — the agent uses the workspace Default model if one is set, or otherwise the runner's default model. This is the recommended setting, and new Agent nodes and agents start blank.
- Named model — the runner tries that model on its own AI provider. If the provider reports that the model does not exist, the runner falls back to its default model and continues. Any other error is handled as usual and does not switch models.
The workspace Default model is a request in the same way: if the runner's provider does not have it, the runner falls back once to its own default. It is one value for the whole workspace, used whatever company the run is for. Only the workspace Owner can change it.
Model IDs differ by provider, for example gpt-5.4, openai/gpt-5.4, claude-sonnet-5, or a Foundry deployment name, so a model that works on one runner may fall back on another. The agent settles on its model at the start of the run and keeps it, including after a pause for approval. If that model stops being available partway through the run, the agent switches to the runner's default for the rest of the run.
On the Agents page, a saved agent with no model shows Model: Runner default and one with a model shows Requested: model, because a named model is only a request. A blank-model agent still shows Model: Runner default when your workspace has a Default model set, even though it runs on the workspace Default model. Each run records the model that actually answered, and the run detail shows it. When the runner fell back, the run detail shows a notice such as "Requested claude-opus-5 → ran on gpt-5.4 (not available on this runner)." A run that switched models partway through shows "Switched to model partway through the run (the model it was using stopped being available on this runner)."
This model handling requires runner version 2.2.0 or later. On an older runner, a blank model behaves as it did before, and the run does not record which model answered. An older runner has no fall-back, though: when your workspace has a Default model set, it uses that name as-is for blank-model agents, so a name its provider does not offer fails those runs until you clear the setting or upgrade the runner. A self-updating runner picks up the current version automatically; see upgrading a runner to a new version.
How Extension Scope Is Resolved
When you bind a saved agent, the node's extension picker fills in with that agent's extensions and remains editable, so you can add extra integrations for this step. The rules are:
- If the node lists extensions, that list is what the agent may use for this step
- If you clear the node's list, the step falls back to the bound agent's own extensions rather than running with no tools
- Reopening the node editor does not overwrite a selection you have made; the picker only fills an empty list
- Switching to a different saved agent replaces the list with the new agent's extensions and prunes input bindings that no longer apply
Keeping the list focused matters: an agent given every integration in your workspace at once can exceed the model's tool limit and fail the run. If an Agent node bound to a saved agent shows no extensions, open the node once and the picker fills in from the agent.
Grounding on Knowledge
You can ground an Agent node on your knowledge base so it reasons with your own documents. In the node's grounding section, attach one or more Knowledge folders or documents; each appears as a chip you can remove. At run time AutomationAI recalls the most relevant passages and supplies them to the agent, and the grounded agent also gets a built-in knowledge search tool it can call during its run to look for more detail. For the full picture, see the article on grounding agents and AI Prompt nodes on knowledge.
Structured Input and Output
A saved agent can declare an input schema and an output schema. When the referenced agent declares an input schema, the node shows a binding table where you map each input field to an upstream node's output. The agent's declared output fields appear as bindable paths, so later nodes can reference specific parts of the agent's result. For how bindings work in general, see the article on passing data between nodes.
Unattended Runs
A workflow is built to run on its own, so an Agent node in a workflow, or an agent play in a playbook, runs unattended: nobody is expected to be watching to answer a question partway through. On an unattended run the agent cannot pause to ask you for information. It gathers what it needs from its tools, and if something essential is still missing, it finishes with an answer that names what it could not find rather than guessing a value. The step always reaches an end, so the workflow either continues or fails with a readable reason instead of waiting indefinitely.
This does not change approval gating: a tool that changes data still pauses for approval, as described below. In the AI Playground, where you are watching the run, the agent can still pause to ask you a question, but only when it is genuinely blocked.
Unattended runs require runner version 2.1.0 or later. A self-updating runner picks this up automatically; see upgrading a runner to a new version.
Approval Gating and Auto-Approve
By default, when an agent wants to run a tool that changes data — a mutating or approval-gated tool — the run pauses and waits for a person to approve the action. Turning on autoApprove lets the agent run those tools without pausing.
Only the Owner or Admin role can enable auto-approve; the toggle is disabled for Members, and the setting is enforced when the workflow is published or tested. Use it with care, since it removes the human checkpoint before changes are made. When a run is waiting on approval, you handle it from the Inbox (see the article on handling Action Required items in the Inbox).
Usage Credits
The Agent node runs on your runner, which calls the runner's own AI provider, so the model's tokens are billed by that provider and do not consume Usage Credits. The step still records the model and token counts so you can review them in the run history. When the node is grounded on knowledge, AutomationAI searches your knowledge on each run, and that search consumes a small number of Usage Credits. Enhance in the goal editor runs on AutomationAI's own AI model rather than your runner, so each use counts toward your workspace's Usage Credits. See the article on understanding Usage Credits and billing for what is metered.
Comments
0 comments
Please sign in to leave a comment.