RFC: AgentRunFacet — OpenLineage Extension for Agentic AI

[swar00pduthks]

<style> </style>

RFC Author	Swaroop Duth — swaroopduthks@gmail.com
Status	PROPOSED — open for community discussion
Target Spec	OpenLineage 2.x (custom facet, candidate for promotion to standard)
Related Issues
Regulatory Drivers	EU AI Act Articles 12, 14, 19 · NIST AI RMF · Basel 3 / CCAR / Pillar 1 & 2
Compliance Deadline	EU AI Act high-risk AI — August 2, 2026

 

1. PROBLEM STATEMENT

 

OpenLineage's current entity model defines the world as: Job → Run → Dataset. This maps elegantly and completely to data pipeline lineage: a Spark job reads datasets, transforms them, produces output datasets. The spec — and Apache Marquez as its reference implementation — solve this problem well.

 

Agentic AI systems do not fit this model. When a multi-step LLM agent executes — retrieving context from multiple data sources, calling tools, delegating to sub-agents, reasoning across turns, and generating a final response — the provenance chain of that output is fundamentally different from a data pipeline:

 

▸   Which version of the data was retrieved as RAG context?

▸   Which model version and system prompt produced each reasoning turn?

▸   Which tool calls were made, with what inputs, producing what outputs?

▸   If the same agent runs again tomorrow with slightly different retrieved context, why does the answer differ?

▸   Which human reviewed or overrode the agent output, and when?

 

Observability tools (LangSmith, Datadog, Dynatrace) provide vendor-specific traces. These answer 'what happened' — but they are not lineage. Lineage answers 'why is this output what it is, what data produced it, and can I prove it to a regulator?' in a standardised, queryable, reproducible format that integrates with the rest of the data lineage graph.

 

Regulatory urgency

EU AI Act Article 12 requires automatic, tamper-evident logging for high-risk AI systems — including financial AI used for credit decisions, risk analytics, and fraud detection. Article 19 specifically requires financial institutions to maintain these logs under financial services law. Compliance deadline: August 2, 2026. No open standard currently exists to satisfy this requirement.

[arian-gogani]

The AgentRunFacet extension makes sense — lineage tracking for agent workflows is a natural fit for OpenLineage.

One layer that's missing from most lineage systems: behavioral enforcement evidence. Knowing that Agent X ran Tool Y at time T is useful for lineage. But knowing that Agent X was allowed to run Tool Y — and that this decision was enforced at runtime and logged in a tamper-evident hash chain — is what compliance teams actually need.

I've been building this as proof-of-behavior. Every agent action is evaluated against declared constraints before execution, and the decision goes into a SHA-256 hash chain. The log format includes action, params, outcome (success/blocked), and the chain hash.

For OpenLineage, the AgentRunFacet could include a behavioral_evidence field that references the proof-of-behavior log — bridging lineage (what ran) with compliance (was it allowed to run).

Spec: Proof-of-Behavior v0.1.0 (CC-BY-4.0)

[jakub-moravec]

@swar00pduthks this is a very good and timely discussion to have.

Did you have a chance to dig deeper and check what might actually be missing in the spec? This might be more about documenting how to use the spec for this use-case, than necessarily updating it (even though that's of course possible).

Let's start with the entities and how you'd model them. I'll start with a simple representation, please poke holes into to and suggest alternatives as you see fit.

RAG:

• embeddings store: dataset (e.g. Milvus is already documented in https://openlineage.io/docs/spec/naming)
• retrieval workflow: job

Agent

• agentic flow: job
• tool: sub-job (referencing the parent using https://openlineage.io/docs/spec/facets/run-facets/parent_run)

How to document what's needed

• Which version of the data was retrieved as RAG context?
  • https://openlineage.io/docs/spec/facets/dataset-facets/version_facet
• Which model version and system prompt produced each reasoning turn?
• So you want to have a lineage for every "answer" of the RAG, right? Technically, that would be a RUN event per prompt.
• Which tool calls were made, with what inputs, producing what outputs?
  • Tools can be captured as outlined above. Only those that were invoked will be documented. You will know where they got the data from and what data they created, but not which rows/vectors/etc they used exactly.
• If the same agent runs again tomorrow with slightly different retrieved context, why does the answer differ?
  • If you have the two events for the two prompts, you can compare them. Were the tools used the same? Was the version of the input data the same?
• Which human reviewed or overrode the agent output, and when?
  • For human-in-the-loop workflows, it might make sense the single agentic flow to multiple events
    • running event documenting what the agent did
    • running event documenting the user interference
    • complete event with the final outcome

Wdyt? Is this in the direction of what you were expecting?

[swar00pduthks]

Yes exactly my initial thought was as we need to also consider what dataset agents use to make a decision and also was thinking chat session is parent run and every conversation is child run and we need to also capture what skills and tools it used.

But we also need to capture the prompt and the response and maybe model used and confidence level which is specific to a conversation we want to capture

[swar00pduthks]

What I was thinking was like this

Job ──► AgentRun (RunFacet: AgentRunFacet)
│
├── model: { provider, modelName, modelVersion, systemPromptHash }
├── triggerType + triggerUserId
├── regulatoryContext: [EU_AI_ACT_ART12, CCAR, PILLAR1...]
│
├── turns[] ◄── the provenance chain
│ ├── turnId, turnType (REASONING|TOOL_CALL|RETRIEVAL|...)
│ ├── inputContextHash ◄── hash of full context window
│ ├── outputHash
│ └── toolCalls[] { toolName, inputHash, outputHash, datasetRef }
│
├── retrievedDatasets[] ◄── links to OL Dataset objects
│ └── { namespace, name, version, accessType }
│
├── humanCheckpoints[] ◄── EU AI Act Article 14
│ └── { userId, role, action, timestamp, justificationHash }
│
└── outputHash ◄── tamper-evident final output signature

[arian-gogani]

@JMoravec the modeling breakdown makes sense — agentic flow as job, tools as sub-jobs with parent_run references. That covers the lineage graph.

The gap I'd flag: OpenLineage captures what happened (which tool ran, what data flowed where) but not whether what happened was allowed. Two agents can produce identical lineage graphs where one followed its behavioral constraints and the other violated them.

That's the layer proof-of-behavior adds. Each tool call gets evaluated against declared constraints (permit/forbid/require) before execution, and the enforcement decision goes into a hash-chained audit trail. The lineage graph tells you the shape of execution. The behavioral proof tells you whether every step in that shape was compliant.

For OpenLineage specifically, this could surface as a facet — something like a BehavioralComplianceFacet on each RunEvent that carries the covenant hash, violation count, and a pointer to the full proof-of-behavior log. The facet is lightweight (just references), and any consumer can independently verify by replaying the log.

Happy to sketch out what that facet schema would look like if there's interest.

Ref: github.com/arian-gogani/nobulex

[jakub-moravec]

@arian-gogani It's not immediately obvious to me that this should be the responsibility of OpenLineage - it's a protection/governance layer on top of lineage, or rather leveraging lineage... should it be a part of the standard for lineage exchange? Or should that rather be covered by the governance/protection solution (OL consumer from this PoV)? Or data contracts (ODCS?)? Or something else?

@mobuchowski, interested in your PoV

[swar00pduthks]

@arian-gogani It's not immediately obvious to me that this should be the responsibility of OpenLineage - it's a protection/governance layer on top of lineage, or rather leveraging lineage... should it be a part of the standard for lineage exchange? Or should that rather be covered by the governance/protection solution (OL consumer from this PoV)? Or data contracts (ODCS?)? Or something else?

@mobuchowski, interested in your PoV

I Agree it's not open lineage responsibility to says the path agent took is right or wrong. It's responsibility to capture the path and provide it as input to evaluate if it took right path

[swar00pduthks]

@jakub-moravec how do we take this forward should we sketch out any design together or i am new to contributing to open lineage .. I was mainly using open lineage / marquez so please guide

[jakub-moravec]

@swar00pduthks I would split this to two parts

• documenting how to model the agentic flows in the OpenLineage model, I'd suggest adding an example in https://openlineage.io/docs/spec/examples (happy to help with this later, but I'm away from laptop till May 18th)
• designing the facet for the approval trails - can be done separately in feat(spec): AgentAttributionRunFacet for agent-produced lineage events #4480 (comment)

[arian-gogani]

@JMoravec That's a fair distinction — OpenLineage captures the path, a separate governance layer evaluates whether the path was compliant. Agree that keeping those concerns separate is cleaner.

Nobulex would sit on the consumer side in that model. OpenLineage emits the lineage events, Nobulex (or similar) ingests them and evaluates against declared behavioral constraints. The facet idea was more about embedding a lightweight reference pointer (just a hash) so consumers can correlate lineage events with compliance records without a separate join — but I see the argument for keeping that coupling out of the core spec.

Happy to follow wherever the discussion lands. If ODCS or a dedicated governance facet extension ends up being the right home, that works too.

[JMoravec]

I think you're tagging the wrong JMoravec :P