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. For connection setup and support tiers, start with Agent Quickstart.

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.
Run the query with query, which validates and compiles it first. validate and compile are optional dry runs; compile returns the explain payload.

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: run a plan draft only when its status is "ok" and it has no warnings, and compare best.query with the question first: the checks don't cover every phrasing. 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. A dimension can advertise five categories while the underlying table only has two. On engine 0.3.2, execute warns FILTER_VALUE_NOT_FOUND when a text is filter value matches no row the caller can read (under the default observation_scope: "dataset"), with a likely spelling where it finds one.

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.