How can my coding agent list the agents in a workspace in Rius?

Your coding agent lists the agents in a Rius workspace with the list_agents tool on the Rius MCP server. Ask in plain words, such as “Which of my agents are running right now?”, and the client calls the tool for you. You get one row per agent instance with its live status: running, ready, stale, gone or stopped.

How it works

list_agents is a read-only tool. It makes the same read as the Agents page in the Rius console, so your coding agent and a person looking at the console see the same instances and the same status words.

It takes two optional parameters:

• workspace: a workspace name or ID. Leave it out to use your default workspace. If the same workspace name exists in two of your organizations, pass it as org/workspace. Use list_workspaces to find the right value.
• agent: an exact agent name, to list only that agent’s instances. If nothing matches, the reply names the agents that do have instances.

What comes back is Markdown that your client renders for you:

• One row per agent instance, so an agent with three copies running shows three rows.
• A status for each instance: running, ready, stale, gone or stopped. Rius computes the status from the last heartbeat, so read it as given instead of working it out from the last-seen time.
• open_trace_count, the number of traces still open for that instance. It is the signal behind running and ready.
• first_seen_at and stopped_at when Rius has them. A blank first_seen_at means the start is unknown, not that the instance just started.

Only agents that send heartbeats appear. An agent that sends traces but no heartbeat does not show up in this list, and the reply explains why when an agent you expect is missing. Heartbeats show that a process is alive, not that it is making progress.

For the wider picture of watching agents in production, see Monitor AI agents in production.

Set it up

1. Connect your coding agent to the Rius MCP server. In Claude Code, run this once. The OAuth sign-in opens the first time a session uses the server:

   claude mcp add --transport http rius https://mcp.eu.console.rius-glassflow.com/mcp

   If you use the Rius plugin, it already registers this server as rius, so skip this step. Other clients, and agents that run without a browser and need a read-scoped API key, are covered on the MCP page.

2. Check the connection by asking: “Who am I in Rius, and which workspaces can I access?” Your client calls get_me and answers with your email and your workspaces.

3. Ask the question in plain words:

   • “Which of my agents are running right now?”
   • “Are any copies of planner lost?”
   • “List the agents in the staging workspace.”

4. If you want to see what the client sends, these are the calls behind the first two questions. The second one names planner as an example agent:

   { "name": "list_agents", "arguments": {} }

   { "name": "list_agents", "arguments": { "agent": "planner" } }

5. To target another workspace, ask for it by name, or have the client pass workspace to list_agents. The full argument list for every tool is in the tool reference.

What you get

• A live list of the agents in a workspace, with every instance and its status, without opening the console.
• A quick check for lost copies: ask about one agent and see whether any of its instances are stale, gone or stopped.
• Agent names you can reuse. Other tools take an exact agent name, such as agent_error_groups, agent_versions and list_agent_traces, so you can read a name off this list and follow up with “What is failing for planner today?” or “Which versions of planner ran this week?”
• The same answer from OAuth and from a read-scoped API key. A key reaches the one workspace it was created in.

When something else fits

• If the agent you expect is missing, it may send traces but no heartbeat. Ask for its traces with list_agent_traces, or for its numbers with agent_traces_summary.
• If you want to know when instances started, finished or were lost over time, ask for agent_lifecycle_events. It returns the lifecycle log instead of the current status.

Related