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

# Agent

> Run an AI agent inside a workflow to research, reason, generate, evaluate, or use Tools

![An Agent node with context input and prompt, and its toolbar showing the model button](https://mintcdn.com/runchat/rUDQhtaRtUR5pk6i/images/nodes/agent-node.webp?fit=max\&auto=format\&n=rUDQhtaRtUR5pk6i\&q=85\&s=1ff9ce87233be374c5dcd5285496f551)

The Agent node runs a single agent turn as part of a workflow. Use it for deep research, idea generation, reasoning, structured data generation, or to call [Tools](https://docs.runchat.com/concepts/publishing/agent-tools.md) on your behalf.

> [!NOTE]
>
> The Agent node runs once per execution and isn't conversational. For an
> interactive agent that you can chat with, use [Chat](https://docs.runchat.com/concepts/agents/chat.md)
> instead.

## Inputs

The Agent node has two inputs on the card:

* **Context**: messages, images, PDFs, or other documents the model should read before responding. Equivalent to the conversation history in a chat. Common uses include feeding in input from an [App](https://docs.runchat.com/concepts/publishing/app-view.md), wiring previous Agent outputs back in to continue a conversation, or attaching reference images.
* **Prompt**: what you want the agent to do this turn. Within a workflow, prompts should describe a task the agent can complete in one turn. If you need follow-up questions, use Chat.

Two more settings live in the node's **More** (…) menu:

* **Instructions**: a system message describing how the agent should behave.
* **Output format**: how the agent returns its answer. See [Output formats](#output-formats).

## Toolbar

Select an Agent node to show its toolbar:

* **Model**: the model button (**Swap model**) opens **Choose a model**. The Agent node only shows installed models compatible with text and reasoning. See [Models](https://docs.runchat.com/concepts/models/overview.md) for installation.
* **Tools**: attach tools to this agent. See [Tools](#tools).
* **Variations**: shown for models that generate images. See [Generating images](#generating-images).
* **More** (…): **Instructions**, **Tool effort**, **Output format**, **Output schema**, **Spread output**, plus the common node actions such as **All parameters**, **Run details**, **Duplicate** and **Delete**.

## Output formats

Open **More** > **Output format** to constrain how the agent returns its answer:

* **Markdown** (default): free-form text. Most flexible, good for general responses.
* **List**: returns multiple items as a list. Each item becomes a separate output, so downstream nodes process them in parallel.
* **HTML**: returns an HTML document, ready to preview or publish.
* **Code**: returns code without surrounding prose.
* **Custom schema**: define a JSON Schema the agent must match. Useful for generating structured data to pass to APIs, drive routing, or feed Grasshopper components.

### Custom schema types

![The Output schema editor for an Agent node](https://mintcdn.com/runchat/rUDQhtaRtUR5pk6i/images/nodes/agent-config.webp?fit=max\&auto=format\&n=rUDQhtaRtUR5pk6i\&q=85\&s=35c3854af30ba4ad9688c24634493e52)

Choosing **Custom schema** opens the **Output schema** editor. Reopen it later from **More** > **Output schema**. The editor supports these types:

| Type | Use for |
| - | - |
| `string` | Text fields |
| `number` | Numerical values |
| `boolean` | True/false values, useful for [routing decisions](https://docs.runchat.com/concepts/data/routing.md) |
| `object` | Nested key-value structures |
| `array` | Lists of items, with a typed item schema |
| `enum` | One of a fixed set of options |

Turn on **More** > **Spread output** so each top-level key becomes its own output on the node. To route a workflow on a yes/no decision, add a `boolean` field to a custom schema and turn on **Spread output**. See [Spread output](https://docs.runchat.com/concepts/nodes/parameters.md) for the full behaviour.

## Tools

Unlike Chat, the Agent node never adds Tools automatically; you specify them explicitly. Click **Tools** (wrench icon) on the node toolbar to open **Choose tools** and attach Tools (your own published workflows or default Tools like search) to this Agent. The button shows how many tools are attached.

The agent calls attached Tools as needed during a single run. For example, an agent prompted to "design a website for a new brand" with search and image-generation tools attached might:

1. Use search to research the brand and similar companies
2. Pull representative images from sources it finds
3. Call an image-generation Tool to create new visuals in a similar style
4. Return an HTML output

For more on building tools and how agents use them, see [Agent Tools](https://docs.runchat.com/concepts/publishing/agent-tools.md).

### Tool effort

Once tools are attached, **More** > **Tool effort** caps how many tool calls the agent can make in a single run:

* **Fast (3 tool calls)**: good when you want the agent to use a specific tool selectively.
* **Moderate (10 tool calls)** (default).
* **Max (25 tool calls)**: for deeper research tasks.
* **Custom**: set any value from 1 to 50.

Higher effort means more thorough but more credits per run.

## Generating images

Some text models can also generate or edit images (e.g. Nano Banana, GPT-Image, Gemini multimodal). When you select one of these as the Agent's model, the toolbar adds **Variations** and the **More** menu adds **Size**, so you can produce multiple image variants per run. The output appears alongside the text response.

## Next steps

* [Chat](https://docs.runchat.com/concepts/agents/chat.md): use an interactive agent instead of a one-shot node
* [Agent Capabilities](https://docs.runchat.com/concepts/agents/capabilities.md): the full set of built-in agent tools
* [Agent Tools](https://docs.runchat.com/concepts/publishing/agent-tools.md): attach published workflows as tools
* [Spread output](https://docs.runchat.com/concepts/nodes/parameters.md): fan a structured response into multiple outputs
* [Routing](https://docs.runchat.com/concepts/data/routing.md): drive workflow flow with boolean Agent outputs


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