Data Agents Need Governed Metric Definitions, Not Just Table Access
OpenAI’s data team argues that data agents need a governed semantic layer—not merely access to warehouse tables or SQL—to interpret metrics according to a company’s agreed definitions, populations, filters and source hierarchy. The team says organizations should reuse existing semantic work where possible, but have domain experts resolve contradictions and review the layer before distributing it as a shared skill. Maintaining that foundation is an ongoing governance responsibility, not a one-time plugin setup.
A data agent needs governed definitions, not just access to tables
A data agent cannot reliably answer a business question simply because it can generate SQL or reach a warehouse. It needs the rules that determine who counts, what a metric measures, which filters apply, how time is bounded, and which source is authoritative when definitions conflict. Those rules are often scattered among tools, documents, dashboards, code, and the people who maintain the data.
The semantic layer shown here is intended to consolidate that knowledge into a shared reference an agent can use. In the displayed “Sites” adoption and lifecycle example, the layer specifies the data’s scope, intended users, unit of analysis, warehouse snapshot, reporting cutoff, and canonical metric-definition source. It also marks limitations: the reference is incomplete for maintained transformation lineage and data-engineering migration.
That context is not administrative detail. The guide identifies the data as synthetic, instructs users to work with complete weeks, and records a cutoff date for the warehouse snapshot. An answer can be technically valid while still being misleading if it ignores those constraints.
The proposed workflow is to turn this existing business knowledge into a reusable skill through a data plugin. Rather than asking an agent to infer a company’s definitions from raw tables each time, the organization makes its agreed interpretation of a bounded domain accessible and shareable.
Metric names are insufficient without populations, exclusions, and precedence
The displayed reference defines entities at a level that distinguishes populations which might otherwise be treated as interchangeable. An “eligible user” is a human in an external organization whose eligibility date falls on or before the measured week’s start. It excludes viewers, internal and test users, service identities, and Work users. Its grain is user by week.
A “creator” is likewise measured by user-week, but requires successful create, edit, or publish activity. The definition excludes viewer-only activity, Sites-page visits, example opens, request starts, and unsuccessful actions. A viewer is an external human with a successful site_view, and is not necessarily eligible to create. A Sites-page visitor is a separate population based on an entrypoint impression—not a required funnel stage or every possible indication of awareness.
These distinctions determine the resulting metrics.
| Metric | Definition | Population or caveat |
|---|---|---|
| Creator WAU | Distinct eligible users with successful create, edit, or publish activity | Eligible users at week start; counts actors, not actions |
| Creator adoption rate | Share of mature first-page visitors who are also creators | Measured at cohort week plus user as creator_v2 / visit_v1 |
| Viewer WAU | Distinct external human viewers with site_view | May overlap with creators outside WAU |
The reference also ranks the sources an analyst or agent should use when information differs. A maintained metric contract with an explicit definition version and approval status comes first. Maintained transformation code and tests follow when their locations are resolved, then live catalog metadata, source rows, and governed views used for fixture reconciliation. Verified dashboard-query metadata and result tables come after that. Team communication can supply recent clarification and decision context, but the guide says it must not silently replace a canonical definition.
That hierarchy is a governance rule, not a documentation preference. It tells the agent that a Slack message is not automatically equivalent to an approved metric contract, and that availability is not the same as authority.
The same guide establishes standard logic for external-human status, weekly eligibility, event deduplication, completeness, and user aggregation. For event analysis, it retains one delivery per event_id, using the latest ingested_at and a stable delivery tie-breaker. For WAU, adoption, and lifecycle counts, it directs users to count distinct users rather than actions.
Conflicting time logic has to be resolved before the layer is shared
The displayed reference contains two incompatible definitions of a reporting week. Its quick reference describes a week as beginning Sunday at 00:00 UTC and running until the following Monday, exclusive. Its standard-filters section instead defines the boundary as Monday at 00:00 UTC through the next Monday, exclusive.
The source does not say which rule controls. That makes the contradiction materially important: a weekly metric, cohort, eligibility calculation, or completeness test can change depending on the selected boundary. Before such a layer is deployed as a shared skill, the conflict needs to be resolved and the controlling definition versioned rather than left for an agent to choose between.
The speakers say someone from the data team who knows the underlying data should review and refine the layer. The artifact is meant to include entities, metrics, standard filters and dimensions, open questions, and known pitfalls; expert review is the step that turns that collection into something the team considers ready to package and distribute.
Reuse existing semantic work, but assign ongoing ownership
A relatively well-contained domain is presented as the practical place to start. The “Sites” example is deliberately scoped to adoption, activation, creation-to-publication, and repeat usage, with named source materials and a stated warehouse context. A bounded domain gives the team a manageable set of populations, metric contracts, and caveats to make explicit.
The work need not begin from scratch. If a company has already invested in a semantic layer—whether as a skill or in systems such as Snowflake Cortex or Databricks Genie—the source says that material can be brought into the agent’s context. The objective is to reuse established organizational knowledge, not recreate it merely because the interface to that knowledge is changing.
But packaging a reference into a plugin does not make semantic governance a one-time setup task. The speakers describe it as focused work requiring a team that continues to invest in it. The layer must remain aligned with the business’s definitions, data environment, and unresolved questions if it is to give an agent a dependable basis for analysis.