Connecting an Agent

Connecting an agent to Mirador means giving it two things: the API contract (via llms.txt) and credentials (a server key). This page shows the setup for the common shapes of agent.

A server key grants read access to every trace in its project. Only hand it to agents you run and trust, keep it in an environment variable rather than pasted into a prompt, and create a dedicated key per agent so you can revoke one without breaking the others.

Claude Code

The fastest way to try this interactively. Export your key, then tell Claude Code where the API brief lives:

export MIRADOR_SERVER_KEY=mir_srv_...
claude

Fetch https://api.mirador.org/llms.txt and use the Mirador REST API it
describes, authenticating with the key in $MIRADOR_SERVER_KEY.

Explain why traces in the past 24 hours have been having more errors
than usual, and tell me which traces I should look at first.

Claude Code fetches the brief, composes the right curl requests, and walks the investigation loop on its own — comparing counts across windows, slicing by tags and attributes, and pulling event timelines for the traces that matter.

Doing this often? Add the instructions to your project’s CLAUDE.md (or a custom slash command) so every session already knows how to reach Mirador:

## Mirador
Trace observability lives in Mirador. To investigate traces, fetch
https://api.mirador.org/llms.txt and query the API it describes with
the server key in $MIRADOR_SERVER_KEY. The API is read-only.

A custom agent (Claude API)

For a programmatic agent — an incident bot, a scheduled report, a Slack assistant — put the brief in the system prompt and give the model one HTTP tool. The brief is small enough to include wholesale, and because it requires no key you can fetch it at startup so it’s always current:

import Anthropic from "@anthropic-ai/sdk";

const brief = await (await fetch("https://api.mirador.org/llms.txt")).text();
const anthropic = new Anthropic();

const response = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 4096,
  system: [
    "You are an observability assistant. You investigate traces via the",
    "Mirador REST API using the mirador_api tool. The API is read-only.",
    "Ground every conclusion in data you actually fetched, and cite the",
    "trace_ids behind your findings.",
    "",
    "--- Mirador API brief (llms.txt) ---",
    brief,
  ].join("\n"),
  messages: [{
    role: "user",
    content: "Explain why traces in the past 24 hours have more errors.",
  }],
  tools: [{
    name: "mirador_api",
    description: "GET a Mirador REST API path (e.g. /v1/traces?filter=...). Returns the JSON response.",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string", description: "Path + query string, starting with /v1/" },
      },
      required: ["path"],
    },
  }],
});

Your tool handler is a few lines — attach the key server-side so it never enters the model’s context:

async function handleMiradorApi(input: { path: string }) {
  const res = await fetch(`https://api.mirador.org${input.path}`, {
    headers: { Authorization: `Bearer ${process.env.MIRADOR_SERVER_KEY}` },
  });
  return await res.text(); // return the body either way; errors are typed JSON
}

Run the standard tool-use loop (call → execute → return result → repeat) until the model produces its answer. Error responses use a typed envelope — pass them back to the model verbatim; the brief teaches it to correct an INVALID_FILTER and retry.

Constrain the tool to GET and to the https://api.mirador.org origin, as above. The API itself is read-only, but a narrow tool keeps the agent from being repurposed to call anything else with your credentials.

Triggered investigations (webhooks + AI)

Combine automations with an agent to investigate before a human arrives: when a rule fires, your webhook consumer fetches the matched trace and asks the agent to analyze it, then posts the summary to your incident channel or ticket. This is the trace export recipe with one extra step — instead of attaching raw JSON to the ticket, hand the exported trace to the agent:

const trace = await exportTrace(traceEntity.id); // summary + full event timeline

const analysis = await analyzeWithAgent(
  `This trace matched the rule "${payload.rule_name}" ` +
  `(${payload.match_reason}). Explain what went wrong, when, and what to ` +
  `check first. Trace JSON follows:\n${JSON.stringify(trace)}`
);

await createTicket({
  title: `[Mirador] ${payload.rule_name} — ${trace.name}`,
  body: analysis, // AI summary up top; link the trace for the full data
});

For a single already-exported trace the agent doesn’t even need API access — the JSON is the evidence. Give it API access as well (previous section) and it can widen the investigation: “is this trace an isolated failure or part of a pattern?”

Prompting tips

Whatever the agent, the same briefing habits produce grounded answers:

Name the time window. “The past 24 hours” beats “recently” — the agent turns it into concrete since/until bounds and a matching baseline window.
Ask for evidence. “Cite the trace_ids behind each finding” keeps conclusions tied to real traces you can open in the dashboard.
Point at metadata first. “Discover the project’s tags and attributes before filtering” stops the agent from inventing field names.
Let counts lead. Encourage comparing pagination.total across slices before fetching event timelines — it’s the difference between a handful of requests and hundreds.

Getting Started

Core Concepts

Web3 Integration

OpenTelemetry

Automations

AI & Agents

Advanced

Best Practices

Claude Code

A custom agent (Claude API)

Triggered investigations (webhooks + AI)

Prompting tips

Next Steps

Worked investigation

Endpoints

​Claude Code

​A custom agent (Claude API)

​Triggered investigations (webhooks + AI)

​Prompting tips

​Next Steps

Worked investigation

Endpoints

Claude Code

A custom agent (Claude API)

Triggered investigations (webhooks + AI)

Prompting tips

Next Steps