Skip to main content

​
A run is rejected

  • Confirm AIR_BASE_URL is the API URL, not the console URL.
  • Confirm the app key and agent belong to the same project.
  • Use the agent API ID—not its display name—as agent_id.
  • Confirm the agent has an active version and usable model access.
AirProtocolError.status_code contains the HTTP status. 401 usually means the key is missing, invalid, or revoked. 403 usually means it has the wrong scope or project.

​
A tool stays awaiting approval

Worker registration only discovers capability. A project owner must open Tools, review the manifest, and select Enable tool. Then add the enabled tool to a new agent version and activate that version.

​
A worker receives no tasks

  • Confirm the worker key and agent belong to the same project.
  • Confirm the tool is enabled and allowed by the active agent version.
  • Confirm the model requested the tool in the run trace.
  • Confirm the worker remains running after registration.
  • Check outbound HTTPS access to the AIR API.

​
A tool fails

Every tool must return a dictionary. Inspect the worker log for the original exception and the run trace for the recorded failure. Validate arguments, tenant access, downstream credentials, and timeouts.

​
Waiting timed out

RunTimeoutError only means the local wait deadline expired. The server-side run may still be active.
Read the run again, inspect its trace, or cancel it explicitly.