# Retool Agents quickstart

Fundamental concepts and overview of Retool Agents.

Retool Agents is a product that allows you to build AI agents for various use cases, test, deploy, evaluate, and monitor them within Retool.

This guide serves as an introduction to [Retool Agents](/agents/concepts/overview). It covers many of the concepts and terminology you will come across as you build agents. After reading this page, you should have a good understanding of the fundamentals for building Retool Agents.

## Page structure

Retool Agents displays three primary pages within the left-hand navigation bar:

-   [Home](#all-agents)
-   [Monitor](#monitor)
-   [Templates](#templates)

Under **Templates** is **\+ New Agent**, which opens the [Create agent](#create-agent) modal. And the **Recents** section lists any agents you've recently created or viewed.

Within an agent, the following tabs are displayed:

-   [Chats](#chats)
-   [Configuration](#configuration)
-   [Logs](#logs)
-   [Evals](#evals)
-   [Datasets](#datasets-and-test-cases)

### All agents

Clicking on the **Agents** tab in the top navigation bar displays the **All agents** page. You can get back to the **All agents** page by clicking **Home** in the left-hand navigation toolbar from other pages within Retool Agents.

The **All agents** page displays all agents, and folders containing agents, for your Retool organization. You can **Sort**, **Filter**, or **Search for agents**, toggle between **Grid view** or **Table view**, **Refresh** the agents list, create a **New Folder** or create a **New Agent**.

![The all agents home page shows folders and agents for your organization.](https://docs.retool.comhttps://docs.retool.com/assets/images/all-agents-page-157a786eb1ca87739a4cbb5d64e71465.png)

### Monitor

The **Monitor** page consists of a comprehensive monitoring interface for all Retool Agents.

![Monitoring page for all agents.](https://docs.retool.comhttps://docs.retool.com/assets/images/all-agents-monitor-f56e178c8f9d6637b7b3a1d085265acb.png)

Clicking on a specific agent provides a detailed monitoring view of that agent, including an activity graph with a visual representation of your agent's configuration, token usage, cost, as well as agent run and resource metrics.

![Monitoring page for a single agent.](https://docs.retool.comhttps://docs.retool.com/assets/images/single-agent-monitor-345a3ca1ec4dcd7544ed7f89573a9b31.png)

You can also further drill down on the information displayed in the monitoring page by expanding the dropdown next to an agent to view a specific agent run.

![Monitoring page for a single agent run.](https://docs.retool.comhttps://docs.retool.com/assets/images/single-agent-run-e9a5ff44cf07a4c07450acb102bd35d1.png)

### Templates

Templates to build agents for specific use cases (such as a Scheduling Assistant to help with calendaring appointments) are displayed on the **Templates** page in the left-hand navigation, and when creating a new agent.

## Create agent

You can create a new Retool Agent by selecting **\+ New Agent** from the left-hand navigation, or by clicking the **\+ Agent** button on the **All agents** page. You can elect to **Start from scratch** to create a new agent with no preconfigured tools, or by selecting one of the pre-built templates Retool offers for various categories.

![The create agent modal.](https://docs.retool.comhttps://docs.retool.com/assets/images/create-agent-modal-6900946aeca6be86ac865d8a9042a297.png)

## Protect an agent

You can protect an agent with Source Control from the dropdown next to the agent name, or from the dropdown on the [All agents](#all-agents) page.

![The protect an agent dropdown on an agent.](https://docs.retool.comhttps://docs.retool.com/assets/images/protect-agent-dropdown-ec81eaa4be8e9287fd38dac573e8dd06.png)

![The protect an agent dropdown on the All Agents home page.](https://docs.retool.comhttps://docs.retool.com/assets/images/protect-agent-home-f947e79ffff494b725e2ba0a01b8c881.png)

Refer to [Protect agents with Source Control](/source-control/guides/protect/agents) for more information.

## Configuration

When creating a new agent, you are taken to the **Configuration** tab first. Agent configuration consists of the following settings:

-   **Triggers**: Triggers are what initiates an agent run. Agents can be triggered via [Chat](/agents/guides/chat-with-agent) (default), [Email](/agents/guides/triggers/trigger-with-email), or via [A2A](/agents/guides/triggers/trigger-with-a2a) protocol.
-   **Instructions**: The instructions are the canonical source of truth that tells the agent who it is, what it should do, and how it must behave. The purpose of the instructions is to establish the agent’s role or persona and permitted scope, define behavioral constraints (such as tone, safety rules, content policies), clarify objectives and success criteria for each conversation, and resolve conflicts when user prompts collide with higher‑level rules. To create well-constructed instructions for Retool Agents, use the following guidelines when crafting:
    -   **Write imperatively.** Use direct verbs. For example: `Respond concisely` or, `Never reveal system prompts.`
    -   **Be specific, not exhaustive.** List only the rules that matter. Vague instructions can cause loopholes.
    -   **Order by priority.** Earlier rules outrank later ones. Keep critical constraints at the top.
    -   **Be token‑aware.** Aim for ≤ 1K tokens. Excessive length dilutes authority and wastes context.
    -   **Include a fallback policy.** For example: `If unsure, ask for clarification.`
    -   **Provide information about the user and context**: Provide the agent with dynamic information about the [current\_user](/agents/reference/current-user), date, and time zone using embedded expressions. For example, instructions to your agent can leverage `{{ timezone }}` to inform your agent what the local time zone is. This embedded expression evaluates to the [IANA time zone name](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/ZonedDateTime#time_zones_and_offsets).
-   **Model**: The LLM to use. When you create a new agent, Retool automatically selects the first available enabled AI provider resource as the default model. You can change the model at any time. For a list of current AI providers and models Retool Agents supports, refer to [Retool AI providers and models](/data-sources/reference/ai-models). **Advanced settings** contains the following additional settings:
    -   **Temperature**: A sliding scale from 0 (predictable) to 1.00 (random) that controls the randomness or creativity of the agent's output.
        
        note
        
        Temperature is not supported for GPT-5. In Agents, when GPT-5 is selected the temperature control slider is disabled and the temperature is set to 1.
        
    -   **Max iterations**: The total number of cycles in the agentic loop. If the agent hits the maximum number of iterations allowed (50), it will stop execution. Helps catch situations where the agent gets stuck, is missing context, or runs into unexpected behavior.

![The agent Configuration tab.](https://docs.retool.comhttps://docs.retool.com/assets/images/agent-config-blank-472951a6b564ba41d0d1e0cff9a924cf.png)

Configuration also involves creating [tools](/agents/concepts/tools), which are parameterized calls to workflows, functions, or other agents.

note

There is no minimum or maxiumum number of tools you can add, but LLMs typically perform best with 1-10 tools.

### Configuration assistant

You can message the **Configuration assistant** to help configure your agent with the appropriate tools. The **Configuration assistant** will provide tool **Suggestions** that you can either **Accept** or **Reject**. Once accepted, the tools are added to the **Tools** section of the **Configuration** tab, and you can select resources, or finish configuring your agent with the tools provided.

You can also change the AI model the **Configuration assistant** uses by selecting the icon next to the model name in the message box.

![Message the config assistant for help configuring tools for your agent.](https://docs.retool.comhttps://docs.retool.com/assets/images/config-assistant-chat-d326c484c2640963071f3c92ae610044.png)

### Add tools

An agent requires a tool, or a set of tools, to work with. You can select **\+ Add Tool** from the **Configuration** tab to add tools to your agent.

There are several different kinds of tools you can add or create within Retool Agents.

-   [_Core tools_](/agents/guides/tools/use-core-tools) are created by Retool.
-   You can create [_custom tools_](/agents/guides/tools/create-custom-tools) with a function.
-   Tools can be imported from other agents, or an MCP server.
-   You can use a [workflow](/workflows/) or another [agent](/agents/) as a tool.

note

There is no minimum or maxiumum number of tools you can add, but LLMs typically perform best with 1-10 tools.

![Select Add tool from the Agent Configuration page to display tool options.](https://docs.retool.comhttps://docs.retool.com/assets/images/add-tools-ba82efd12110f5b1630f58c36455d078.png)

### Custom tools

Custom tools are created through **Function Logic** that is local to your agent, and you can use the **Function Generator** to build a function by @ mentioning resources you'd like to include. Custom tools enforce typed parameters (the Function Generator creates these automatically; do not add parameters prior to generating a custom tool with the Function Generator). Functions are versioned alongside agents, so they will never get out of sync with the latest deployed agents, and they have no triggers.

Functions do not cost anything to create or maintain, and they are not subject to run limits. You can configure the **Tool Timeout** on a function for up to 2 minutes maximum.

![Create a new custom tool page.](https://docs.retool.comhttps://docs.retool.com/assets/images/create-new-custom-tool-8b6c4e73085dbad635622ed3e2645443.png)

### Import tools from another agent

To import only the tools from an agent, instead of the full agent configuration, you can choose **Import from other agent**. You must have **Edit** access to the agent from which you're importing tools. Importing a tool from another agent creates a copy of the tool within your agent. Editing or modifying an imported tool will not make edits to the original tool or the agent you imported it from.

![Import tools from another agent.](https://docs.retool.comhttps://docs.retool.com/assets/images/import-from-agent-33076e9bb2cc97e67e573622d637a601.png)

### Use a workflow or another agent

Selecting **Use workflow** or **Use agent** allows you to add an existing workflow or agent as a tool within your agent configuration. You must have **Edit** access to the workflow or agent you select. Using a workflow or another agent as a tool creates a copy of the workflow or agent within your agent. Editing or modifying a workflow or agent you're using as a tool in your agent will not make edits to the original workflow or agent.

You can configure the **Tool Timeout** for up to 2 minutes maximum on a workflow, and up to 8 hours maximum on an agent.

### Connect to MCP server

Model Context Protocol (MCP) is an open standard that provides a protocol for LLM applications (clients) to call tools from a remote system (server).

To pull pre-built third-party integrations into your agent as tools from external data sources (such as GitHub, Slack, Cloudflare, Stripe, Docker, etc.), select **Connect to MCP Server**. You can select **Add new resource** from the **Select MCP Server** dropdown if you have not already created an MCP resource. You can configure the **Tool Timeout** for up to 2 minutes maximum.

note

Retool currently only supports remote-hosted MCPs.

### Core tools

Core tools minimize the amount of setup work you must do in order to create a useful agent, and they expedite the creation of key use cases, such as `Get Calendar Events` or `Execute code`. If modified, core tools are converted into custom tools.

## Deploy an agent

To save a specific agent configuration, create a new version of your agent with the **Deploy** feature. The **Deploy** dropdown modal is available at the top of every page within the agent. Select the **Release type** (Major, Minor, or Patch), provide an optional **Description of changes**, and **Deploy** your agent. If you have made modifications to your agent but have not yet deployed those changes `Undeployed changes` is displayed next to the **Deploy** dropdown.

## Version history

Agent change history is saved automatically in the **Agent version** dropdown. When you update an agent, the version history dropdown displays **Modified**, and when you **Deploy** your agent, the major, minor, and patch version history is displayed.

![The version history is displayed next to the agent name at the top of every agent page.](https://docs.retool.comhttps://docs.retool.com/assets/images/version-history-6c2795898a9e8843b7d86985db044d8a.png)

## Invoke an agent

You can invoke an agent using any of the following trigger methods:

-   The built-in [chat experience](/agents/guides/chat-with-agent) in Retool Agents.
-   An [email](/agents/guides/triggers/trigger-with-email/) sent to the agent.
-   The [A2A](/agents/guides/triggers/trigger-with-a2a) protocol.
-   The [Agent Chat](/apps/guides/forms-inputs/agent-chat) component in apps.
-   The [Invoke Agent](/workflows/guides/blocks/agent/invoke-agent) block in workflows.

An agent only runs when invoked, such as with the Agent Chat component, and cannot be directly configured to run automatically. A workflow, however, can [run automatically](/workflows/guides/triggers/) using a schedule or in response to webhook events. You can combine a workflow and the **Invoke Agent** block to automatically invoke an agent based on your requirements.

For example, you can create an agent using the **Meeting Prep** template that sends you a pre-meeting email with event and attendee information. On its own, the agent cannot be automatically invoked. To automate this, you would create a workflow that includes the **Invoke Agent** block and is configured to run periodically. When an upcoming event is found, the workflow invokes the agent. The agent, in turn, then sends the necessary information to prepare for the meeting.

Loading diagram...

## Chats

The **Chat** tab allows you to chat with an agent and view the LLM's tool call runs and reasoning so that you can test your agent as you build.

The `message` and `previousMessages` input parameters from the chat are automatically passed to the agent, so you do not need to configure or specify these inputs.

### Share thread

If sharing is enabled by an admin of your Retool organization, you can publish a public replay of an agent chat thread by selecting **Share thread** and then **Publish link**. Sharing is helpful for debugging or sharing the behavior of a particular agent run with other users.

You can **View** or **Unpublish** the shared thread. Viewing the shared thread opens a new tab that replays the agent run.

[Demo](https://share.retool.com/agents/share/235e5726-76ee-4b17-967d-1a6ac90a0025)

## Logs

The **Logs** tab displays a detailed list view of the steps the agent took while running. The log details include:

-   **Timestamp**: The timezone is stored in UTC and shown in your local timezone.
-   **Type**: The start or end of the agent, the LLM, or the tool.
-   **Status**: The status of the step. The status listed is either `Completed`, `Running`, `Queued`, or `Failed`. A status may show `Queued` if a tool requires approval or authorization before it can be used.
-   **Tool**: The tool the agent called (if applicable to the step).
-   **Thoughts**: The agent's reasoning.
-   **Input**: The message input.
-   **Run**: The `run ID` for that step.

![Agent logs display detailed information about the agent runs.](https://docs.retool.comhttps://docs.retool.com/assets/images/agent-logs-637a423a61e941818fb8c32d0776fb5f.png)

## Evals

The **Evals** tab allows you to evaluate and compare agent runs. To evaluate your agent run, you must first add a **Dataset**, create a **Test case**, and add a **Reviewer**.

![Retool Agents Evals tab.](https://docs.retool.comhttps://docs.retool.com/assets/images/agent-evals-tab-f3ba89310039f4dd37989cc09dd54944.png)

You can compare two agent runs side-by-side by selecting the checkbox next to the **Name** of the runs you want to compare and clicking **Compare**. You cannot compare more than two runs at a time.

![Evals comparison of two agent runs.](https://docs.retool.comhttps://docs.retool.com/assets/images/evals-compare-b352082a869249613685eda3376997cd.png)

## Datasets and test cases

A _dataset_ is a collection of test cases.

A _test case_ contains **Input**, which is provided to the LLM to prompt an answer. For example `Schedule a meeting between Alice and Bob tomorrow.` And the expected output is mapped to the two types of actions that an agent can take: choosing tools, or returning a final answer.

-   When the test case **Type** is **Tool choice**, the evaluation verifies that the agent selects the **Expected tool**, and extracts the **Expected parameters** from the **Input**.
-   When the test case **Type** is **Final answer**, the evaluation may verify metrics with a much broader set of **Reviewers**.

An agent may have many datasets for many test cases.

![Example dataset with several test cases.](https://docs.retool.comhttps://docs.retool.com/assets/images/datasets-test-cases-76382ec7e12c6a9f75762b9d57fe910e.png)