Troubleshooting your first agent

Missing package or import

Install atensec-thoth, then import thoth in Python. Check that your terminal uses the virtual environment where you installed it. TypeScript uses @atensec/thoth and Node.js 22+; the starter project uses ES modules and tsx. See Install an SDK.

Missing key, tenant, or endpoint

Use all three values supplied with your activated tenant. Set THOTH_TENANT_ID, THOTH_API_URL, and THOTH_API_KEY in the same terminal that runs the example. Use the unified base URL, without appending /v1/enforce. Do not guess a hostname or use the GovAPI administration endpoint for the SDK.

401 or 403

Check key expiry, tenant binding, and execute permission. A provider needs a separate organization read/write key. A key is only shown once at creation; rotate it through your administrator if you no longer have it. Never send plaintext keys in a support request.

429, transport errors, or 5xx

Honor retry guidance when present. Avoid rapid retry loops. Keep fail-open disabled while resolving connectivity or service failures. A refusal caused by an unavailable service does not prove server policy blocked your tool.

demo.read is refused

If an earlier run blocked shell.exec, the demo agent is quarantined. Ask an administrator to open Agents → trial-demo → Restore Agent, then start again with demo.read. Restore it before switching languages too.

If this is the first run, verify that your tenant has the expected demo policy and inspect the decision reason with your trial contact.

shell.exec returns STEP_UP or executes the guard

Stop the demo and reconcile the server policy. The expected result is BLOCK. The example's callback raises an error if reached and never starts a shell. Changing approved_scope does not install the expected policy.

Activation progress changed, but the result looks wrong

Progress records a first authenticated, finalized decision, including a refused action. Check decision history separately. Progress alone does not prove an ALLOW, callback execution, or a finalized evidence export.

Request help

Contact your trial support contact or support@atensecurity.com. Include the SDK version, timestamp, agent ID, sanitized error, and available correlation ID. Remove credentials, hold tokens, personal data, and private tool arguments. Explain the expected decision and the observed result.

Return to your first governed agent →