Configure your organization for Agents

Learn how to configure Agents for cloud and Self-hosted deployments.

Agents Availability
Cloud	Public beta	Available on all plans
Self-hosted Edge 3.234 or later	Public beta	Available on all plans
Self-hosted Stable 3.253 or later	Public beta	Available on all plans

An organization admin must complete the steps in the following sections to make sure your organization is ready to use Agents.

To learn how to create and use agents, visit the Agents quickstart or the Agents tutorials.

Configure organization settings

Ensure that Agents is enabled and that it has access to the proper AI models.

1. To ensure your users can access Agents, navigate to Settings > AI. Verify that the Retool AI and AI Agents settings are toggled on.
2. Navigate to Resources > Retool AI. Ensure that at least one AI provider is enabled. You can choose to use Retool-managed keys or self-managed keys.

Only AI models that support tool creation can be used with Agents. Refer to AI providers and models for supported models.

Self-hosted configuration

Complete the steps in the following sections if your deployment is self-hosted. Skip these steps if you use Retool cloud.

Requirements

To use Agents on Self-hosted deployments, your organization must:

• Be on Self-hosted Retool version 3.234.0 or later (3.253.0 or later for stable releases).
• Have its own AI model key(s) configured.
• Meet all of the requirements outlined in the tutorial for your chosen deployment infrastructure.

Installation

Agents is supported for the following self-hosted deployment options.

AWS Fargate and ECS

Follow the instructions outlined in the AWS Fargate and ECS tutorial.

Docker Compose

Follow the instructions outlined in the tutorial corresponding to your deployment infrastructure:

• Amazon EC2
• Azure Virtual Machines
• Docker
• Google Compute Engine

Kubernetes with Helm

To deploy a Self-hosted Retool instance that contains agents, use the Retool Helm chart 6.6.0 or later.

Configure the values.yaml file as follows:

1. In the image.tag for the tryretool/backend and tryretool/code-executor-service, specify the Docker tag for the version of Retool to install, such as tryretool/backend:3.300.5-stable.

   Agents is available on self-hosted Retool version 3.253.0-stable or later.

2. Set agents to enabled: true.

For further configuration, you can reference the full agents: block as defined in retool-helm.

Additional configuration

Agents on self-hosted deployments rely on Temporal. To deploy agents, you must create two additional containers with configuration and networking egress identical to the workflows-worker container:

Container	SERVICE_TYPE Environment Variable 1	Networks	Dependencies	Restart Policy
agent-worker	WORKFLOW_TEMPORAL_WORKER	backend, code-executor	postgres	always
agent-eval-worker	AGENT_EVAL_TEMPORAL_WORKER	backend, code-executor	postgres	always

The infrastructure of the Agents edge deployment is very similar to a Retool deployment with workflows. The following example code block shows the agent-worker and agent-eval-worker container configuration for a Docker Compose deployment.

docker-compose.yaml example

services:
  # Temporal workers for Agents
  agent-worker:
    build:
      context: .
    env_file: docker.env
    environment:
      - SERVICE_TYPE=WORKFLOW_TEMPORAL_WORKER
    networks:
      - backend
      - code-executor
    depends_on:
      - postgres
    restart: always

  agent-eval-worker:
    build:
      context: .
    env_file: docker.env
    environment:
      - SERVICE_TYPE=AGENT_EVAL_TEMPORAL_WORKER
    networks:
      - backend
      - code-executor
    depends_on:
      - postgres
    restart: always

Using a Retool-managed agents observability API is required in the edge release. This API strictly does not receive, persist, or have access to sensitive customer data, agent inputs, or agent outputs. It is required to power the Monitor dashboard.

Set up evals

Evals work in self-hosted deployments without any special configuration. To optimize performance, you can configure Amazon Simple Storage Service (Amazon S3) to store test case inputs and outputs (which can be large) instead of Postgres. To use Amazon S3, first configure Amazon S3 as a resource, and then set the following environment variables:

  # Replace the following example values with your S3 values.
  AGENT_EVALS_S3_BUCKET='retool-agent-evals'
  AGENT_EVALS_S3_ACCESS_KEY_ID='AKIAIOSFODNN7EXAMPLE'
  AGENT_EVALS_S3_SECRET_ACCESS_KEY='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'
  AGENT_EVALS_S3_REGION='us-west-2'

Configure AI providers

After installation, navigate to <your domain>/resources/retool_ai and configure one or more AI model providers.

Choose a change management strategy

Agents can be versioned and protected using Retool's change management features:

• Source Control: Organizations on the Enterprise plan can use Source Control to protect agents and manage changes through Git workflows. Consider creating feature branches when making significant changes to agents.
• Version History: All changes to agents are automatically tracked in version history, allowing you to review and restore previous versions.

Track usage

Organization admins can monitor Agents usage and costs.

Monitor agent runs

Use the Monitor dashboard to track:

• Agent run success or failure rates
• LLM token usage
• Runtime performance
• Tool invocations

Billing and usage limits

Retool organizations receive up to $50 worth of agent runtime per month. For Self-hosted deployments using self-managed LLMs, this equals 10 hours of free usage per month at $5/hour.

If you exceed the cap, agents will not execute and you'll see a warning message. Contact your account team to discuss additional capacity.

For more information about pricing, refer to the Model pricing and the Agents billing and usage pages.

Next steps

Once configuration is complete:

1. Create your first agent using the Agents tutorial page.
2. Configure agent tools to connect to your data sources.
3. Set up permissions to control who can create and use agents.
4. (Optional) Configure email triggers or A2A triggers for automated agent invocation.
5. For answers to common questions about Agents, review the Agents FAQ.

Footnotes

1. For a complete list of Agents-related environment variables, refer to the Environment variables reference. ↩