Skip to Content
RiusMCPExample workflows

Example workflows

Four investigation patterns you can run entirely from your AI client once the Rius MCP server is connected. Each starts from a plain-language prompt; the tool sequence shows what your client does with it.

Investigate a slow agent run

My agent felt slow this afternoon. Find the slowest runs from the last 6 hours and show me where the time went in the worst one.

What the client does:

  1. list_spans with hours: 6, kind: "agent", sort_field: "duration_ms", which returns the agent runs in the window, longest first.
  2. get_agent_trace with the slowest run’s trace_id.

Don’t sort list_agent_traces for this: it returns the 20 newest traces by default, so sorting that page by dur_ms only finds the slowest of the 20.

The waterfall shows every step indented by depth with its duration, so the bottleneck is visible at a glance: one LLM call dominating the total is a model latency problem, many sequential tool calls of similar size is a fan-out you could parallelize, and a gap between spans points at uninstrumented work.

Follow-ups that work well in the same conversation:

Is that latency normal? Compare against the p95 for the last week.

(The client calls agent_traces_summary with hours: 168 and compares the percentiles against the slow run.)

Find failed runs this week

Which of my agent runs failed this week, and what actually went wrong?

What the client does:

  1. list_agent_traces with hours: 168, root_status: "Error".
  2. get_agent_trace on one or more failing runs.

root_status: "Error" keeps the runs whose root span ended in error, the genuine failures. status: "Error" matches any trace with an errored span, so it also returns runs that retried and recovered. The list returns 20 traces at a time; the reply carries a cursor for the next page.

In the waterfall, the failed span carries the error status. Failed tool calls show up as error-status TOOL steps inside otherwise healthy runs, so status: "Error" answers “find failed tool calls” too. If the list is long, narrow it:

Only the checkout-agent service, and group the failures by root span name.

(service: "checkout-agent" on the list call; the grouping happens in the client from the returned table.)

Watch cost and compare models

What did my agents cost this week, and which service is spending the most?

What the client does:

  1. agent_traces_summary with hours: 168 for the total.
  2. agent_traces_summary per service (service: ...) for the split.

Because list_agent_traces includes a model and cost column per trace, model-level comparisons work from the same data:

List this week’s traces and compare average cost per run between the gpt-4o runs and the gpt-4o-mini runs.

For a recurring version of this, ask the same question tomorrow; the tools always answer from a lookback window ending now, so “this week” stays current.

Let one agent learn from another’s failures

A supervisor agent checks your other agents on a schedule, finds the one that is failing, and passes what it learned to the team or back to that agent.

Give the supervisor its own key with read, and a name, for example X-MCP-Agent-Name: supervisor (see Name your agent). Then prompt it:

Every hour, use Rius to find the agent with the highest failed rate in the last 24 hours. Group its errors, compare its current version with the previous one, and read two failing traces. Summarise the most likely cause and a suggested fix.

A typical run calls:

  1. list_agents for the agent names, then agent_traces_summary with agent: ..., hours: 24 for each, to find the highest failed rate. (list_agents lists heartbeat instances only and has no error figures. To start from the failures instead, call agent_error_groups with hours: 24 across the workspace.)
  2. agent_error_groups with agent: ... to group that agent’s failures by cause.
  3. agent_versions for the versions that agent ran, then compare_agent_versions with agent, dimension, base, and head taken from that list, to check whether a new version introduced the problem.
  4. list_agent_traces with agent: ..., root_status: "Error", then get_agent_trace to read the failing runs.
  5. Optionally, with alerts:manage: create_alert_rule to watch for the same failure next time. Add channels:manage if the rule should notify a channel.

What the supervisor does with the result is up to you: post it to a channel, open a ticket, or pass it to the failing agent as context for its next run. The supervisor can’t acknowledge alerts; a person always does that.

Check that the loop is working on Usage and access: the supervisor shows up as a Named client with a high answered rate and a low Asked again rate.

Writing your own

The pattern behind the first three: start wide with agent_traces_summary (is anything wrong? how much?), narrow with list_agent_traces filters (which runs?), finish with get_agent_trace (why?). Any question you can phrase in those three steps works, and the tool reference lists every filter available at each step.

Next steps

Last updated on
Tool referenceInteroperability