Create agentic workflows with the Invoke Agent block

Learn how to call an agent from a workflow.

Use the Invoke Agent block to trigger a Retool Agent from a workflow. Invoking an agent from a workflow creates an agentic workflow. Refer to the conceptual guide on agentic workflows for more information.

Some tools require user approval or authentication to execute. These tools are not available in agentic workflows.

This guide provides instructions on how to invoke an agent and retrieve its results. Click the following link to download a sample workflow in JSON form and import it as a new workflow. Configure the workflow to call your own agent.

Sample Workflow

Prerequisites

Before you create an agentic workflow, you must first create an agent. Refer to the Retool Agents tutorial for more information.

Invoke agent

Complete the following steps to add and configure an Invoke Agent block:

Click and drag to create a new, connected block.
Select Invoke Agent as the type of block.
Set Agent to the agent you want to call.

Define your agent input using the Agent Inputs setting.

Your agent input must be in the following format:

{
  "messages": [ 
    { 
      "role": "user",
      "content": "The message you want to send to the agent." 
    }
  ], 
  "action": "invoke" 
}

Replace the content value with the text that you want to use to prompt the agent. For example:

{
  "messages": [ 
    { 
      "role": "user", 
      "content": "What's the weather tomorrow in NYC?" 
    } 
  ], 
  "action": "invoke" 
}

Running this resource query block returns a response in the following format:

{
  "data": {
      "agentRunId":"0196d548-c38a-74ac-91bf-ab1a2412fd75",
      "agentId":"1bb4e629-26be-42a2-8388-6c67cb6c73e6",
      "status":"PENDING"
  }
}

The invoke agent call

Write a multi-step function to retrieve the agent updates

Next, utilize a multi-step function to retrieve the agent's response. If you don't need the results of the agent to continue with the workflow, you can skip these steps.

Create a new function, and name it getAgentLogs.
Add two parameters: agentRunId and agentId.
Set the Type to Multi-step. Click the Edit function button to navigate to the multi-step function control flow.
Click and drag to create a new, connected block.
Select Invoke Agent as the type of block. Name the block requestAgentLogs.
Set Agent to the agent you want to call.
Set Agent Inputs to the following:

{ 
  "action": "getLogs", 
  "agentRunId": {{ params.agentRunId }} 
}

Add a Response block with a Status code of 200 and return the following: requestAgentLogs.data.

The multi-step function

Poll the agent for results

The time period it takes to receive a result from an agent can vary widely based on a variety of factors, including the model used, the number of tools called, and the type of reasoning performed. If you need to use the outcome of your agent call in the workflow, you need to poll the agent for results. There's no need to do this if you are simply using the workflow to trigger the agent invocation.

Click and drag to create a new, connected block.
Select the Code block type, and name the block pollForAgentLogs.
Paste in the following JavaScript code snippet to populate your block:

// Defines the polling interval (500ms), the max number of attempts (30), and the statuses that indicate the agent is still running (PENDING, IN_PROGRESS).
const SLEEP_DURATION_IN_MS = 500;
const MAX_ITERATIONS = 30;
const AGENT_PENDING_STATUSES = ["PENDING", "IN_PROGRESS"];

// A utility function that returns a promise which resolves after 500ms (used for pausing between polls).
const sleep = () => new Promise(resolve => setTimeout(resolve, SLEEP_DURATION_IN_MS));

// Extracts the agentId and agentRunId from the invokeAgent block. Initializes latestAgentStatus as "PENDING". latestAgentLogs will store the last retrieved logs, and iterations tracks the number of attempts.
const { agentId, agentRunId } = invokeAgent.data;
let latestAgentStatus = "PENDING"; // Initial assumption
let latestAgentLogs;
let iterations = 1;

// Keeps polling as long as the agent is in a pending state and hasn’t exceeded the maximum attempts.
while (AGENT_PENDING_STATUSES.includes(latestAgentStatus) && iterations <= MAX_ITERATIONS) {
  console.log(`Beginning iteration ${iterations}/${MAX_ITERATIONS}`);

  try {
    // Call the multi-step function
    const agentLogs = await getAgentLogs(agentRunId, agentId);
    console.log({ agentLogs });
    latestAgentStatus = agentLogs.data.status;
    latestAgentLogs = agentLogs;
  } catch (err) {
    throw new Error(`Failed to fetch agent logs on iteration ${iterations}: ${err.message}`);
  }

  // If still pending, wait before the next iteration. If not, exit the loop early.
  if (AGENT_PENDING_STATUSES.includes(latestAgentStatus)) {
    await sleep();
  } else {
    break;
  }
  iterations += 1;
}

// If the status is still not complete after 30 tries, throw an error.
if (AGENT_PENDING_STATUSES.includes(latestAgentStatus)) {
  throw new Error(`Agent status is still ${latestAgentStatus} after 30 polling ${MAX_ITERATIONS} attempts.`);
}

// Return the agent response.
return latestAgentLogs;

Handle responses

Finally, set your workflow up to gracefully handle success and failure.

To return a successful response:

Click and drag to create a new, connected block.
Chose the Response type.
Set the Status code to 200.
Paste the following code in the Return body field:

{
status: pollForAgentLogs.data?.data?.status,
resultText: pollForAgentLogs.data?.data?.resultText,
fullLogsResponse: pollForAgentLogs.data
}

To handle a failure:

Right-click on the canvas to create a block that is not connected to the rest of the control flow.
Chose the Response type.
Click the ••• menu and select Add global error handler. This setting configures the block as an error handler that applies to the full workflow.
Set the Status code to 400.
Paste the following code (or something similar) in the Return body field:

workflowContext.currentRun.error

Agent responses

Test out your workflow by clicking the Run button before you deploy it.

Add triggers

Like any other workflow, you can add triggers to run your agentic workflow. Note that if you create a webhook trigger, anyone with access to the webhook will be able to trigger your agent.

Configure block settings

Refer to the Wait block reference for information about the block's settings.

Prerequisites​

Invoke agent​

Write a multi-step function to retrieve the agent updates​

Poll the agent for results​

Handle responses​

Add triggers​

Configure block settings​