# How Agent's Notebook would work

*Design preview. This describes the intended design, not a shipped product. Last updated 2026-10-12.*

## Three steps for a team

1. **Connect sources.** Logs arrive over OpenTelemetry (OTLP/HTTP), a generic JSON/NDJSON endpoint, or an AWS Firehose HTTP destination (CloudWatch subscription or ECS/FireLens sidecar, no application change). Sentry, PostHog, Linear and GitHub connect with OAuth and are queried live. Kubernetes gets a Helm chart; Vercel and Supabase use log drains.
2. **Add one MCP URL to the agents.** One remote endpoint per team or project. OAuth 2.1 for humans, scoped service tokens for cloud and CI agents.
3. **Ask.** Agents get joined, cited answers and write findings to a shared notebook. Humans see connector health, agent usage and outcomes in a console.

## What an agent would get

| Tool (planned) | Purpose |
|---|---|
| `describe` | Sources, tables, entities, join keys, column meanings, example queries, budget remaining |
| `search` | Cross-source keyword or id search in a time window; grouped hits with exemplars and evidence ids |
| `log_patterns` | Cluster log lines by template with counts and deltas against a baseline window |
| `timeline` | Joined events around a release, deploy, route, user or issue: deploys, error spikes, pattern changes, flag exposure |
| `query` | Read-only SQL over the team's lake, dry-run cost estimate, enforced scan budget |
| `get_evidence` | The full item behind an evidence id, inside an untrusted-data envelope, with source link |
| `notebook_read` / `notebook_write` | Findings with claims, evidence ids, saved queries, linked issues |
| `submit_feedback` | Rate a connector, tool, release or session as helpful or not |

Outputs are summary-first with drill-down ids. Every tool accepts an optional short `intent` string that feeds the console.

## Safety model

- **Read-only.** No tool writes to a source system. Issues are created and closed through the tracker's own MCP; the notebook records evidence and outcomes.
- **Untrusted-data envelopes.** Text from logs, errors and tickets comes back marked as data, with instruction-like content flagged, never executed or summarised with tools.
- **Budgets.** Per-team and per-session scan budgets; oversized results are summarised rather than dumped.
- **Isolation.** Per-team storage path and encryption key, per-team scoped query credentials, tenant id on every audit row. Deleting a tenant destroys its key.
- **Audit.** Every tool call is logged (agent, tool, argument hash, bytes scanned, sources touched); the team can read it.

## Deployment options

Hosted multi-tenant is the default for self-serve teams. Enterprise: deploy the data plane into the customer's own cloud account, or run it as a self-contained appliance; the data plane has no runtime dependency on the vendor's control plane. Storage format is open (Parquet, Iceberg later) so a team's own engines can read it.

## Example questions it is designed to answer

- "Has anyone used the new export feature since Tuesday?"
- "Summarize all searches since 9am this morning."
- "What errors and warnings appeared after release `api@1.42`?"
- "Is the `new-ranking` flag live for anyone, and are they hitting errors?"
- "Pull today's errors and warnings, open issues for the real ones, fix them, verify, close."

Overview for comparisons: https://agents-notebook.com/agents/overview.md · Survey: https://agents-notebook.com/agents/survey.md · Home: https://agents-notebook.com/index.md