AI Agent

Run one of your saved agents as a workflow step, with its model, instructions, tools and knowledge.

The AI Agent node (ai_agent) runs one of your agents as a step. The agent brings everything configured on it — model and fallback model, instructions, tools, Knowledge Bases, skills and guardrails — so the workflow only decides what to send it.

Configuration

Field	Type	Default	Description
`mode`	`existing`	—	Always `existing`: the node runs a saved agent. Agents built inline on the node are no longer supported and are refused when the workflow is saved.
`agentId`	string	—	The agent to run. It must belong to the workflow's organization.
`agentName`	string	—	The agent's name, kept for display.
`inputMappings`	list of `{ field, expression }`	`[]`	What to send the agent. Each `expression` is resolved with the `{{ }}` syntax. One mapping sends its value; several send a JSON object keyed by `field`.

With no input mappings the node forwards what reached it: the output of its one upstream node, or a { nodeId: output } object when several feed it, or the trigger payload when nothing does.

How agent settings apply inside a workflow

Model, instructions, tools, Knowledge Bases, skills, guardrails — exactly as configured on the agent. Change the agent and every workflow that runs it changes with it.
Memory — each node in each run gets its own session, so a workflow run does not continue a chat and two runs do not share history. User memories, if enabled on the agent, are scoped to the run.
The current date — turn on Add date/time to context in the agent's Basic information and the agent is told the current time (UTC). To pass the run's own start time instead, map {{ run.startedAt }} into its input.
Budget — the run's organization budget applies to every call the agent makes.
Policies — the workflow's policies govern the run, not the agent's; see Policies inside a workflow.

Policies inside a workflow

The node runs under the workflow's effective policy: the Organization's and the Project's policies, plus the ones attached to the workflow. Policies attached to the agent itself count in one place only:

Rule	Decided by
Which of the agent's tools it can use	The workflow's effective policy only.
Each tool call as it is made: tool ceilings and the host allowlist	The agent's policies: the Organization's, the Project's and the agent's own. A tool the agent's policy forbids is still offered to the model, but its calls are refused.
Approval requirements, model and region checks, data rules, and the host allowlist for model providers	The workflow's effective policy only.

To govern what an agent does inside workflows, attach the policy to the workflow, its Project or the Organization. A policy attached to the agent covers it when it is called directly (chat, the API, async jobs), inside a Team, and on each tool call. See Policies for what a policy can do.

Output

Field	Type	Description
`text`	string	The agent's answer.
`json`	object \| null	The answer parsed as a JSON object, when `text` is one; else `null`.
`model`	string	The model that answered — the fallback model if the primary failed.
`toolCalls`	array	Each tool call: `toolName`, `input`, `output`, `latencyMs`.
`knowledgeQueriesCount`	number	How many Knowledge Base searches the agent made.
`tokenUsage.prompt`	number	Prompt tokens.
`tokenUsage.completion`	number	Completion tokens.
`estimatedCostUsd`	number \| null	Estimated cost of the call; `null` when the model has no price.
`latencyMs`	number	How long the step took.

Reference them as {{ upstream.<nodeId>.output.text }}.

Limits and errors

The node fails, and says why on the node, when no agent is selected, the agent belongs to another organization, the node was saved in the retired inline mode, the agent's model call fails on both its primary and fallback model, or the step runs past the node time limit. A failed node stops its branch; see Retrying a failed run.

Example

workflows/answer-ticket.yaml

name: Answer ticket
description: Drafts an answer to a support ticket.
graph:
  nodes:
    - id: ticket
      type: trigger_http
      position: { x: 0, y: 0 }
      data:
        method: POST
        fields:
          - { name: subject, type: string, required: true }
          - { name: message, type: string, required: true }
    - id: draft
      type: ai_agent
      position: { x: 280, y: 0 }
      data:
        mode: existing
        agent: agents.support
        agentName: Support
        inputMappings:
          - field: ticket
            expression: 'Today is {{ run.startedAt }}. Subject: {{ trigger.body.subject }}. {{ trigger.body.message }}'
  edges:
    - { id: ticket-to-draft, source: ticket, target: draft }

In a Package

The agent travels with the Package: declare it under agents: in the manifest and reference it from the node as agents.<name>.

Travels: mode, agentName, inputMappings
Converted: agentId → agent (an agents.<name> reference)
Never carried: none

Check the Package with npx @elizon/cli validate and npx @elizon/cli build.