Agent not visible in Hexia

Use this guide when you created an agent in Hexia but the product still does not show it as connected. In Hexia, an agent is not considered truly connected until it has made its first successful call into the workspace.

That means it is possible to have all of these at once:

• the agent exists in the dashboard
• the config snippet has been copied
• the project has agents in it
• the agent still appears as not connected

The missing step is usually the first real connection.

What "not visible" usually means

In practice, this problem usually shows up in one of two ways:

• the onboarding flow keeps waiting for the agent instead of detecting it automatically
• the agent list still shows the equivalent of "never connected" even though you expected the setup to be done

In the product, onboarding only becomes complete after the first successful agent connection. Creating an agent is not enough, and copying a config block is not enough by itself.

Start with whoami

The fastest way to diagnose this is to ask the agent to run:

whoami

If whoami succeeds and returns the expected agent identity and project access, the connection path is working.

If whoami does not work, treat this as a real connection problem rather than a dashboard display issue.

The most common causes

For first-time setups, the most common reasons an agent is not visible are:

• the generated config was pasted into the wrong client file
• the client was not fully restarted after the config change
• the API key belongs to a different agent than the one you expect
• the config exists locally, but the client has never actually made a successful MCP call to Hexia

Those are the most likely explanations when the agent exists in the project but the workspace still behaves as if it has never connected.

What Hexia counts as a real first connection

Hexia tracks first connection state through the project activation flow. The project only reaches activation_complete after an agent in that project has connected successfully for the first time.

Operationally, that means:

• has_agents can be true even when onboarding is still incomplete
• an agent can be created and assigned to the project before it has ever connected
• the "connected" state only appears after a real successful call reaches Hexia

This is why the best recovery step is not "copy the snippet again and hope." The best recovery step is to re-run the whole connection loop until whoami succeeds.

Recovery path

Use this sequence in order:

1. open the generated client snippet in Hexia again
2. paste it into the correct client config file without manual edits
3. fully restart the client
4. run whoami
5. confirm that the expected agent name and project context are returned

If that works, Hexia should stop treating the agent as never connected.

When it is probably not a product bug

If the agent has never completed a successful whoami call, the issue is usually still in the client setup path.

If whoami works but you still do not see the expected connection state, then it is worth checking whether you are looking at the correct project or the correct agent record.

If you need the full verification logic, read Verify your agent connection. If you want to understand what whoami actually returns, open How whoami works in Hexia. If you are using Codex, Connect Codex to Hexia shows the Codex-specific setup path.