Skip to main content

AI Agents – Troubleshooting Guide

This guide helps users identify and resolve common issues with BEAK AI Agent skills (REST API, Python, or PowerShell) before escalating to the BEAK support team. Users are recommended to use this guide, along with the FAQ, to troubleshoot issues independently before reaching out to the BEAK team for support.

1. Initial Self-Evaluation​

Before checking BEAK, confirm that your skill works independently.

a. For REST API Skills​

  • Test the same API call using Postman or any online API testing tool.
  • Ensure the request completes successfully without errors.
  • If the API itself doesn’t work in Postman, fix this first before testing in BEAK.

b. For Python or PowerShell Skills​

  • Run the script locally on your machine.
  • Confirm that the code executes without errors.
  • If the script fails locally, update or correct the code before using it in BEAK.

2. Review the Execution Trace​

If the API or script works outside BEAK but fails inside BEAK, the next step is to inspect the run in AI Observability.

Open AI Observability and go to Traces. Each row is one agent run.

Open the most recent trace for your agent (match it by timestamp). A trace opens with its span tree on the left and the selected span's detail on the right.

Select the generation (LLM) or tool span you want to inspect, then open the Input / Output tab. The Input shows the exact request the agent sent — the system prompt and messages for a generation span, or the arguments for a tool call.

The Output shows what came back — the assistant's response, or the tool's result, including the exact error text when a span failed.

a. For REST API Skills​

  1. Check the request generated by the AI Agent in the Trace.
  2. Compare this with the request you executed in Postman.

Next Steps:

  • If both requests match: The issue is likely on the BEAK platform side. Please escalate to BEAK Support.
  • If the requests differ: Review the OpenAPI spec configured in the skill, and update parameters or adjust the Additional Info section.

b. For Python or PowerShell Skills​

  1. Verify that the script visible in Trace matches the one you executed locally.
  2. Compare the behavior between local execution and BEAK execution.

Next Steps:

  • If the script works locally but not in BEAK: Escalate to BEAK Support.
  • If the script does not work locally: Update and correct the script before re-testing in BEAK.