AI Agent

🤖

AI Agent

Run an AI agent as a workflow step — with tools, skills, guardrails, and human approval

The AI Agent node runs an AI agent as a step in a workflow. Depending on the action, it can hold a full agentic tool loop that runs until it reaches a terminal state, make a single synchronous model call, work with a knowledge base, or recall agent memory. It references reusable objects — tool instances, MCP servers, skills, and guardrail policies — from the AI Hub by id.

Common uses include:

• Running a durable agent that plans, calls tools, and returns a result.
• Classifying, extracting, summarizing, or rewriting text with a single model call.
• Answering questions from an ingested knowledge base.
• Coordinating subagents on a larger task.

Values written as {{expression}} in the prompt and tool parameters are resolved from workflow data before the agent runs.

Before You Use This Node

What you may need	Where to set it up	Why it matters
A guardrail policy	AI Hub Configuration	Enforces tool permissions, run limits, and the token clamp.
Tool instances or MCP servers	AI Hub Configuration	Gives the agent the tools it is allowed to call.
AI skills	AI Hub Configuration	Injects reusable instructions into the agent.
Saved values such as customer name, ticket ID, or report period	Global Variables	Create the value once, then reference it as {{...}} in the prompt.

Actions

Action	Description
aiAgent:runAgent	Durable agentic run with a tool loop; HITL-capable; polls to a terminal state
aiAgent:runMultiAgent	Same as runAgent, forcing mode = subagents
aiAgent:chat	Stateless synchronous chat; returns immediately, no polling
aiAgent:transform	Single synchronous model call for classify, extract, summarize, or rewrite
aiAgent:ingestDocuments	Ingest documents into a knowledge base (RAG)
aiAgent:queryKnowledge	Query an ingested knowledge base (RAG)
aiAgent:manageMemory	Recall agent memory
aiAgent:manageSkill	Proxy skill management to the AI Hub — not yet available (the handler currently throws)
aiAgent:toolResource	Resource node; merged into an agent step, inert on its own
aiAgent:memoryResource	Resource node; merged into an agent step, inert on its own
aiAgent:skillResource	Resource node; merged into an agent step, inert on its own
aiAgent:guardrailResource	Resource node; merged into an agent step, inert on its own

Legacy actions

The earlier aiAgent:talkToDatabase, aiAgent:talkToDocument, aiAgent:talkToKnowledgeGraph, aiAgent:talkToCode, and aiAgent:talkToSME actions are no longer handled by the workflow node. The v2 node rejects them with CONFIGURATION_ERROR. Rebuild those steps using aiAgent:runAgent or aiAgent:transform.

The Basic Idea

Configure

Pick an action, model, tools, and guardrails

Resolve

Expression placeholders fill in from workflow data

Run

The agent engine executes the run

Return

The result flows to the next step

Simple: the node hands a fully resolved request to the agent engine and returns the outcome to the workflow.

Node Configuration

Node configuration is grouped into sections. The parameters below apply across the run actions; chat and transform use the prompt and model settings but do not poll.

promptConfig

Parameter	Type	Required	Default	Description
promptConfig.prompt (or promptConfig.userPrompt)	string	Yes	--	The user prompt. {{...}} expressions are resolved before the engine call

agentConfig

Parameter	Type	Required	Default	Description
agentConfig.model	string	Yes	--	Model id. There is no engine default
agentConfig.mode	string	No	auto	auto, single, or subagents. Aliases: react → auto, multi_agent → subagents, single_agent → single
agentConfig.fallbackModels	string[]	No	[]	Models to fall back to if the primary fails
agentConfig.skillIds / agentConfig.skillId	string[] / string	No	--	AI Hub skill ids to inject

modelParams

Parameter	Type	Required	Default	Description
modelParams.temperature	number	No	--	Sampling temperature
modelParams.maxTokens	int	No	--	Max response tokens; clamped by the guardrail maxTokensPerResponse
modelParams.topP	number	No	--	Nucleus sampling
modelParams.thinking	boolean	No	--	true sends a thinking config with thinkingBudget
modelParams.thinkingBudget	int	No	--	Token budget for thinking
modelParams.topK / seed / frequencyPenalty / presencePenalty / stop	any	No	--	Passed through, snake_cased, to the engine

toolsConfig

Parameter	Type	Required	Default	Description
toolsConfig.tools	string[]	No	[]	AI Tool Instance ids
toolsConfig.mcpServers	string[]	No	[]	MCP server ids

executionLimits

Parameter	Type	Required	Default	Description
executionLimits.maxIterations	int	No	30	Max agent iterations; a guardrail can lower it
executionLimits.maxExecutionTimeSeconds	int	No	1800	Max run time; a guardrail can lower it
executionLimits.tokenBudget	int	No	--	Sent only if greater than 0
executionLimits.costLimitUsd	number	No	--	Sent only if greater than 0
executionLimits.pollIntervalSeconds	int	No	5	How often runAgent polls for status
executionLimits.maxWaitSeconds	int	No	600	runAgent poll and HITL approval window

guardrails

Parameter	Type	Required	Default	Description
guardrails	map or list	No	--	Inline { guardrailId, blockedTools }, or a list from resource nodes

memory

Parameter	Type	Required	Default	Description
memory.sessionId	string	No	--	Memory session binding
memory.agentId	string	No	--	Memory agent binding

---

aiAgent:runAgent

Runs a durable agent with a tool loop. The node starts the run, then polls every pollIntervalSeconds up to maxWaitSeconds until the run reaches a terminal state. If a guardrail pauses the run for approval, the same window applies while a person decides.

Example: Triage a support ticket with tools

Field	Value
Action	aiAgent:runAgent
promptConfig.prompt	Triage ticket {{ticketId}}. Look up the customer and suggest the next owner.
agentConfig.model	claude-sonnet-4-5
toolsConfig.tools	["crm-lookup", "ticket-update"]
guardrails	{ "guardrailId": "support-safe" }
executionLimits.maxWaitSeconds	600

What happens:

1. The node resolves {{ticketId}} from workflow data.
2. It starts the run and passes the tool instances and guardrail policy.
3. The agent plans and calls tools; the guardrail is enforced on each call.
4. The node polls until the run completes, then returns the agent output.

aiAgent:runMultiAgent

Identical to runAgent, but forces agentConfig.mode = subagents so the agent coordinates subagents. Use it for larger tasks that decompose into parallel or specialized sub-tasks.

aiAgent:chat

A stateless, synchronous chat call. It returns immediately with no polling and no tool loop. Use it for a quick conversational reply that does not need tools or durability.

Example: Draft a short reply

Field	Value
Action	aiAgent:chat
promptConfig.prompt	Write a one-line acknowledgement for ticket {{ticketId}}.
agentConfig.model	claude-sonnet-4-5

aiAgent:transform

A single synchronous model call for a transformation task — classify, extract, summarize, or rewrite. Like chat, it does not poll.

Example: Classify an incoming message

Field	Value
Action	aiAgent:transform
promptConfig.prompt	Classify this message as billing, technical, or other: {{Read message.output}}
agentConfig.model	claude-sonnet-4-5

aiAgent:ingestDocuments / aiAgent:queryKnowledge

RAG actions. ingestDocuments adds documents to a knowledge base; queryKnowledge answers a question from an ingested base.

aiAgent:manageMemory

Recalls stored agent memory, bound through memory.sessionId and memory.agentId.

aiAgent:manageSkill

Proxies skill management to the AI Hub. This action is not yet available — the handler currently throws. Manage skills directly in AI Hub Configuration instead.

Resource nodes

aiAgent:toolResource, aiAgent:memoryResource, aiAgent:skillResource, and aiAgent:guardrailResource are resource nodes. They contribute their configuration to an agent step when connected to one. On their own, they are inert and do not run anything.

---

Human Approval

When the run's guardrail sets destructiveApprovalMode to ask, a destructive tool call pauses the run for human approval. The node keeps polling within maxWaitSeconds while an operator approves or rejects the pending action. On timeout, the step fails with APPROVAL_TIMEOUT; on rejection, the run is cancelled. See Building AI Agents for the full flow.

---

Output

On success, the node returns the run, chat, or transform output for the action. On failure, it returns a structured error:

{
  "status": "failure",
  "errorType": "UPSTREAM_LLM_ERROR",
  "message": "The model provider returned a transient error.",
  "retryable": true
}

Field	Type	Description
status	string	success or failure
errorType	string	Error category (see below) — present on failure
message	string	Human-readable detail
retryable	boolean	Whether a retry may help; derived from the error code, never the message

---

Error Taxonomy

errorType	Retryable	Typical cause
CONFIGURATION_ERROR	No	Invalid or unsupported node configuration (including legacy talkTo* actions)
VALIDATION_ERROR	No	Request failed validation
NOT_FOUND	No	A referenced resource does not exist
CONFLICT	No	A conflicting state prevented the operation
RUN_NOT_RESUMABLE	No	The run cannot be resumed from its current state
BUDGET_EXCEEDED	No	A token or cost budget was exhausted
APPROVAL_TIMEOUT	No	No approval decision arrived within maxWaitSeconds
RUN_TIMEOUT	No	The run exceeded its time limit
UPSTREAM_LLM_ERROR	Yes	The model provider returned a transient error
UPSTREAM_TOOL_ERROR	Yes	A tool or MCP call failed transiently
INTERNAL	No	An unexpected internal error

---

Common Error Scenarios

Error	Likely Cause	What to Check
CONFIGURATION_ERROR	A legacy talkTo* action, or a missing required field	Rebuild the step with a v2 action; confirm promptConfig.prompt and agentConfig.model are set
APPROVAL_TIMEOUT	No one approved a paused destructive action in time	Raise executionLimits.maxWaitSeconds or ensure an operator is available to approve
RUN_TIMEOUT	The run exceeded its time limit	Raise executionLimits.maxExecutionTimeSeconds, or check whether a guardrail lowered it
BUDGET_EXCEEDED	The token or cost budget ran out	Increase tokenBudget / costLimitUsd, or reduce the work the agent attempts
UPSTREAM_LLM_ERROR	A transient model provider error	Retry; add agentConfig.fallbackModels for resilience

---

Best Practices

• Attach a guardrail to every agent run. It enforces tool permissions, run limits, and the maxTokensPerResponse clamp — see guardrail policies.
• Give the agent named tool instances, not raw operations. Pre-configured tool instances keep credentials and parameters consistent.
• Use {{...}} for workflow data. Reference values from earlier steps and Global Variables instead of hard-coding them; they resolve before the run.
• Size the HITL window for real approvers. If destructive actions pause for approval, set maxWaitSeconds to a value someone can realistically meet.
• Only retry retryable errors. Check the retryable flag; retrying a CONFIGURATION_ERROR will fail the same way.
• Prefer chat or transform for simple calls. They return immediately; reserve runAgent for durable, tool-using work.

---

Related Pages

• AI Hub Configuration - the guardrails, tools, servers, and skills this node references
• Building AI Agents - guardrail enforcement and human approval
• MCP Server - registered MCP servers and tool discovery
• MCP Tools Reference - discovered tools and tool instances