Skip to main content

🛠️ Troubleshooting Agents

Below are solutions to common issues related to agents, orchestration, and skills in Beak AI.

Cannot view agent after creation​

  • Make sure you're logged in with the same account used to create the agent.
  • Ensure you're viewing the correct Industry and Agent Type filters.
  • Check the Inactive Agents section in case it was deactivated by mistake.
  • If inactive, simply reactivate the agent to make it visible again.

Agent is not responding or timing out​

  • Check agent logs in Beak AI Observability for errors or timeouts.
  • Ensure all required data sources and skills are connected and healthy.
  • Verify that the agent has the necessary permissions and environment variables.
  • Restart the agent or the underlying service if needed.

Orchestration errors (e.g., failed workflows, stuck tasks)​

  • Review the orchestration trace in Observability to identify the failing step.
  • Check for misconfigured workflows, missing dependencies, or circular references.
  • Validate that all sub-agents and skills are registered and accessible.

Broken or missing skills​

  • Confirm that the skill is correctly registered in Studio and enabled for the agent.
  • Check for version mismatches or missing dependencies in custom skills.
  • Test the skill independently in the Studio playground.

Agent produces unexpected or incorrect outputs​

  • Review the agent’s prompt and memory configuration.
  • Check for outdated or conflicting skills.
  • Use Observability to trace the agent’s reasoning and outputs step-by-step.

How to use AI Observability for debugging​

  • Search for your agent in the Tracing tab and locate the specific chat message.
  • Review the workflow to see how data sources and skills are being triggered.
  • Check the inputs sent to and outputs returned from each data source and skill.
  • Look for errors or malformed inputs in the trace and make necessary adjustments.

Agent cannot access external APIs or data sources​

  • Verify network connectivity and firewall rules.
  • Ensure API keys and credentials are correctly set in environment variables.
  • Check integration settings in Studio.

Agent is not calling my skill​

  • Ensure the skill is properly added to the agent.
  • Check the skill’s instructions — make sure they clearly describe what the skill is responsible for.
  • There are strict size limits on skill instructions in OpenAI.
  • Summarize or shorten your skill instructions wherever possible.
  • Avoid placing OpenAPI specs or table schemas inside skill instructions.
  • Move extra details to agent instructions or user questions when appropriate.

Python code execution skill fails in agent, but works locally​

  • Check the AI Observability → Trace for any specific error messages.
  • Ensure your code can run from start to finish without requiring user input during execution.

How to configure my agent to send email​

  • Configure the prebuilt Send Email skill in your agent.
  • Use base64-encoded email app passwords along with correct usernames and email addresses.
  • Set the appropriate SMTP server and port based on your email provider (e.g., Gmail, Outlook).
  • Customize the HTML email template as per your formatting preferences.

Skill selection logic when multiple skills are present​

  • The agent chooses a skill based on the skill’s instructions and the user's question.
  • Ensure each skill's instructions clearly describe its purpose and responsibilities.

Chatting with large file is not working, no response from agent​

  • This may be due to OpenAI token limitations when sending large content directly.
  • Upload your files as a data source instead.
  • Choose Smart Search or Structured Smart Search, and submit the files properly.

Editing skill is not changing agent's behaviour​

  • After attaching a skill to an agent, avoid editing it from the Skills section.
  • Instead, edit the skill from the Agent → Configure section to ensure changes are reflected.

Guidelines for setting up an ambient agent​

  • Avoid creating rogue and untested agents with open-ended recurring schedules.
  • First verify the agent’s behavior in chat mode to ensure it responds correctly.
  • Configure the ambient schedule as per your requirement only after confirming the agent behaves as expected.
  • Do not create the ambient agent with an empty trigger message.

For persistent issues, consult the General FAQ or contact Beak AI support.