Troubleshooting

The API returns fewer messages than expected

The relay appends only the newest turn to the stored thread history. If older messages seem to be missing, you are usually writing into a different sandbox or thread than you expect. Reuse the same sandboxId, and if you have multiple conversations in one sandbox, also reuse the same threadId. If you omit threadId, the relay resumes the latest thread in that sandbox.

Auth & token issues

• 401 Unauthorized - your API key is missing or invalid. Re-run an login or check API_KEY_21ST in your environment.
• Token exchange failing - ensure your /api/an-token route is correctly calling createTokenHandler with a valid API key.

Agent not responding

• Sandbox expired - idle sandboxes are destroyed after a timeout. When that happens, treat the old sandbox as gone and start a fresh sandbox/session.
• Max turns reached - the agent hit its maxTurns limit. Increase it in the agent config or per-request via options.maxTurns.
• Budget exceeded - if maxBudgetUsd is set and the cost exceeds it, the agent stops.

Tool permission errors

If the agent can't execute a tool, check the permission mode in your agent config. In default mode, risky tools require user confirmation. Use bypass for fully autonomous agents in isolated sandboxes.

SSE streaming drops or doesn't start

Ensure your client supports Server-Sent Events and that no proxy or CDN is buffering the response. Check the Logs page in the dashboard for error details on the specific dialog.

Deploy fails

• Missing entry point - ensure agents/<slug>/index.ts exists with a default export using agent().
• Invalid API key - re-run an login.
• Bundle too large - keep agent code small, avoid heavy dependencies in the entry point.