Skip to main content
Studio only — part of Evidence Studio, our hosted platform.
The Evidence Agent is Evidence’s bi ai agent for your project — an artificial intelligence for business that lets your readers ask data questions as a natural language query and get analytical answers built from your project. It’s one of the ai business intelligence tools that brings AI analytics to your published reports and dashboards: the agent reads them as context, generates new insights (analyses written in Evidence Markdown), and can reach the underlying SQL and filter definitions behind your reports. It respects your project’s existing access rules and page-level access control, so readers only ever see data they’re allowed to — enabling self serve bi and self service business intelligence where readers answer their own questions without waiting on an analyst. You can customize the agent’s behaviour with an agent/ directory at your project root — version-controlled files that ship through the same git workflow as your pages. There are two kinds of customization: context (always-loaded instructions) and skills (on-demand playbooks the agent loads when a task calls for them).
The Evidence Agent and its agent/ authoring tools are available once the Evidence Agent is enabled for your organization.

The agent/ directory

Every new project is scaffolded with the reserved structure:
agent/ is a reserved sibling of pages/, queries/, and components/. Files are recognized by location, not extension — anything under agent/context/ is context, anything under agent/skills/<name>/ is a skill.

Context

Every file under agent/context/ is treated as freeform markdown and is always included in the Evidence Agent’s instructions. Use these files to give the agent the organizational knowledge it can’t infer from your data — company targets, business processes, the org chart, metric definitions, the product changelog — and to set the tone and guardrails for how it should answer.
Context replaces the legacy org-level Custom Instructions (on the AI Agent settings page) — moving those into agent/context/ makes them version-controlled and per-project. Across projects a reader can access, each project’s context is merged.

Skills

Skills encode an analytical process directly, so the agent runs it the way your team would — the right follow-up questions, the analytical steps, and how to present results. They load on demand, keeping the always-on instructions small. Each skill is a folder under agent/skills/ containing a SKILL.md file:
SKILL.md follows the open Agent Skills format — YAML frontmatter plus a markdown body:
Frontmatter requirements: The description is the only part of a skill loaded up front — it’s how the agent decides whether to open the skill, so write it to say what the skill does and when to use it. The body loads only when the agent chooses to use the skill.
A SKILL.md with missing or invalid frontmatter blocks publishing. Fix the errors shown in the editor before you publish. Context files are freeform and are never validated.

Creating agent files

New projects already include a starter agent/context/instructions.md. To add more context files or skills, use the Agent config menu in the editor’s project sidebar — it creates a context file or a skill folder with the right structure and a starter template. You can also add the files directly in git.

Monitor agent usage

Users with the Developer or Admin role can open AI Observability from the sidebar to see how report viewers use the Evidence Agent. The page is only available to developers and admins because it shows every viewer’s conversations across the organization. The dashboard covers one calendar month at a time. Use the arrows next to the month to switch periods. A conversation counts in the month it started. For each period, AI Observability shows:
  • Adoption and cost: conversations, active viewers, messages, and credits, plus daily activity, top viewers, and whether conversations happen on the web or in Slack.
  • Agent health: the resolution rate and share of helpful answers, with breakdowns of answer quality and outcome.
  • Topics: usage by category and the topics where the agent underperforms, so you know which context or skills to improve.
  • Recent conversations: each conversation’s topic, viewer, message and credit counts, quality, and outcome.
Quality, outcome, and topic come from analyzing each conversation. Select Analyze conversations to analyze any new conversations, or conversations that have grown since they were last analyzed. Conversations that have not been analyzed show Not analyzed.

Beyond Evidence Studio

The Evidence Agent is available in Studio’s chat, and the same context and skills are exposed to external AI clients (such as Claude and ChatGPT) through the Studio MCP server’s get_context tool — so a connected assistant sees the same instructions and available skills as the in-app agent.