​

Agent Issues

This guide helps you diagnose and resolve common agent-related problems.

​

Agent not responding

Symptoms: You send a message and nothing happens, or you see an error message. Possible causes and fixes:

1. The task is still running — Agent tasks run on the server, not in your browser. If your connection dropped or you reloaded the page, reopen the conversation: it reattaches to the task in progress and continues showing the answer. Nothing was lost.
2. The task is queued — If you see Queued…, you’re at your plan’s limit for parallel agent tasks. Wait for one to finish, or stop one you no longer need.
3. AI model service issue — The underlying AI model may be temporarily unavailable. Wait a minute, then send again.
4. Agent configuration error — The agent may have an invalid configuration. An administrator should check the agent’s settings in the Agents page.
5. Tool failure — A tool the agent is trying to use may be failing. Check toolkit connections in the admin panel.

​

Agent can’t use the browser

Symptoms: The agent says the browser is unavailable or busy, or the Browser tab says there is no browser. Possible causes and fixes:

1. The browser is unavailable on this deployment — The agent reports browser_unavailable and falls back to web search and opening links. The deployment’s sandbox has no browser (for example Azure Dynamic Sessions), or the browser’s network access is not configured. An administrator should check the browser settings of the deployment.
2. The browser is busy — The agent reports browser_busy: the sandbox has no free browser right now. The agent retries after a short wait; send the request again later if it gives up.
3. The agent is waiting for you — The chat shows that the agent handed the browser to you. Open the Browser tab, take control, do what it asks (sign in, for example) and select Hand back and continue, or send a message.
4. You are holding the browser — While you have control, the agent cannot act and waits for you. Select Hand back.
5. A page is blocked — The agent reports url_blocked for internal, private or cloud metadata addresses and for any host your organization blocks. This is by design.

​

Agent responding slowly

Symptoms: The agent takes a long time before text starts appearing. Possible causes and fixes:

1. Complex tool usage — If the agent is searching knowledge bases, calling external tools, or executing code, each step adds time. This is normal behavior. You don’t have to wait on the page — the task keeps running if you navigate away, and the answer is saved to the conversation either way.
2. Large context — Long conversations with many messages create a larger context for the model to process. If the current conversation has become very long, stop the running task first, then start a new conversation — otherwise the old task keeps running and keeps consuming a parallel-task slot.
3. Model selection — More capable models (reasoning models, larger models) can be slower. An administrator can try a faster model if speed is a priority.
4. Server load — During peak usage, response times may increase.

​

Task stopped at its execution limit

Symptoms: The turn ends with Run stopped at its execution limit. instead of an answer. An agent task has an upper bound on how long it can actively run (one hour by default) and on how many tokens it may consume in total. A task that reaches either limit is stopped and reported rather than left running indefinitely. Possible causes and fixes:

1. The task was too broad — Split it into smaller requests (“summarize these five documents” → one document at a time).
2. A loop — An agent repeatedly retrying a failing tool can burn the budget without progressing. Check whether the toolkit it depends on is healthy.
3. Very large sources — Narrow the knowledge base or the attached files so each step handles less material.

Work already done up to the limit is billed, so prefer stopping a task you know is going nowhere over letting it run to the cap.

​

The agent is waiting on you

Symptoms: The task pauses and the agent asks a question, or asks you to approve an action. This is intentional — agents can pause mid-task for a human decision, and no compute is used while paused.

1. A question — Answer it with a normal chat message; the task continues from where it paused.
2. An approval request — Use the approve or reject control shown with the request.
3. It expires — A pause left unanswered for 72 hours is cancelled automatically. Send the request again if that happens.

​

Stop is stuck on “Stopping…”

Symptoms: You pressed Stop and the task shows Stopping… for a few seconds. Stopping is cooperative: the agent finishes the step it is on (an in-flight model or tool call) and then stops cleanly, rather than being killed mid-write. It normally settles within a few seconds. Work completed before the stop is billed.

​

A follow-up message hasn’t been sent

Symptoms: You typed a message while the agent was working and it hasn’t been sent. A conversation runs one agent task at a time. A message typed during an active task is held and sent automatically when that task finishes. To send it sooner, stop the running task.

​

Agent giving wrong or irrelevant answers

Symptoms: The agent provides incorrect information, ignores your question, or goes off-topic. Possible causes and fixes:

1. Missing knowledge — The relevant documents may not be in the connected knowledge base. Check that the KB contains the information and that it’s been indexed.
2. Poor system prompt — The agent’s instructions may not be clear enough. An administrator should review and refine the system prompt.
3. Wrong agent — You may be chatting with an agent that isn’t designed for your question type. Try selecting a different agent.
4. Strict mode — If the agent is in strict mode and can’t find relevant documents, it will decline to answer rather than guess.
5. Outdated documents — The knowledge base may contain outdated information. Verify documents are current.

​

Agent not using knowledge base

Symptoms: The agent responds but doesn’t cite any sources, even for questions that should match documents. Possible causes and fixes:

1. Knowledge search not enabled — Verify the agent has the knowledge search tool enabled.
2. No knowledge base connected — Verify at least one KB is connected to the agent.
3. KB not indexed — Check the knowledge base’s indexing status — documents may still be processing.
4. KB access control — You may not have access to the KB. Check your group memberships.
5. Query mismatch — Your question may not match the documents well. Try rephrasing.

​

Reporting persistent issues

If issues persist after troubleshooting:

1. Note the agent name, your message, and the error/behavior
2. Note when the turn ran — support can trace the individual agent task from the conversation and time
3. Check the Analytics dashboard for the interaction details
4. Contact support@neuralfactory.ai with this information