How can my coding agent group an agent’s errors in Rius?

Your coding agent calls the agent_error_groups tool on the Rius MCP server, which groups an agent’s errored spans by failure class so a page of failures reads as a few causes. You ask in plain words, such as “What is failing for the planner agent today?”, and the client picks the tool and its arguments. Each row of the reply is one group, with its count, distinct traces, last occurrence, the instances it hit and sample trace ids.

How it works

The agent_error_groups tool reads the errored spans in a time window and groups them by exception type and a normalised message. Rius returns the result as Markdown, which your client renders as a table. It is the same read the Agent page in the Rius console draws its Exceptions figure from, so your coding agent and a person in the console see the same groups.

The main parameters, all optional:

• agent: the exact agent name. Read it off list_agents, or off the root_agent column of list_agent_traces, rather than guessing one.
• instance: an exact instance id, to narrow to one running copy of that agent.
• hours: a lookback window ending now. The default is 24, and “this week” is 168.
• start and end: absolute RFC3339 bounds. They override the window that hours gives.
• limit: groups per page. The default is 20 and the server maximum is 100. The reply says how many errored spans the whole window holds, so you can see when a page is full.
• workspace: a workspace name or ID. Omit it to use your default workspace.

The unit is errored spans. The count in each group is not the failed_traces figure from agent_traces_summary, which counts runs whose root span errored. Rius labels the two and never adds them together. The grouping reads span events, so the window is capped like any other unindexed query. If the server refuses a window, the reply says so.

Set it up

1. Connect your client to the Rius MCP server once. For Claude Code, run the line below and finish the browser sign-in the first time a session uses the server. The Rius plugin already registers the server as rius, and other clients and headless keys are covered in MCP.

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

2. Find the exact agent name. Ask “Which of my agents are running right now?” and the client calls list_agents. Use the name it shows in the next step.

3. Ask in plain words. The examples below show what the client sends for each question.

   “What is failing for the planner agent today?”

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

   “Group this week’s failures across every agent.”

   { "name": "agent_error_groups", "arguments": { "hours": 168, "limit": 50 } }

4. Narrow to one copy. Ask “Is one copy of planner producing the errors?” and the client adds an instance.

   {
       "name": "agent_error_groups",
       "arguments": { "agent": "planner", "instance": "inst-planner-01" }
   }

5. Open one failure. Take a sample trace id from a group and ask the client to break that trace down. It calls get_agent_trace with the id and shows the span waterfall.

The tool only reads. A key without manage scopes can call it, as long as the key has the read scope. Ingest keys, which the SDK uses, cannot query through the MCP server. The full argument list is in the tool reference.

What you get

• A short table of failure classes instead of a long list of failed spans. Each row gives the count, the number of distinct traces, the last time it happened and the instances it hit.
• Sample trace ids in every group, ready to pass to get_agent_trace for the full span waterfall of a real failure.
• A per-copy answer when you pass instance, so you can tell whether one running copy of an agent causes the errors or all of them do.
• A page-size signal. The reply states how many errored spans the whole window holds, so you know when to raise limit or narrow the window.
• Numbers that match the console. Your coding agent reports the same groups a person reads on the Agent page, and the wider picture is in Monitor AI agents in production.

When something else fits

• To count runs whose root span errored, ask for agent_traces_summary, which reports failed traces and errored traces as two separate figures.
• To find a failure by what it said, such as “rate limit”, use list_agent_traces with error_text and then open the trace you want.
• To see how one run unfolded, call get_agent_trace directly with a trace id.

Related