Analytics components, tools and briefings

Status: Current | Last reviewed: 2026-10-02

The Call Drivers editor shares response configuration between Analysis and Experience. Draft changes use the canvas collaboration document. Publishing pins the configuration; private chat history retains its original configuration, data snapshot and selected catalogue versions. See the user guide for the controls.

Component contract

analysis.presentation.components selects built-in Analytics components, chart styles, published catalogue versions and individual components. It also controls prose length, visual count, initial report expansion and composition instructions. Existing agents retain the eight built-in families and ten chart types by default. The migrated CallSight layout and prompt remain the default composition.

GET /api/analytics/catalogs requires Manage Agents and returns current published catalogue manifests accessible to the tenant. Each selection pins catalogId, versionId and component names. There are at most ten catalogues and fifty selected catalogue components in total. Explicit tenant/shared predicates and published-ready checks apply during validation, generation and presentation. Updating a catalogue does not silently upgrade an agent.

component-catalogs.ts produces a function tool for each selected component using the published props_schema. Tool results undergo JSON Schema validation before becoming component attachments. Attachment anchors use the same composition pipeline as built-ins. The runtime strips disabled, unsupported or over-budget visuals while retaining factual evidence in tool output. Length is prompt guidance; the visual budget is enforced.

The presentation endpoint supplies signed bundle/CSS URLs and integrity hashes for the authorized agent or private session. The shared A2UI loader verifies the bundles and registers them under an immutable analytics:<versionId> namespace. Renderer lookups stay inside that namespace, including recursive children. This prevents matching component names from colliding across agents or versions. Shared catalogue CSS is still page CSS; authors should scope their selectors. Built-in cards retain their existing appearance, transcript drawers and citation actions. Published components are presentational: selecting them does not attach catalogue data tools, proxy capabilities or transactional actions.

Task prompts and model choices

Analytics prompt fields reuse Studio's full prompt editor, with an expanded modal, enabled-tool references and selected component references in Analysis and Experience. {{TODAY}} resolves to today's UTC date. Compiler prompts have their own structured task contracts and do not advertise chat component tools.

The live analyst supplies the composition model. Answer review and the briefing can choose separate provider/service/integration/model bindings. Composition guidance supplements the full analyst/briefing prompt. The runtime appends the authorized data contract, enabled component policy and verified values; editing a prompt cannot override these constraints. Model choices are not changed by opening the new settings.

Prepared insights, drift and scenarios

Preparation owns report hierarchy construction, coverage, models and summary prompts. Analysis owns which completed trend levels and summary types may be discovered/read, list limits and whether the analyst should prefer them. Direct report reads enforce the same filters as report discovery.

Intent drift supports reported-versus-inferred classification disagreement or intent-share changes between adjacent time windows. The latter selects the reported/inferred lens, window duration, minimum contact count, percentage-point threshold and result limit. Totals are computed before filtering and limiting. An empty comparison window is insufficient data, not a zero-share observation. These calculations are deterministic; the live analyst model explains them. They do not discover or modify taxonomy entries.

Scenario configuration chooses enabled levers, historical window, handling cost/currency and containment cap. The question supplies intent/category, percentage or process area/date. Retired billing/Atlanta settings are ignored. The process-change lever compares handling time around a supplied event date using the warehouse hub field for area. Its reversal estimate assumes the observed difference is attributable to that change and explicitly states this limitation. It is not a causal forecasting model.

Briefing lifecycle

The opening briefing uses the same selected component policy. Its prompt can choose all metrics/cards, or the server can supply a selected subset of volume, containment, average handling time and escalation metrics. Unknown measurements are omitted. The selected mode uses a single metric card or a metric group when enabled. Metric windows follow the latest completed selected report tier, with a configurable rolling fallback ending today. There is also an explicit rolling window option.

Secondary findings have a configurable maximum (zero through six) and initial expansion state. Prompt-selected metric groups render inline; a fixed operating group retains the original location below the greeting.

generation: scheduled enables the existing Analytics worker's minute-level scheduler for published agents. It prepares once per configured refresh time bucket. on_open queues only when a reader opens an uncached bucket. Draft preview also generates on opening. Refresh is interval-based, not a time-of-day cron schedule. Existing settings default to scheduled generation.

PostgreSQL stores the answer, tool history, lease and bounded failure state. The cache key includes the full agent config, immutable snapshot, time bucket and prompt contract version. Reopening the same ready binding reuses its answer; new data/configuration invalidates it. Failed generation can be retried. The briefing cadence does not ingest files or rebuild annotations/reports. Follow-up chat can reuse the briefing's exact evidence history.

Validation

lib/analytics/composition.test.ts covers component policy/schema validation, catalogue scope/version pinning, renderer namespace isolation, cache changes and unknown metric handling. analytics_runtime/test_configuration.py covers drift denominators, thresholds, prepared report access and scenario target handling. The existing isolated database integration suite exercises warehouse translation, report compilation and evidence retrieval.