Opaque governance references for GenAI agent decision points

[AgentGymLeader]

Agent traces can show what happened during a model call, tool call, or agent step. For enterprise agent runtimes, operators may also need to correlate a decision point with producer-owned records that should not be carried in telemetry payloads, such as the policy, review, approval, workflow, or execution-context records that governed the action.

Would it be useful for GenAI agent conventions to document a small set of payload-free, producer-defined opaque reference attributes for those join points?

Possible attributes:

• gen_ai.agent.decision.id
• gen_ai.agent.decision.outcome
• gen_ai.agent.governance.ref

Telemetry would treat each *.ref value only as an opaque string. The referenced record formats, schemas, lifecycles, validation behavior, and governance semantics would remain implementation-defined and out of scope for the semantic convention.

Non-goals: policy schema, approval workflow schema, execution-context record format, external evidence format, external business meaning, validation behavior, or propagation rules. The convention would only define a safe reference surface for downstream joins without putting external-system payloads into telemetry.

Related discussion: #132 / #165 discuss opaque producer-defined correlation references for threat detection; this issue asks whether a similar payload-free reference surface is useful for agent decision points more generally.

[AgentGymLeader]

A small clarification on the boundary I intended here: I think the useful standard surface is the join point, not the producer-owned context behind it.

If this moves forward, I would keep the candidate attributes deliberately narrow:

attribute	intent	note
gen_ai.agent.decision.id	correlate one decision point	opaque, producer-defined, not interpreted by the convention
gen_ai.agent.decision.outcome	record the observed decision result	small enum such as allow, block, review, escalate, defer
gen_ai.agent.governance.ref	point to producer-owned governance context	opaque string; the referenced context remains out of scope

Good values should look like opaque handles, for example ctx_7f3a9c or decision_01J.... Bad values would be embedded JSON, prompts, tool arguments, policy bodies, user data, or any other payload that the span would then be carrying directly.

I would also treat these as span/event/log material, not metric labels, because the values are likely high-cardinality.

Non-goals I would keep explicit: no governance workflow schema, no external context format, no validation behavior, no propagation rules, no record lifecycle, and no business meaning for the referenced context.

One open question is namespace: should this stay under gen_ai.agent.* because the immediate target is GenAI agent spans, or should it follow the broader agent.* direction discussed in #132/#165 for controls that may sit at proxy, host, or wrapper boundaries?

[Rul1an]

I like keeping the standardized surface at the join point and leaving the referenced context opaque, because that matches how this actually gets produced. The thing gen_ai.agent.governance.ref points at, in our case, is a signed, content-addressed evidence record, and keeping it an opaque handle like ctx_7f3a9c is exactly right: that record is verified out of band, so inlining its hashes or structure into the span would re-litigate an attestation format as telemetry schema and would tempt people to start carrying payload on the span. Opaque handle plus payload-free is the correct call, and treating these as span or event material rather than metric labels matches the high cardinality.

On the open namespace question, I would lean toward the broader agent.* direction from #132 and #165 for the decision, outcome and ref trio rather than gen_ai.agent.*. In our setup the allow or block is decided out of process, at a proxy and at a kernel-level enforcement layer, not inside the model or provider span, and the control point is frequently not GenAI-specific at all. You want the same attribute set whether the decision came from an in-process guard or from an external sandbox, and pinning it under gen_ai.* makes the out-of-process case look like a second-class citizen.

One small thing on the outcome enum. A decision that resolves to blocked before execution should still leave a span or event behind. The absence of a child execute_tool span together with a terminal block outcome is what makes a denial auditable; if a blocked call simply produces no telemetry, "denied" and "never attempted" become indistinguishable after the fact. We emit exactly these as span and event attributes in assay, with the governance ref pointing at the signed record, and that deny-is-not-a-missing-trace invariant turned out to matter more than the enum values themselves.

[AgentGymLeader]

Yeah, this helps — thanks. Keeping the referenced context verified out of band feels like the right line to draw: *.ref stays useful, and the span doesn't end up carrying the evidence itself. It's an architectural boundary, not a security claim, which is the part that keeps it clean.

Your proxy and enforcement-layer examples are also a good argument for leaving the namespace question open for now. If the decision can happen outside model execution, the attributes really should describe the control decision itself, not just a provider call.

And the blocked-before-execution case is a good one to call out. A denied attempt should still leave something behind — a span or an event — otherwise "blocked by policy," "no telemetry," and "the thing crashed" all look identical downstream. That distinction is what makes the reference useful.

[rpelevin]

I like keeping the convention at the join point and not standardizing the referenced governance object.

One distinction I would make explicit is that a blocked decision is still an observable decision point. If no tool call executes, telemetry still needs a payload-free way to distinguish "blocked by policy" from "agent crashed" or "nothing happened."

A minimal lifecycle could be represented as span events or attributes around the control point:

• decision id: opaque producer-defined handle;
• decision type: tool_call, model_step, handoff, workflow_resume, or external_action;
• outcome: allow, block, defer, review_required, or stale;
• governance ref: opaque producer-defined reference;
• target kind: tool, resource, workflow, or agent;
• correlation id to the attempted action, when one exists.

I would avoid putting prompts, arguments, policy bodies, evidence hashes, or user data into the semantic convention. If an implementation wants hashes, signatures, or receipts, those can live behind the opaque ref.

Acceptance questions for the convention:

• can a denied tool attempt leave a useful event without a tool.executed span?
• can a proxy or policy layer record the decision even if it is not inside the model provider call?
• can high-cardinality refs be clearly marked as span/event material, not metric labels?
• can downstream systems join on the opaque ref without interpreting its format?

That preserves the standard as telemetry, not governance-schema design.

[AgentGymLeader]

@rpelevin Agreed on the split.

The part that matters to me: the convention can make the decision point observable without pulling the referenced governance object into the convention itself.

A blocked decision is still useful telemetry even when nothing downstream runs — a reader can tell "policy blocked this" apart from "the agent crashed" or "nothing happened," without prompts, arguments, policy bodies, evidence hashes, or user data ever entering the semantic convention.

Keeping the reference opaque is the right call too. A downstream system that understands the producer can join on it; the convention doesn't need to interpret the format.

[Rul1an]

Happy to answer rpelevin's four acceptance questions from the producing side, since we already run all four in assay rather than as a proposal.

Yes, a denied attempt leaves a useful event without a tool.executed span: the decision point emits its own span and event with the outcome and the opaque ref, and the deliberate absence of a child execution span beside a terminal block is what makes the denial readable afterwards. Yes, it is recorded outside the model provider call, because the allow/block resolves at a proxy and at a kernel enforcement layer, so the control point produces the event rather than the provider span. The refs stay span and event material and never metric labels, being high-cardinality opaque handles by construction. And downstream joins run purely on the opaque ref: it points at a signed, content-addressed record verified out of band, so a consumer that knows the producer resolves it while the convention never parses the format.

So from an implementer's seat none of the four are really open questions; they are satisfiable today, which feels like a good sign for keeping the standard at the join point and the referenced object out of scope.