Troubleshooting

This guide covers common issues you may encounter when using AI Agents and how to resolve them.

General Troubleshooting Tips

When encountering issues with AI Agents, follow these steps:

1. Use the Agent Tester - The built-in tester in Lime Admin lets you run agents with different test objects and see exactly what's happening.
2. Start Simple - If an agent isn't working, simplify it. Remove Additional Input Data queries, reduce number of Output parameters, and simplify instructions. Add complexity back gradually once the basic version works.
3. Verify Your Data - Make sure your input object exists and has the expected properties. Check that Additional Input Data queries are returning the data you expect.
4. Review Instructions - Agent instructions should be clear, specific, and unambiguous. Vague instructions lead to unpredictable results.
5. Check the Logs - Logs for all AI Agent requests are available in Lime Admin, under "Settings" → "AI Agents" → "Log".

Common Issues

Cannot Select "Run AI Agent" in Automation Step

Description

When building an automation in Lime Admin, the "Agent" action type does not appear in the available actions list, or it cannot be selected.

Solution

This happens when the "Run in background" switch has not been enabled for the automation.

Agent Performance is Slow

Description

Agent execution takes longer than expected, causing delays in automations or user actions.

Solution

Slow agent performance is typically caused by excessive data being sent in Additional Input Data queries.

Common causes:

• Queries returning hundreds or thousands of records
• Including large text fields (long descriptions, full email threads)
• Multiple queries each returning substantial data
• No limit set on query results

How to fix:

1. Always set a limit on Additional Input Data queries

   • Review each query and add a reasonable limit
   • Ask yourself: "Does the agent really need all these records?"

2. Filter query results

   • Use query filters to return only relevant records
   • Example: Instead of "all deals", query "open deals in last 90 days"

3. Select only necessary properties

   • Only include properties the agent needs for Input Object and Additional Input Data queries
   • Exclude large text fields unless essential

Important: More data doesn't always mean better results. Excessive irrelevant data often makes agent responses worse while also making execution slower and more expensive.

Agent Fails Due to File Issues

Description

The agent fails to run when the input object or an additional data query includes a file property. Typical error messages mention unsupported file formats, files that are too large, PDFs with too many pages, or too many files in the request.

Solution

Each AI model supports a specific set of file formats and has limits on file size, page count, and the number of files per request. The supported formats and limits for the currently selected model are listed in the banner shown on the agent's configuration page in Lime Admin when file properties are included.

Common causes:

• A file property references a file in an unsupported format
• A single file exceeds the model's per-file size limit
• A PDF has more pages than the model allows
• The total number of files, or the total combined size, across the input exceeds the model's per-request limits

How to fix:

1. Review the banner on the agent configuration page for the selected model's supported formats and limits
2. Filter your queries to return fewer objects - and therefore fewer files - per run
3. Remove file properties that aren't essential to the agent's task from the Input Object Properties or from Additional Input Data queries

Agent Returns Unexpected Results

Description

The agent completes successfully but returns results that don't match expectations or seem incorrect.

Solution

1. Review agent instructions

   • Are they specific and unambiguous?
   • Do they include necessary domain knowledge?
   • Are there conflicting instructions?

2. Check input data

   • Use the agent tester with different test objects
   • Verify the input object has the expected properties
   • Confirm Additional Input Data queries are returning relevant data

3. Adjust instructions

   • Be more specific about what you want
   • Provide examples in the instructions
   • Break complex analysis into multiple fields

4. Try different models

   • Test with the "Powerful" model if using "Fast"
   • More complex reasoning tasks may need the more capable model