ClariLayer Docs

AI Agent Context

Guides

AI Agent Context Guide

How to ground AI agents with ClariLayer metric context while preserving lifecycle state, caveats, and traceability.

AI agents should not guess which business metric definition is canonical. A useful agent reads the governed context first, answers from the approved definition when it can, and surfaces caveats when the context says the metric is draft, ambiguous, deprecated, or still under discussion.

This guide describes the current read-only v1 pattern. It uses API keys, the metrics discovery routes, and the metric contract envelope.

Before wiring an agent, understand the product signals it must respect: registry discovery, validation evidence, governance and release state, Reasoning Trail notes, and the contract envelope.

Read Metric Registry, Warehouse Validation, Governance and Release, The Reasoning Trail, and Metrics Contract API when you need the product context behind those fields.

The safe read pattern

Use three steps:

  1. Search or list metrics with GET /api/v1/metrics.
  2. Fetch detail with GET /api/v1/metrics/{id} when the agent needs broader definition and governance metadata.
  3. Fetch the contract with GET /api/v1/metrics/{id}/contract before using the metric in an answer, prompt, or tool call.

The contract response is the prompt-facing source of truth. The detail route is useful for richer UI or tool context, but the contract route is the compact agent envelope.

Discovery

Start with search when the user asks for a metric by name:

GET https://app.clarilayer.com/api/v1/metrics?q=active%20customers&page=1&pageSize=10
Authorization: Bearer cl_0000000000000000000000000000000000000000

If search returns multiple candidates, the agent should use names, lifecycle status, scope, concept, and policy tier to choose. When the candidates still conflict, ask the user to choose rather than silently selecting a metric with a similar name.

Prefer lifecycle_status over the deprecated status field. Treat RELEASED and APPROVED as the strongest signals. Treat DRAFT, VALIDATED, and CANDIDATE as pre-release context unless the workflow explicitly allows advisory answers. Treat DEPRECATED as readable historical context, not the default answer.

Contract fetch

Fetch the contract before answering:

GET https://app.clarilayer.com/api/v1/metrics/5e6f7a1b-2c3d-4e5f-8a9b-0c1d2e3f4a5b/contract
Authorization: Bearer cl_0000000000000000000000000000000000000000
Accept: application/json

The route requests canonical-metric-api:read. New Agent Contract keys have that scope by default. Older metrics:read keys remain compatible with the current read model.

Build the prompt context

A simple prompt context should include:

  • name
  • business_definition
  • current_approved_version
  • last_validated_at
  • lifecycle_status
  • open_challenges_count
  • requires_disambiguation
  • agent_context_notes
  • discourse_summary
  • canonical_url

Do not paste the entire detail envelope into the prompt by default. Keep the prompt focused on the fields that affect meaning, trust, and response behavior. Store the raw JSON in your tool trace if your system needs auditability.

Respect lifecycle state

Use lifecycle state to shape the answer:

  • RELEASED: answer normally and cite the definition version if useful.
  • APPROVED: answer from the approved context, but avoid implying it has been released if current_approved_version is null.
  • CANDIDATE or VALIDATED: say the metric has passed checks or is under review, then answer only if advisory context is acceptable.
  • DRAFT: avoid production claims. Ask for confirmation before using the metric for decisions.
  • DEPRECATED: explain that the metric is retired and use deprecation framing if supplied.

If last_validated_at is null, the agent should avoid saying the metric has recent validation evidence.

Use Reasoning Trail signals

The Reasoning Trail appears in the contract through discussion counts, pinned notes, and the discourse summary.

agent_context_notes are curated for agent use. They can contain decision rationale, clarifications, or objections that should travel with the answer.

discourse_summary signals live objections or proposals. If open_objections_count is greater than 0, include a caveat in the answer. If it is null, do not infer that no discussion exists; other note types may still exist, and supporting reads can degrade to stable defaults.

discussion_thread_count and discussion_message_count help the agent know whether human discussion exists at all. Counts can default to 0 when a supporting read fails, so treat them as signals, not proof of absence.

Handle managed variants

Managed variants are legitimate when different teams need different definitions. Agents should not collapse variants into one answer.

When multiple metrics share a concept but have different scope, domain_id, policy tier, or owner, choose the version that matches the user's context. If the user asks a broad question and there are both enterprise-canonical and domain-canonical candidates, prefer the enterprise-canonical metric unless the user names a domain. If there are multiple plausible domain variants, ask a clarifying question.

When requires_disambiguation is populated, follow its policy instead of inventing your own clarification behavior.

Optional discussion summary

The contract route supports ?summary=true for a natural-language discussion summary:

GET https://app.clarilayer.com/api/v1/metrics/5e6f7a1b-2c3d-4e5f-8a9b-0c1d2e3f4a5b/contract?summary=true
Authorization: Bearer cl_0000000000000000000000000000000000000000

The summary can be null when generation is unavailable, capped, degraded, or unnecessary. The response includes discussion_summary_meta when the summary path runs and an X-Discussion-Summary-Charged header with 0 or 1.

Use the summary as a convenience layer, not as the only source. The structured fields remain the contract.

Cache carefully

Agents and gateways may cache contract responses, but cache invalidation should respect the fields that change meaning:

  • current_approved_version.released_at
  • last_validated_at
  • lifecycle_status
  • discourse_summary.last_activity_at
  • the set of agent_context_notes

If those values change, refresh the prompt context before answering. If the user asks for the current definition, fetch fresh context rather than relying on stale memory.

Answer shape

A good answer grounded in ClariLayer sounds like this:

Active Customer Count means customers with at least one billable subscription in the trailing 30 days, excluding internal test workspaces. The metric is RELEASED on definition version 2.1.0 and was last validated on 2026-05-09. One pinned note says the 30-day window anchors on UTC midnight. There is one open objection about whether free-tier customers should be reported separately, so use this answer with that caveat for ARR-facing analysis.

That answer uses the approved definition, names trust state, and carries the human caveat. It does not pretend the warehouse SQL alone contains the business truth.

See also