When building AI Agents, you can sometimes run into errors or unexpected behavior. We put together this guide to assist you in troubleshooting these issues and get your AI Agents up and running smoothly.
This guide contains step-by-step instructions and tips to help you resolve any issues you may face.
Table of contents:
Variables
Execution error
Oops error
Custom Function error
Data Source error
Run Workflow Block error
Generate Asset block error: PDF, PNG, HTML
MindStudio Architect
Out of Usage Credits
Models are locked
Something else
Variables
If your variables aren’t resolving, they’re likely referenced incorrectly.
We recommend reviewing this Help Doc for guidance on using variables:
Be sure to double-check the syntax, especially when extracting nested values from JSON arrays.
Execution error
If you see an Execution error, the Debugger usually shows what caused it.
Open your AI Agent, go to the Debugger tab, and select the failed Run to review the details.
Once you’ve identified the issue, check the Community for solutions or similar topics: Search results for '' - MindStudio.
Oops error
First, please perform the basic troubleshooting steps:
- Log out and log back in
- Clear your browser’s cache and cookies
- Try accessing MindStudio in a different browser
If the issue persists, please contact us directly at support@mindstudio.ai and we will take a closer look.
Custom Function error
While testing and designing Custom Functions falls outside our scope of support, here are some resources and suggestions to help you troubleshoot:
- Consider replacing the Custom Function with built-in blocks:
For example, instead of using a custom function to search for recent news, you can use a Generate Text block with Sonar Online models or Search Google News.
- Debug the Custom Functions by chatting with AI:
Remix Custom Function Debugger Agent
- Check out these resources for guidance on Custom Functions:
- Need hands-on help?
You can hire an expert from the MindStudio Partner Directory, which features agencies, solution providers, and professional service firms ready to assist.
Data Source error
The main challenge usually is how vague queries interact with Retrieval-Augmented Generation (RAG).
How RAG Works:
When you upload files, the system breaks them into smaller chunks, vectorizes them, and retrieves the most relevant ones based on your query. However, very broad or vague queries can pull unrelated chunks or cause the Run to fail with an error.
Querying:
For best results, Query Templates should be concise and specific. That’s likely why this setup isn’t working as expected. We cover this in more detail in this Help Doc and this YouTube video.
Here’s what you can try:
- Add a Generate Text block that uses a prompt to create a focused RAG query based on the variable containing all the text. Make sure the prompt asks for a short, specific sentence.
- Reference that new variable in the Query Template section of the Query Data Source block to improve retrieval results from your Data Sources.
Run Workflow Block Error
The Run Workflow block might not work as expected if there are any issues with the variables, JSON array, or launch variables.
Below are two AI Agents that use a Run Workflow block. You can remix them into your Workspace and explore how they’re structured to implement needed changes in your current setup:
Simple : https://app.mindstudio.ai/agents/run-workflow-simple--remix-46a2a888/remix
Advanced : https://app.mindstudio.ai/agents/run-workflow-advanced--remix-f3bfba48/remix
The key difference between them:
- The Simple version uses an Iterator to process individual items
- The Advanced version works with a structured JSON array
Explore both versions to see which approach fits your use case. Please note that the usage will be charged to your Workspace.
Generate Asset block error: PDF, PNG, HTML
If your PDF turns out empty or is missing some content, here are two approaches you can try:
1. Detailed HTML approach
With this approach, you’ll need to:
-
Adjust the last Generate Text block to output structured JSON
-
Modify the HTML code to be more structured and reference each key from the JSON array separately within the HTML
Help Doc: Extracting a Value from a JSON Structure
Pros : Consistent design.
Cons : To avoid pagination issues, you’ll need to specify the expected amount of text for each JSON key in the prompt.
2. Use HTML only
Instead of working with JSON, you can prompt a Generate Text block to output the entire content in HTML, then reference that variable in the Source Document field of the Generate Asset block:
Pros : Quick and simple setup.
Cons : You must be very specific when defining the design in the prompt. The design might vary since the HTML code is generated from scratch each time.
MindStudio Architect
The MindStudio Architect is a powerful feature designed to simplify building AI Workers. By describing your desired outcome, it automatically generates a detailed workflow complete with prompts, variables, automation steps, and custom functions.
However, since the Architect is AI-powered, it may produce inaccurate results or miss important details. It’s essential to review the generated workflow carefully before using it.
Here’s a step-by-step video guide on how to review the Architect’s outcome:
After the Architect builds your AI Agent scaffold, make sure to:
- Review the System Prompt and make sure it matches your expectations.
- Go through each workflow step to ensure it performs the intended tasks.
- Run the workflow and review the results to check if something is off.
- Use the Debugger and the Diagnostic Tool to check for errors and warnings. Please note that the Diagnostic Tool may overwrite parts of your automation. To preserve the original version, create a copy of your Agent first.
- Validate all variables by reviewing their syntax and references. For guidance, refer to our Help Doc on variables.
If you need help, please reply to this post. Our MindStudio Developer Community is here to help!
Out of Usage Credits
When you create a MindStudio account, you’re automatically enrolled in the Community Plan and receive $5 in free Usage Credits for testing.
The Community Plan has no subscription fee - you only pay for Usage Credits, which cover tokens consumed by LLMs, and a 2.9% processing fee.
If you want to continue using your agents after testing, you can top up your balance here: https://app.mindstudio.ai/billing/overview.
Models are locked
To unlock all models, please add a valid CC on file here: https://app.mindstudio.ai/billing/payment-methods
Something else
If you’re unable to identify the issue, here are a few options to try:
- Run Diagnostic: To preserve your work, make a copy of your AI Agent and click Run Diagnostic. The Agent will attempt to analyze and resolve the issue automatically.
- Hire an expert: If you need hands-on assistance, consider hiring a professional from the MindStudio Partner Directory. It features agencies, solution providers, and professional service firms who can help.