Agent Node

An agent node ("type": "agent") runs an LLM-backed step. It is the only node type with more than one handler class, and handler_class decides the shape of process. Use this page when building nodes for Create a Workflow or Update a Workflow.

Choosing A Class

	`agent_basic`	`agent_custom`	`agent_advanced`
You supply	A blueprint	Your own prompts	A blueprint + tools
Opus writes the prompts	Yes	No	Yes
Can call tools	No	No	Yes
Use it when	You want the outcome specified and the prompting handled for you	You need exact control over wording	The step needs several tools or sub-agents to finish

An agent_advanced node cannot be used as a tool by another advanced agent. Only Basic and Custom agents, code utilities and integrations can be referenced in tool_references.

agent_basic

You describe what the step should achieve; Opus generates the prompting.

object

required

See Blueprint below.

string

Model identifier. Defaults to an empty string, which lets Opus pick.

string

Model provider. Defaults to an empty string.

string

Model to fall back to if the primary is unavailable.

string

Provider for backup_model.

agent_basic

{
  "id": "{NODE_ID}",
  "name": "Summarize Report",
  "type": "agent",
  "handler_class": "agent_basic",
  "process": {
    "blueprint": {
      "objective": "Summarize a quarterly financial report into five bullet points",
      "input_description": "A quarterly financial report as plain text",
      "process_description": "Read the report, identify the material changes, and condense them",
      "output_description": "Five bullet points, each one sentence",
      "input_items": [{ "name": "report_text", "description": "The full report" }],
      "output_items": [{ "name": "summary", "description": "Five bullets" }],
      "required_steps": [{ "name": "Extract figures", "description": "Pull the headline numbers" }]
    },
    "model": "",
    "provider": ""
  }
}

agent_custom

You write the prompts verbatim. Opus sends them as given.

string

required

The system prompt, sent unchanged.

string

required

The user prompt, sent unchanged.

string

Model identifier. Defaults to an empty string.

string

Model provider. Defaults to an empty string.

string

Model to fall back to if the primary is unavailable.

string

Provider for backup_model.

agent_custom

{
  "id": "{NODE_ID}",
  "name": "Classify Ticket",
  "type": "agent",
  "handler_class": "agent_custom",
  "process": {
    "system_prompt": "You are a support triage assistant. Reply with one word.",
    "user_prompt": "Classify this ticket as billing, technical or other:\n\n{{ticket_body}}",
    "model": "",
    "provider": ""
  }
}

agent_advanced

A blueprint agent that can call other handlers as tools.

object

required

See Blueprint below. Identical to the agent_basic blueprint.

array | object

The tools this agent may call. Defaults to empty.

object

The handlers behind those tools, keyed by tool name.

Show Tool reference object

string

required

ID of the handler to call

string

required

Version ID of that handler

string

required

Active handler ID

string

required

Active handler version ID

string

required

The referenced handler’s node type — agent, code or integration

string

required

The referenced handler’s class. Must not be agent_advanced.

string

Tool name shown to the model

string

What the tool does — the model uses this to decide when to call it

number

default:"5"

How many tool-calling rounds the agent may take before it must answer.

string

Model identifier. Defaults to an empty string.

string

Model provider. Defaults to an empty string.

string

Model to fall back to if the primary is unavailable.

string

Provider for backup_model.

agent_advanced

{
  "id": "{NODE_ID}",
  "name": "Research Vendor",
  "type": "agent",
  "handler_class": "agent_advanced",
  "process": {
    "blueprint": {
      "objective": "Produce a vendor risk summary",
      "input_description": "A vendor name",
      "process_description": "Look the vendor up, then summarize the findings",
      "output_description": "A one-paragraph risk summary"
    },
    "tool_references": {
      "lookup_vendor": {
        "handler_id": "{HANDLER_ID}",
        "handler_version_id": "{HANDLER_VERSION_ID}",
        "handler_active_id": "{HANDLER_ACTIVE_ID}",
        "handler_active_version_id": "{HANDLER_ACTIVE_VERSION_ID}",
        "handler_type": "integration",
        "handler_class": "integration",
        "name": "lookup_vendor",
        "description": "Fetch a vendor record by name"
      }
    },
    "max_iterations": 5
  }
}

Blueprint

Used by agent_basic and agent_advanced. Four fields are required — the blueprint is what Opus turns into prompts, so an empty description produces a weaker agent.

string

required

What this step is meant to achieve

string

required

What the step takes in, described as a whole

string

required

How the step should go about the work

string

required

What the step hands on, described as a whole

array

Named inputs, each { name, description }. Defaults to empty.

array

Named outputs, each { name, description }. Defaults to empty.

array

Steps the agent must carry out, each { name, description }. Defaults to empty.

input_description and output_description describe the step’s input and output as a whole. Per-variable descriptions belong in input_schema and output_schema instead.

Get Started

Workflows

Cases

Files

Business Process Discovery

Integrations

Agents

Deprecated

Choosing A Class

agent_basic

agent_custom

agent_advanced

Blueprint

​Choosing A Class

​agent_basic

​agent_custom

​agent_advanced

​Blueprint

Choosing A Class

agent_basic

agent_custom

agent_advanced

Blueprint