Retool Agents best practices

Best practices for Retool Agents.

Version: Cloud and 3.234 Edge

Retool Agents is currently in public beta on Retool Cloud.

Retool recommends using the following best practices to create operationally efficient, cost-aware, performant, reliable, secure, and sustainable agents.

Operational excellence

Best practices for operating Retool Agents effectively include implementation strategies, monitoring, and continuous improvement methodologies.

Test with the Chat feature

Test agents using the built-in chat interface, which uses the latest saved version, before deploying to users.

Use logs for monitoring and debugging

The agent logs provide run details including inputs, outputs, thoughts, and runtime information helpful for debugging tool and LLM calls.

Use Evals to optimize agents

Use evals for systematic testing of agent behavior after significant changes to instructions or tool descriptions, ensuring consistent performance and quality across scenarios.

Monitor your agents

Use the monitoring page to observe agents in production, providing visibility into runs, errors, tool calls, token usage, cost, runtime and more.

Cost optimization

Best practices on managing and optimizing costs associated with Retool Agents include resource allocation, usage patterns, and budgeting considerations.

Write clear instructions

Clear instructions allow the agent to optimally choose tools and iterate the fewest number of times, reducing total runtime and associated costs.

Write detailed and specific tool descriptions

Clear, short, specific tool descriptions allow the agent to optimally select its execution path, reducing unnecessary tool calls and iterations.

Be token aware

Consider the total size of responses from your tool calls. Returning large amounts of data results in token-inefficient LLM calls, so wherever possible, minimize the data returned from tools.

Choose the fastest capable model

Select the fastest model that can effectively solve your particular problem to minimize total runtime and associated costs.

Performance

Best practices for performance include strategies and techniques to maximize the performance of Retool Agents, including response-time optimization, and throughput considerations.

Reduce the amount of agent tools

Connect only the necessary tools to each agent.

Implement timeouts and fail-fast strategies

Set clear timeout thresholds for each tool to prevent long-running tool calls from degrading overall agent responsiveness.

Instruction guidance

In general, Retool Agents perform best when they have a set of well-written instructions. Use the following best practices to create instructions with Retool Agents:

• Explicitly state the agent's purpose: Clearly specify the agent's role and goals upfront to ensure alignment.

  Example

  You are a data analyst agent tasked with identifying anomalies in daily sales data.

• Break down tasks clearly: Provide step-by-step guidance to simplify complex instructions into manageable steps.

  Example

  1. Pull sales data from the provided database.
  2. Calculate the weekly average sales figures.
  3. Identify any days with sales deviations greater than ±15% from the weekly average.

• Be precise: Explicitly state validation rules and decision-making criteria. Include relevant context directly in each instruction; avoid relying on prior prompts or implicit context.

  Example

  All phone numbers must contain exactly 10 digits. If a provided number doesn't meet this criterion, flag it and request correction.

• Include explicit error handling guidance: Clearly state how the agent should handle errors, edge cases, or unexpected scenarios.

  Example

  If data retrieval fails due to an API error, notify the administrator immediately with the specific error message and retry once after 5 minutes.

• Provide information about the user and context: Provide the agent with dynamic information about the 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.

  Example

  You are a helpful assistant chatting with {{ current_user.name }}. Today is {{ new Date() }} in the {{ timezone }} time zone.

Refer to the Configuration section of the Quickstart guide for additional instruction guidance.

Example instructions

You can use the following examples as templates when creating instructions for Retool Agents.

Task-specific

You are a data analysis assistant. When analyzing the provided dataset:
1. First identify the key metrics present
2. Calculate relevant statistical measures
3. Present insights in bullet points
4. If you spot any anomalies, highlight them separately

Context-rich

You are helping with Retool app debugging. Given the error message:
- First identify the component type involved
- Check for common configuration issues
- Suggest specific fixes
- Provide example code if relevant
Only use features available in the current Retool version.

Role-based

Act as a SQL query optimizer. For any query provided:
1. Analyze the query structure
2. Identify potential performance bottlenecks
3. Suggest specific optimizations
4. Explain the reasoning behind each suggestion

Common issues with instructions

The following table provides some common pitfalls or issues you may encounter when crafting instructions for agents, as well as do's and don'ts for instruction writing.

Issue	Do	Don't
Vague or ambiguous instructions	Write specific, clear instructions, that include numbers or percentages if necessary.	Write vague or short instructions that don't provide enough context for the model.
Providing too much information	Provide only the context directly relevant to the current task.	Include unnecessary historical context or irrelevant details.
Lack of error handling guidance	Point out what the agent should do if it encounters missing data or errors when running.	Fail to specify how to handle edge cases or errors.
Inconsistent output requirements	Clearly define output format upfront and maintain consistency.	Fail to specify response format or change format requirements mid-conversation.
Assuming prior context	Include necessary context in each instruction, even if briefly.	Refer to information from previous conversations without restating it.
Imprecise tool usage	Specify which tool to use for certain tasks.	Fail to specify which tools the agent should use for specific tasks.
Missing validation requirements	Include specific validation criteria and acceptable ranges or values.	Fail to specify what makes a response acceptable.
Unclear priority order	Clearly define the steps an agent should take, and in what order (first, second, third, etc.).	Fail to specify the order of operations for multiple tasks.
Lack of response size guidelines	Specify the amount of bullet points or words an agent should provide in a summary.	Fail to specify the desired level of detail or response length

Reliability

Best practices to ensure the reliability of Retool Agents include error handling, failover mechanisms, and continuous availability strategies.

Provide error handling

Implement proper error handling in custom tools and agent instructions, returning errors that the LLM can understand to recover from failure situations.

Test with edge cases

Use evals and chat to test agents thoroughly across different scenarios to help reduce failures and errors.

Monitor run usage

Monitor total runtime and individual agent runs from the Monitor page.

Maintain version control for agent configuration changes

Include thorough descriptions of what was changed and whether the change was major, minor, or a patch.

Security

Best practices for security considerations when implementing and using Retool Agents include data protection, access controls, and compliance requirements.

Configure appropriate permissions for agent access

Apply the principle of least access when permissioning agents, which follow the same permission model as apps and workflows. Use role-based access control for agent management.

Be mindful of tool data access

Carefully consider what data you expose through tools, as agents have full access to any data accessible via their connected tools. Use OAuth to authenticate tools where possible so that user data access is scoped to their permissions. Limit access to only what's necessary for the agent's function.

Use role-based permissions

Implement role-based permissions across Retool to ensure that agent builders do not accidentally use resources they should not have access to.

Sustainability

Best practices on sustainable usage patterns for Retool Agents focus on resource efficiency and environmental impact considerations.

Optimize token usage

Design prompts, instructions, and tool responses to minimize token consumption by using concise language and limiting data transfer to only what's necessary.

Implement resource-efficient patterns

Cache responses when appropriate, use streaming for long-running processes, and implement rate limiting to prevent resource overuse during peak periods.

Regular performance monitoring

Schedule periodic reviews of agent usage patterns and resource consumption to identify and address inefficiencies in your implementation.