version:0.1 doc:agent-actions updated:2026

Agent Actions

This page replaces the old action-runtime framing. The active integration story is a staged public query path that lets apps and agents inspect catalog context, ask for build options, validate, compile, and execute without jumping straight to raw SQL.

Preferred user path

Discover a business term with discover.
Inspect the semantic object card with inspect.
Ask for the next legal patch with build-options.
Use valid-values when a categorical filter needs concrete values.
Use validate, compile, and then query. The compile response includes an explain payload inline.

Why this flow exists

It reduces guesswork for human users and agents.
It exposes planner-backed guardrails before execution.
It keeps apps and agents honest about what the runtime can and cannot express.

Client responsibilities

Surface	Role
Catalog	Browse metrics, measures, dimensions, entities, temporal roles, and value domains
Inspect	Show object summary, compatible clocks, sample questions, and starter patches
Build state	Apply recommended or available patches without mutating hidden planner state
Raw query handoff	Keep raw JSON editing and lower-level surfaces available when needed
Segment preview	Validate and preview authored segments without altering the working query

Representative request path

guided flow

POST /api/v1/discover   {"terms":"revenue by store"}
POST /api/v1/inspect    {"object_id":"measure.jaffle.revenue_usd"}
POST /api/v1/build-options
POST /api/v1/valid-values
POST /api/v1/validate
POST /api/v1/compile
POST /api/v1/query

When to use plan

Use plan when the user gives a natural-language analysis intent and needs a validated Query IR draft. Use build-options when the caller already has a partial query and wants the next legal edits.

Agent gotcha: plan pays the validation cost before returning status="ok". Do not skip the final compile or execute step; use the returned Query IR as the reviewed draft and keep user-visible assumptions in the answer.

Value domains vs warehouse data

valid-values returns the declared value domain for a dimension — the values authored or sourced from a value_domain / valid_values configuration. The runtime does not currently warn when the declared domain diverges from what is actually present in the warehouse. A dimension can advertise five categories while the underlying table only has two; a filter on one of the missing values returns an empty result with no diagnostic.

For categorical dimensions where the declared domain may be aspirational, authors should treat valid-values output as the authoring contract, not as a guarantee of warehouse coverage, and verify against execute on the underlying measure when answering customer- facing questions.

The API surface is intentionally staged so agents, app backends, and human-authored docs can all show the same reasoning steps without coupling the repo to a bundled frontend.

Continue to Guardrails for runtime boundaries and failure modes that builders should expect.