Retool Agents tutorial

Create a Retool Agent from scratch.

Retool Agents is currently in public beta on Retool Cloud.

Retool Agents enable you to create AI agents that can think, reason, and call tools independently. They take actions and complete or delegate tasks that you assign them during configuration.

This tutorial walks you through the process for building an agent that aggregates new Retool changelog posts and release notes for a specified date range and sends you a digest email.

1. Create a new agent

To create a new agent, sign in to your Retool organization, and select the Agents tab in the top navigation bar.

From the All agents page, click the + Agent button.
Select Start from scratch and click Create.
In the Agent name field, enter Retool Digest.
In the Description field, enter Retool release notes and changelog updates and click Create.

2. Configure your agent

The Configuration tab is where you input the Instructions your agent uses to help the AI Model you select think and reason as it calls tools.

When creating a new agent, you can pass references to current_user, {{ timezone }}, and {{ new Date() }} into the instructions 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.

For this tutorial, replace the default text in the Instructions field with the following:

You are an assistant that provides Retool updates. Summarize all of the new release notes and changelog entries at Retool for a given date range and send an email.

1. Collect and summarize:
- Release notes
- Changelog entries

2. Format the email digest as follows:
The subject line: Retool Updates

The Date Range provided by the user.

The body of the email should contain the following sections:
📦 New Releases
- Provide a bulleted list of updates for Edge and Stable Release Notes and include direct links to the full content.
- Links for Edge Release Notes should link to this page: https://docs.retool.com/releases/edge/all
- Links for Stable Release Notes should link to this page: https://docs.retool.com/releases/stable/all
- Each bulleted list item should have a title, a summary of the release notes, and the date the release notes were published.
- If there are no release notes for Edge or Stable for a given week, say `No new items this week`.

📝 Changelog
- Provide a bulleted list of changelog entries, and include direct links to the full content.
- Each bulleted list item should have a title, a summary of changelog item, and the date of the changelog.
- If there are no changelog entries for a given week, say `No new items this week`.

3. Always include:
- Links to the Release Notes: https://docs.retool.com/releases and the Changelog: https://docs.retool.com/changelog at the bottom of every email

4. Always send an email to {{ current_user.email }}

Keep summaries concise and highlight breaking changes or major features.

Retool's Best Practices page offers additional guidance about creating clear instructions for your agent to follow.

In the Model setting, select the AI model you want to use. For this tutorial, use the Retool-managed Anthropic model: Claude 3.7 Sonnet. Results may differ if you select a different model.

You must have Retool AI enabled, and the Retool-managed Anthropic key must be enabled by an admin of your organization for Anthropic models to appear in the model selection dropdown.

You can interact with OpenAI, Anthropic, DeepSeek, and Llama 4 models using either a Retool-managed connection or with your own credentials. Retool recommends using Retool-managed connections for testing and development purposes.

3. Connect tools to your agent

There are several kinds of tools that Retool Agents can consume and use. For this tutorial, you're going to add prebuilt tools, and create custom tools.

For more information about tools, refer to the Tools conceptual guide.

You can also chat with the Config Assistant, which helps you configure your agent by suggesting tools and automatically populating your configuration with them if you accept the suggestion. Depending on the AI model used, you may have varying results, and automatically generated tools may need to be refined.

Add core tools

Core tools are created by Retool to provide you out-of-the-box tool functionality for common tasks, like updating a Google Calendar or Executing Code.

To add core tools:

Click Add Tool and click the + on the Send Email tool and the Get Webpage Content tool. A green check mark will appear to notify you that the tools have been selected.
Click the Add 2 tools button. The number changes depending on how many tools are selected.
The Send Email and Get Webpage Content tools are displayed in the Tools section of the Configuration tab.

Convert core tool to custom tool

When you edit a core tool, Retool Agents automatically converts it to a custom tool, and you can edit the Function Logic. You will be prompted with a warning message when converting a core tool.

Click to expand the Get Webpage Content tool, and click the Edit ( ) icon.
Click Continue on the warning message that pops up.
Select Edit function in the Function Logic section.
In the Resource query block labeled getContent, replace {{ params.url }} with the Edge Release Notes text-only URL: https://docs.retool.com/releases/edge/all.
Add another Resource query block in between getContent and parseHTML. Choose the REST API resource query type, and GET the Stable Release Notes text-only URL: https://docs.retool.com/releases/stable/all.

Replace the JavaScript in the parseHTML block with the following:

function cleanHtmlWithHeaderLinks(rawHtml) {
// 1. Remove <head>, <script>, <style>, <noscript> and their content
let html = rawHtml
    .replace(/<head[\s\S]*?<\/head>/gi, "")
    .replace(/<(script|style|noscript)[\s\S]*?<\/\1>/gi, "");

// 2. Find headers and replace with markdown links
// Matches <h1 id="foo">Bar</h1> or <h2>Bar</h2>
html = html.replace(/<h([1-6])([^>]*)>([\s\S]*?)<\/h\1>/gi, (m, level, attrs, content) => {
    // Try to extract id attribute
    let idMatch = attrs.match(/\sid=["']?([^\s"'>]+)["']?/i);
    let id = idMatch ? idMatch[1] : null;
    // If no id, generate from content
    let text = content.replace(/<[^>]+>/g, '').trim();
    let anchor = id || text.toLowerCase().replace(/[^\w\- ]+/g, '').replace(/\s+/g, '-');
    // Markdown header link: [Header Text](#anchor)
    return `\n[${text}](#${anchor})\n`;
});

// 3. Mark block-level tags as line breaks
const blockTags = [
    "address","article","aside","blockquote","canvas","dd","div","dl","dt","fieldset",
    "figcaption","figure","footer","form","hr","li","main","nav",
    "noscript","ol","p","pre","section","table","tfoot","ul","video","br","tr","td","th"
];
const blockRegex = new RegExp(`<(?:${blockTags.join("|")})\\b[^>]*>`, "gi");
html = html.replace(blockRegex, "\n");

// 4. Strip all remaining tags
html = html.replace(/<[^>]+>/g, "");

// 5. Decode numeric entities (decimal & hex)
html = html
    .replace(/&#(\d+);/g, (_, dec) => String.fromCharCode(dec))
    .replace(/&#x([0-9A-Fa-f]+);/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)));

// 6. Decode common named entities
const entityMap = {
    nbsp: " ", lt: "<", gt: ">", amp: "&", quot: '"', apos: "'",
    mdash: "-", ndash: "-", hellip: "…", rsquo: "’", lsquo: "‘",
    ldquo: "“", rdquo: "”"
};
html = html.replace(/&([a-zA-Z]+);/g, (_, name) =>
    name in entityMap ? entityMap[name] : `&${name};`
);

// 7. Collapse whitespace and blank lines
const text = html
    .split("\n")
    .map(line => line.replace(/\s+/g, " ").trim())
    .filter(line => line.length > 0)
    .join("\n");

// 8. Merge short lines
const threshold = 80;
const lines = text.split("\n");
const merged = [];

for (const line of lines) {
    const trimmed = line.trim();
    if (!trimmed) continue;

    if (merged.length === 0) {
    merged.push(trimmed);
    } else {
    const prev = merged[merged.length - 1];
    if (trimmed.length < threshold) {
        merged[merged.length - 1] = prev + " " + trimmed;
    } else {
        merged.push(trimmed);
    }
    }
}
return merged.join("\n");
}

// Defensive: Fallback to empty strings if undefined at any level
const rawHtml1 = getContent?.data?.message || '';
const rawHtml2 = query1?.data?.message || '';

const text1 = rawHtml1 ? cleanHtmlWithHeaderLinks(rawHtml1) : '';
const text2 = rawHtml2 ? cleanHtmlWithHeaderLinks(rawHtml2) : '';

const finalText = [text1, text2].filter(Boolean).join('\n\n');
return finalText;

Click Done.
Click the back button to go back to the Edit Tool page, and click Save.

Create a custom tool

In this section, you'll create a custom tool to fetch the Changelog JSON feed. You can make a custom tool by creating a function. For more information about functions, refer to the Functions page.

From the Configuration tab, click Add Tool.
Select Create new custom tool.
In the Name setting, enter fetchFromChangelog
In the Description setting, enter Searches for and filters changelog entries by user-provided date range.

Click Add parameter twice. Click to update it. Configure the following parameters:

Name	Type	Description	Required
`startDate`	String	The start date (inclusive) for filtering entries, in YYYY-MM-DD format.	Yes
`endDate`	String	The end date (inclusive) for filtering entries, in YYYY-MM-DD format.	Yes

Select Edit function in the Function Logic section.
Delete the code1 block. Click and drag from the Parameters block. Create a Resource query block with the REST API resource type to GET the JSON feed for the Changelog: https://docs.retool.com/changelog/feed.json. Name it getChangelogEntries.

You can also message the Function generator and @ mention the Changelog resource. The function generator will automatically create the function and the parameters for your tool, but depending on the model you use you may have varying results and need to troubleshoot the code that's generated.
From getChangelogEntries, click and drag to add a Code block. Replace the default code with the following JavaScript:
```
return getChangelogEntries.data.items
```
From the Code block, click and drag to add a Filter block with the following Expression to use the moment() date library to match any posts within the specified range:
```
moment(value.date_modified).isBetween(moment(params.startDate), moment(params.endDate))
```
From the Filter block, click and drag to add a Response block with a Status code of 200 and the following Return body:
```
filter1.data
```
Click Done.
On the Edit Tool page, click Save.

4. Deploy your agent

Now that you've configured your first agent, it's time to deploy it.

On the Configuration tab, click the Deploy button.
Select the Major version radio button and add a Description.
Click Deploy.

5. Test your agent

To test your agent and ensure it's working as intended, chat with it.

Select the Chats tab.
Message your agent with the following, changing the date as needed. Ensure you include the correct year.
```
What's my weekly digest for April 28th through May 2nd, 2025?
```
Your agent will display thoughts and provide Tool chips in the chat thread and in the side bar as it runs so you can see which tools were called, the parameters that used, and the result. You can toggle Hide or Show thinking for the tool chips in the side bar, depending on your preference.

When your agent has finished running and provided a final answer, you should have an email in your inbox with your weekly digest, and it will also display the results in the message thread, and should look similar to the below.

I've sent your Retool Weekly Digest for April 28 - May 2, 2025 to your email. The digest includes:

One Edge version released on April 30, 2025

Five changelog entries covering new features and improvements, including:
Record user sessions with Fullstory (May 1)
Backend runtime upgrade to Node.js v20.18 (April 30)
Disable catch-up commits in Source Control (April 29)
Multi-step functions now generally available (April 28)
Error reporting for Retool Workflows (April 28)

Your digest has been delivered successfully. Let me know if you need anything else!

To make your thread public and share it with another user, click Share thread and then click Publish link.

You can continue chatting with your agent, and check the Logs to test any modifications you make to the tools or agent configuration, or you can revert to previous deployed versions from the version history displayed next to the name of your agent.

Wrap up

At this point, you should be able to configure an agent, add prebuilt and custom tools to an agent, deploy an agent, and chat with an agent to test how it performs.

To continue learning about agents, explore the following resources:

1. Create a new agent​

2. Configure your agent​

3. Connect tools to your agent​

Add core tools​

Convert core tool to custom tool​

Create a custom tool​

4. Deploy your agent​

5. Test your agent​

Wrap up​