> For the complete documentation index, see [llms.txt](https://docs.lleverage.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lleverage.ai/build-and-improve/automate/advanced-workflow-building/agent.md).

# Agent

Add the generally available Agent node to a Workflow, configure its message, memory, tools and outputs, and test the result.

Use the **Agent** action when a Workflow needs to hand a task to the Project Agent rather than execute a fixed series of canvas actions. The Agent can use its available tools, integrations, Skills and files, then return results to the Workflow.

The Agent node is generally available. It replaces **Agent (legacy)** for new Workflows. Existing Workflows with the legacy node continue running; there is no automatic migration.

## Add an Agent action

1. Open the Workflow editor.
2. Select **Add Action** (or add an action from an existing card).
3. In the **AI** category, select **Agent**.
4. Enter a **Message** describing the work the Agent should do.
5. Bind any required inputs from earlier Workflow steps and test the action.

The Message is one task handed to the Agent. The Workflow waits for that Agent turn to finish before using its results in later actions.

## Configure the task

### Message and Skills

Use **Message** to supply the task, relevant Workflow variables and the expected outcome. It can contain values from previous actions.

Use **Add Skill** below the Message to reference an existing Project Skill. Unlike the legacy node, you do not configure a separate set of child action cards inside the Agent node. The Agent uses capabilities available through its Project, subject to the node's tool policy.

For example, an order-intake Workflow might ask the Agent to inspect an incoming order against the Project's customer and article rules and return the fields needed for the next step.

### Files

Use **Files** to attach files produced by earlier Workflow steps. Bind the relevant file variable or file array. The node accepts up to **10 input files**, with a maximum of **25 MB per file**.

### Output structure

Leave **Output structure** empty when a text reply is sufficient. Configure it when later Workflow actions need named, typed fields.

To add the first field in a new Output structure, select **Configure** to open the structure editor. The current **Add Field** control does not initialise an empty structure.

With an output structure, the Agent must submit a result matching that structure. Downstream actions can use the structured **result** rather than parsing the text reply.

### Model and thinking

The Agent uses the Project's default model unless you select an override. Where available, the **Thinking** option controls the reasoning preference for this turn. Selector availability depends on the corresponding feature settings.

**Current limitation:** After selecting a specific model, **Auto** is no longer offered in the model picker. Review your model choice before saving an override.

## Memory and tool access

Open **Memory and tools** for the execution policy.

| Setting                           | Behaviour                                                                                                      |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Memory — Project**              | Default. Reads and writes the shared Project Agent memory.                                                     |
| **Memory — Off**                  | This run does not recall or store Agent memories. It does **not** isolate tools, files or network access.      |
| **Tool policy — Inherit project** | Default. The Agent can use the tools and integration actions available to the Project Agent.                   |
| **Tool policy — Allowlist**       | Restricts optional tools to the listed **Allowed capabilities**. An empty allowlist permits no optional tools. |

Choose the narrowest access required for the task. The tool policy limits what the Agent may execute; it does not grant a Connection or expand permissions beyond the Project.

## Advanced settings

**Session ID** lets the action continue an existing Agent session. Leave it empty to start a new session for the run. Reusing a session also reuses its conversation context, so provide a Session ID deliberately.

**Maximum wait (ms)** controls how long the Workflow waits for the Agent turn. The default is **240,000 ms (4 minutes)**, with a maximum configurable wait of **280,000 ms**.

## Use the results

An Agent action can return:

* **output** — the text reply, when present;
* **result** — the structured value submitted to match Output structure, when configured;
* **files** — files the Agent produced and presented;
* **status** and **resultState** — execution and result classification;
* **agentSessionId** and **agentRunId** — identifiers for tracing the Agent execution.

A valid structured result or presented file can complete successfully without an ordinary text reply. If no usable text, files or required structured result is produced, the action fails explicitly rather than passing an empty success downstream. A missing or malformed structured result also fails.

Bind subsequent Workflow steps to the specific output they need. Do not assume an empty text reply means the Agent failed if it returned a valid structured result or file.

## Test before publishing

1. Run the Agent action with representative input data.
2. Inspect its output and, when applicable, the structured result and files.
3. Check the Agent execution evidence and verify any external changes in the source system.
4. Test the rest of the Workflow using those outputs before publishing.

**Current limitation:** The Project Agent can't run a Workflow that contains an Agent action, including one in a subworkflow the Workflow runs. When the Agent tries, the run is refused before any step runs, so nothing is executed or written. Test the Workflow end to end yourself with [**Run**](/build-and-improve/automate/test-and-publish/run-panel.md) in the Workflow editor; the Agent's message may call this **Try it**. The Agent can still [test the Skills](/build-and-improve/overview/test-and-improve-the-agent.md) the Agent action uses on their own.

When reviewing editor-run activity in **Monitoring**, change the Environment filter to **Builder**. The default **Live** filter does not include those test runs.

**Run** and **Test** can perform real actions in connected systems. Use safe test data and ensure write permissions and human approval boundaries are appropriate.

## Existing Workflows with Agent (legacy)

**Agent (legacy)** has been removed from the customer add-node picker. The older node is still retained for existing Workflows and for designated internal/Delta uses. Existing Workflows are not migrated automatically.

**Current limitation:** The **Basic Agent** starter template still inserts Agent (legacy). For a new Workflow, use **Add Action → AI → Agent** instead of that template.

The legacy node's configuration is different, including its inline actions/resources. Do not assume its settings map one-to-one to the new Agent node. When rebuilding a legacy Workflow, create a new Agent action in a Draft, bind the Message/Files/Output structure, choose the memory and tool policy, and test the resulting Workflow before publishing.

See [Agent (legacy)](/build-and-improve/automate/advanced-workflow-building/agent/agent-legacy.md) for the original node's configuration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lleverage.ai/build-and-improve/automate/advanced-workflow-building/agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.