# bigquery-agent-analytics-sdk

A skill for analyzing AI agent telemetry in BigQuery: trace reconstruction, LLM-as-Judge evaluation, and drift detection.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 768 installs · ★ 5
- Author: reason-machines
- License: LicenseRef-Unknown · policy=link-only · description only; the file stays with the author
- Source: https://github.com/reason-machines/data-skills/tree/HEAD/skills/bigquery-agent-analytics-sdk/SKILL.md
- Updated: 2026-10-09
- HTML: https://affpapa.org/en/nevibecode/skills/bigquery-agent-analytics-sdk

## What it does

The skill brings the `bigquery-agent-analytics` Python toolkit into your project. It reads agent events from BigQuery, stitches them into traces, and renders each one as an ASCII DAG. Event semantics helpers tell apart agent start, tool invocation, LLM call, and agent end.

Inside you get a `Client` with `get_trace`, `get_traces_for_session` and time-range queries, a `ViewManager` that splits events by type into BigQuery views, `SystemEvaluator` plus LLM-as-Judge evaluators, and the `bqaa` CLI with commands for diagnostics, evaluation, and Agent Context Graph extraction. Periodic materialization can be scheduled — that command provisions Cloud Scheduler and Cloud Run.

You need Python 3.10+, a Google Cloud project with BigQuery enabled, and agent traces already sitting in BigQuery. Auth goes through `GOOGLE_APPLICATION_CREDENTIALS` or `gcloud auth application-default login`. Skip that step and the client simply won't reach your dataset, so wire up credentials before the first run.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/data-skills --skill bigquery-agent-analytics-sdk -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/bigquery-agent-analytics-sdk/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/bigquery-agent-analytics-sdk/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/data-skills --skill bigquery-agent-analytics-sdk -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/bigquery-agent-analytics-sdk/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/data-skills --skill bigquery-agent-analytics-sdk -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/bigquery-agent-analytics-sdk/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install reason-machines/data-skills bigquery-agent-analytics-sdk
```

2. **Manually: put the files in place**
- File: `.github/skills/bigquery-agent-analytics-sdk/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add reason-machines/data-skills --skill bigquery-agent-analytics-sdk -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/reason-machines/data-skills --path skills/bigquery-agent-analytics-sdk
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/bigquery-agent-analytics-sdk/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add reason-machines/data-skills --skill bigquery-agent-analytics-sdk -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/reason-machines/data-skills/tree/HEAD/skills/bigquery-agent-analytics-sdk/SKILL.md

## When to use it
- rebuild agent traces from BigQuery events into one readable graph
- score agent responses with an LLM judge against chosen criteria
- compare the actual execution path with a golden one
- spot drift in agent behavior over a time window
- pull agent decisions out of the context graph

## Example prompts
- show trace trace-abc-123 and render it as a DAG
- run llm-judge evaluation with criteria correctness and hallucination
- compare trajectories against the golden path plan,execute,verify

## Similar
- [bigquery-observability](https://affpapa.org/en/nevibecode/skills/bigquery-observability.md) — skill · 1800 installs
- [bigquery-bigframes](https://affpapa.org/en/nevibecode/skills/bigquery-bigframes.md) — skill · 6426 installs
- [bigquery-pipeline-audit](https://affpapa.org/en/nevibecode/skills/bigquery-pipeline-audit.md) — skill · 8800 installs
- [arize-evaluator](https://affpapa.org/en/nevibecode/skills/arize-arize-evaluator.md) — skill · 3100 installs
- [looker-studio-bigquery](https://affpapa.org/en/nevibecode/skills/looker-studio-bigquery.md) — skill · 389 installs
- [gcp-expert](https://affpapa.org/en/nevibecode/skills/gcp-expert.md) — skill · 547 installs

From the same set: [reason-machines/data-skills](https://affpapa.org/en/nevibecode/by/reason-machines/data-skills.md) — 22 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md