Troubleshoot AI Workers
Fix common worker setup, access, and run problems.
Use this checklist when a worker is missing, cannot run, or returns poor output.
Start with the worker detail page and one recent run. It is easier to fix the real failure when you know the exact worker status, source record, instructions, context sources, enabled tools, run error, and output.
Worker Is Missing
Check whether the worker was archived, whether you are in the right workspace, and whether your role can access AI Workers.
Also confirm the worker was not saved as a draft, paused, or created in another workspace. If another user created it, ask an admin to check role access before recreating the worker.
Output Is Too Vague
Tighten the instructions. Tell the worker what records to review, what format to use, what to ignore, and what output should be written.
Compare a vague run with a useful run if one exists. Look for differences in record context, date range, enabled tools, and instruction detail. Improve the instruction first before adding more tools or broader context.
Worker Cannot Use Data
Check context sources. The worker can only include enabled sources such as tasks, projects, CRM, finance, docs, or products.
If the data exists but the worker does not use it, confirm the record belongs to the current workspace, the context source is enabled, and the worker's instructions mention the data clearly enough. Keep sources narrow so the worker uses the right records instead of searching too widely.
If the worker should use one record, name the record type in the instruction. For example, say "summarize the current ticket and its related contact" instead of "summarize the customer." Clear record names help the worker use the context Agiled provides.
Worker Cannot Use a Tool
Check tool categories. Tool access is controlled separately from context. Also confirm the current user and workspace permissions allow the action.
Do not enable every tool just to fix one failed run. Add only the tool category the worker actually needs, then run a small test and review the output before allowing broader actions.
Run Failed
Open the worker detail page and read the run error. Then review status, instructions, context sources, tool categories, and max iterations.
If the run stopped because it reached the iteration limit, reduce the scope or make the requested output more specific. If it failed during a tool action, check whether the target record still exists, whether required fields are missing, and whether the user running the worker has permission for that action.
Do not edit every setting after one failed run. Change one thing, run a small test, and compare the new run detail with the failed run. This makes it clear which change fixed the problem.
Safe Reruns
Before rerunning a failed worker, check whether it already created tasks, comments, notes, messages, or other records. If it did, clean up duplicate risk or adjust the instruction so the next run does not repeat the same write.
For workers that write to customer-facing records, rerun against one test record first. Review the created output before using the worker on a larger set of records.
Pause Before Broad Fixes
Pause a worker before changing instructions, sources, or tools if it is attached to a workflow or used by multiple teammates. Then review the most recent output and decide whether any created tasks, comments, drafts, messages, or status changes need cleanup.
After the fix, run the worker on a low-risk record. Re-enable it only after the run proves that the worker reads the right context, stays within scope, and does not create duplicate records.