> ## Documentation Index
> Fetch the complete documentation index at: https://developer.opus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Node

> The three agent handler classes and the process object each one takes

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](/api-reference/v1-workflow-generation/create-workflow) or [Update a Workflow](/api-reference/v1-workflow-generation/update-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 |

<Note>
  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`.
</Note>

## agent\_basic

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

<ParamField body="blueprint" type="object" required>
  See [Blueprint](#blueprint) below.
</ParamField>

<ParamField body="model" type="string">
  Model identifier. Defaults to an empty string, which lets Opus pick.
</ParamField>

<ParamField body="provider" type="string">
  Model provider. Defaults to an empty string.
</ParamField>

<ParamField body="backup_model" type="string">
  Model to fall back to if the primary is unavailable.
</ParamField>

<ParamField body="backup_provider" type="string">
  Provider for `backup_model`.
</ParamField>

```json agent_basic theme={null}
{
  "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.

<ParamField body="system_prompt" type="string" required>
  The system prompt, sent unchanged.
</ParamField>

<ParamField body="user_prompt" type="string" required>
  The user prompt, sent unchanged.
</ParamField>

<ParamField body="model" type="string">
  Model identifier. Defaults to an empty string.
</ParamField>

<ParamField body="provider" type="string">
  Model provider. Defaults to an empty string.
</ParamField>

<ParamField body="backup_model" type="string">
  Model to fall back to if the primary is unavailable.
</ParamField>

<ParamField body="backup_provider" type="string">
  Provider for `backup_model`.
</ParamField>

```json agent_custom theme={null}
{
  "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.

<ParamField body="blueprint" type="object" required>
  See [Blueprint](#blueprint) below. Identical to the `agent_basic` blueprint.
</ParamField>

<ParamField body="tools" type="array | object">
  The tools this agent may call. Defaults to empty.
</ParamField>

<ParamField body="tool_references" type="object">
  The handlers behind those tools, keyed by tool name.

  <Expandable title="Tool reference object">
    <ParamField body="handler_id" type="string" required>
      ID of the handler to call
    </ParamField>

    <ParamField body="handler_version_id" type="string" required>
      Version ID of that handler
    </ParamField>

    <ParamField body="handler_active_id" type="string" required>
      Active handler ID
    </ParamField>

    <ParamField body="handler_active_version_id" type="string" required>
      Active handler version ID
    </ParamField>

    <ParamField body="handler_type" type="string" required>
      The referenced handler's node type — `agent`, `code` or `integration`
    </ParamField>

    <ParamField body="handler_class" type="string" required>
      The referenced handler's class. Must not be `agent_advanced`.
    </ParamField>

    <ParamField body="name" type="string">
      Tool name shown to the model
    </ParamField>

    <ParamField body="description" type="string">
      What the tool does — the model uses this to decide when to call it
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_iterations" type="number" default="5">
  How many tool-calling rounds the agent may take before it must answer.
</ParamField>

<ParamField body="model" type="string">
  Model identifier. Defaults to an empty string.
</ParamField>

<ParamField body="provider" type="string">
  Model provider. Defaults to an empty string.
</ParamField>

<ParamField body="backup_model" type="string">
  Model to fall back to if the primary is unavailable.
</ParamField>

<ParamField body="backup_provider" type="string">
  Provider for `backup_model`.
</ParamField>

```json agent_advanced theme={null}
{
  "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.

<ParamField body="objective" type="string" required>
  What this step is meant to achieve
</ParamField>

<ParamField body="input_description" type="string" required>
  What the step takes in, described as a whole
</ParamField>

<ParamField body="process_description" type="string" required>
  How the step should go about the work
</ParamField>

<ParamField body="output_description" type="string" required>
  What the step hands on, described as a whole
</ParamField>

<ParamField body="input_items" type="array">
  Named inputs, each `{ name, description }`. Defaults to empty.
</ParamField>

<ParamField body="output_items" type="array">
  Named outputs, each `{ name, description }`. Defaults to empty.
</ParamField>

<ParamField body="required_steps" type="array">
  Steps the agent must carry out, each `{ name, description }`. Defaults to empty.
</ParamField>

<Note>
  `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`](/api-reference/v1-workflow-generation/variable-schemas) instead.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.