Building AI Agents

An AI agent is an assistant that can understand a user's request, choose the right Automation Hub action, follow progress, and explain the result in plain language.

The goal is not to make the AI do everything on its own. The goal is to make the AI helpful, careful, and easy to trust.

What an AI Agent Does

Understand

Read what the user wants to get done

Find

Look for the best matching automation

Confirm

Ask for missing or important details

Run

Start the approved automation

Report

Explain what happened and what to do next

Simple: a good agent turns a user request into a safe Automation Hub run, then keeps the user informed.

A Good Agent Feels Like This

User says	Good agent response
"Send the monthly sales report"	"I found the Monthly Sales Report automation. Which month should I use?"
"Run the backup job"	"I found two backup jobs: Database Backup and File Storage Backup. Which one should I run?"
"Stop that sync"	"I can stop the Customer Data Sync that is currently running. Please confirm before I stop it."
"Why did the job fail?"	"The job failed while sending the email because the recipient address was missing."

Core Responsibilities

1. Understand the Request

The agent should first identify what the user is trying to achieve.

Good examples:

• "Generate a report"
• "Check whether a job finished"
• "Run onboarding for a new employee"
• "Pause the current data sync"
• "Find out why an automation failed"

If the request is unclear, the agent should ask a simple follow-up question before taking action.

2. Find the Right Automation

The agent should search Automation Hub instead of guessing.

If the user...	The agent should...
Knows the exact automation name	Look up that automation directly
Describes the outcome	Search for matching automations
Mentions a department or process	Narrow the search by workspace or collection
Gives a vague request	Show the best matches and ask the user to choose

Example:

"I found three automations that may match: Monthly Sales Report, Regional Sales Summary, and Sales Email Digest. Which one do you want to run?"

3. Check Required Details

Before running anything, the agent should check what information the automation needs.

Common inputs include:

• Date or month
• Customer, vendor, or employee name
• Region or department
• Email recipient
• File, folder, or report type
• Approval choice

The agent should never guess important values when a wrong value could cause confusion, send the wrong message, or change important data.

4. Confirm Risky Actions

Some actions should require a clear confirmation.

Situation	Why the agent should confirm
Sending emails or notifications	The message may go to real people
Updating business records	Incorrect data can affect operations
Deleting, stopping, or overwriting work	The action may be hard to undo
Running a high-impact job	It may affect many users or systems
More than one automation matches	The agent may pick the wrong one

Confirmation should be short and specific:

"I am about to run Monthly Sales Report for March 2026 and email it to finance@example.com. Should I continue?"

5. Start and Monitor the Run

After the user confirms and all required details are available, the agent can start the automation.

While the automation is running, the agent should be able to answer:

• Has it started?
• Which step is running now?
• Did it complete?
• Did it fail?
• Is it paused or stopped?
• What should happen next?

6. Explain the Result

The user usually does not need raw technical output. They need a clear answer.

Automation result	Helpful explanation
Completed	"The report was generated and emailed to the finance team."
Failed	"The report was created, but the email step failed because the recipient was missing."
Paused	"The job is waiting for approval before it sends the final email."
Stopped	"The run was stopped before updating any records."

Example Conversation

User

"Send the March sales report to finance"

Agent

Finds the Monthly Sales Report automation

Agent

Confirms March 2026 and finance recipients

Automation Hub

Generates and emails the report

Agent

Reports that the job completed successfully

What to Prepare Before Using an Agent

Agents work best when automations are easy to understand.

Preparation	Why it helps
Clear automation names	The agent can find the right job faster
Helpful descriptions	The agent can explain what each automation does
Well-defined required inputs	The agent knows what to ask the user
Sensible tags and categories	Search results become more accurate
Permission rules	Users only run automations they are allowed to use
Owner information	The agent can tell users who to contact when something fails

Good Agent Rules

Search before acting

If the user does not name an exact automation, the agent should search first.

Ask when unsure

If the request is ambiguous, the agent should ask one clear question.

Confirm important actions

If the automation sends messages, changes data, or affects many users, the agent should confirm before running it.

Keep users updated

For longer jobs, the agent should explain whether the automation is running, paused, failed, or completed.

Explain failures simply

The agent should say which step failed and what the user can do next.

Common Agent Types

Agent type	What it helps with
Report assistant	Finds, runs, and sends business reports
Operations assistant	Checks health jobs, backups, alerts, and maintenance runs
Support assistant	Looks up ticket-related automations and runs follow-up actions
Approval assistant	Starts jobs that wait for manager or business approval
Monitoring assistant	Watches running jobs and explains failures or delays

When the Agent Should Pause and Ask

The agent should stop and ask the user before continuing when:

• Multiple automations look correct
• Required information is missing
• The action may send external communication
• The action may change important data
• The user asks to stop, pause, or resume a run
• A previous run failed and the user asks to retry
• The agent cannot tell whether the request is safe

Design Checklist

Use this checklist before making an automation available to AI assistants.

Question	Good answer
Is the automation name clear?	A user can understand it without opening details
Does the description explain the outcome?	It says what the automation creates, sends, checks, or updates
Are required inputs obvious?	The agent knows exactly what to ask for
Are risky actions protected?	The agent knows when to request confirmation
Is there an owner?	Users know who can help if the run fails
Are permissions correct?	Only the right users can find or run it

Guardrails Are Enforced, Not Advisory

The confirmation habits above describe how a well-behaved agent should act. The platform also enforces those boundaries mechanically through a guardrail policy attached to the run. The engine applies the policy on every tool call and every model response — the agent cannot opt out.

A guardrail is an enforced cap, not a suggestion. When more than one guardrail applies to a run, the engine merges them into the tightest effective policy:

• Permission rules union, keeping the strongest outcome per tool. Strength order is deny > ask > allow.
• Numeric limits take the smallest value across all applied policies (tool-call caps, timeouts, run limits).
• maxTokensPerResponse is a hard clamp — the response cannot exceed the tightest configured value, regardless of what a model request asks for.

Human-in-the-Loop Approval

When a guardrail sets destructiveApprovalMode to ask, a destructive tool call does not run immediately. The engine pauses the run and waits for a person to decide.

Agent Requests

A destructive tool call is proposed

Run Pauses

Status becomes awaiting_approval

Operator Decides

Approve or reject the pending action

Run Resumes

The tool runs, or the run is cancelled

ask vs deny

Mode	Behavior
ask	The run pauses and surfaces a pending approval; a person approves or rejects
deny	The destructive call is blocked outright — no pause, no approval path

The pending approval

When the run pauses, the engine surfaces a pending approval with these fields:

Field	Description
approvalId	Identifier used to resolve this approval
tool	The tool the agent wants to call
input	The arguments the agent proposed
reason	Why approval is required
requestedAt	When the request was raised

The AI Agent node polls for the decision within its maxWaitSeconds window. An operator resolves the approval with:

POST /api/v2/runs/{id}/approvals/{approval_id}
{
  "decision": "approve",     // or "reject"
  "reason": "optional note",
  "modifiedInput": { }        // optional: run the tool with adjusted arguments
}

How each outcome ends

Outcome	What happens
Approve	The tool runs (with modifiedInput if supplied) and the run continues
Reject	The run is cancelled with cancelReason = approval_rejected
Timeout	If no decision arrives within maxWaitSeconds, the run is cancelled; the step fails with errorType = APPROVAL_TIMEOUT

Error Taxonomy

When an agent step fails, it returns a structured error whose errorType tells you whether a retry could help. The retryable flag is derived from the error code, never from message text.

errorType	Retryable	Typical cause
CONFIGURATION_ERROR	No	Invalid or unsupported node configuration
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 in time
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

See the AI Agent node for the full result and error contract as it appears on the node.

Related Pages

• AI Integration Overview - the big picture of AI and Automation Hub
• AI Hub Configuration - guardrail policies, skills, servers, and tool instances
• MCP Server - the bridge between AI assistants and Automation Hub
• MCP Tools Reference - the actions an AI assistant can use
• AI Agent Node - running an agent inside a workflow