Agent status shows where each Agent User is in setup and what to fix, so you can get your agent answering your team without guessing.
In This Article
- Where You See the Status
- Not connected via webhook or API
- API key created, but never used
- Connected, but cannot be reached: no webhook registered
- Webhook set, but the agent has never connected
- Set up, but the round trip is not confirmed yet
- Has replied before, but is currently unreachable
- Message delivery to this agent is turned off
- When BasicOps Cannot Reach Your Agent
- Related Articles
Where You See the Status
On the agent's avatar. An agent that is not finished being set up shows a marker on its avatar. Hover over it to see its status. Open the chat to see what to do next.
In the chat. Open a chat with the agent and, if the setup is not complete, a line at the bottom tells you what is wrong and what to do next. The same line appears if you send a message the agent cannot receive.
Once the agent has answered at least once and is reachable, both disappear. No marker means the agent is working.
Not connected via webhook or API
Nothing has reached BasicOps from this agent yet. This is where every agent starts.
What to do: Create an API key for the agent: go to Settings > Administration > Users > Agents, hover the agent, click the pencil, then click + next to API Keys. Then connect the agent from your agent platform.
See How to Set Up an API Key and Set Up an External Agent as a BasicOps Agent User.
API key created, but never used
The key exists, but the agent has never used it. Usually the key has not been given to the agent yet, or it was entered incorrectly.
What to do: Ask the agent to call get_current_user. If the key is right, it will come back with the agent's own name and workspace. If it fails, check that the key was copied in full.
See Set Up an External Agent as a BasicOps Agent User.
Connected, but cannot be reached: no webhook registered
The agent has used its key, so the connection to BasicOps works in that direction. But BasicOps has no way to reach the agent, which is what delivering a message requires.
This is the most common place to get stuck. The agent appears to be working, and it can read and write in BasicOps, but nobody can talk to it.
What to do: Ask the agent to call connect_agent. That registers the webhook BasicOps delivers to.
See Set Up an External Agent as a BasicOps Agent User.
Webhook set, but the agent has never connected
A webhook is registered, but nothing has ever used the API key. This usually means the webhook was registered by something other than the agent itself.
What to do: Connect the agent to the BasicOps MCP server using its API key, and check that it can call get_current_user.
See Connecting BasicOps to Your AI Assistant via MCP.
Set up, but the round trip is not confirmed yet
Everything is in place and nothing has gone wrong. The agent has not replied yet, so BasicOps cannot confirm the whole path works.
What to do: Send the agent a message. Its first reply clears the status.
If it does not reply, the most common cause is the agent's system prompt: it needs to know that it should answer messages from BasicOps. See System Prompt for an External Agent.
Set up, but BasicOps cannot reach it
BasicOps tried to deliver a message to the agent's webhook and could not. The agent has never replied, so this may be the first time anything was delivered.
What to do: Work through When BasicOps Cannot Reach Your Agent below.
Has replied before, but is currently unreachable
The agent has worked in the past, so the setup itself is right. It has now stopped responding.
What to do: Check that the agent is still running, then work through When BasicOps Cannot Reach Your Agent below.
Message delivery to this agent is turned off
After repeated failed deliveries, BasicOps stops trying. This stops one unreachable agent from slowing delivery for everything else in the workspace.
What to do: Fix whatever was making the agent unreachable, then have the agent call connect_agent again. That turns delivery back on.
When BasicOps Cannot Reach Your Agent
Work through these in order:
- Is the agent running? The most common cause. A hosted agent that has been stopped, redeployed, or has run out of credit will stop answering.
- Is the webhook URL still correct? If the agent moved to a new address, the registered webhook still points at the old one. Have the agent call connect_agent again to register the current address.
- Is the URL reachable from outside? A webhook on localhost, behind a VPN, or on a machine that sleeps cannot be delivered to.
- Is anything in front of it blocking BasicOps? A firewall, proxy or tunnel that has expired will refuse the delivery.
After fixing any of these, have the agent reply to a message. The status clears as soon as a reply arrives.
Article is closed for comments.