| Internet-Draft | Verifiable ACRs | February 2026 |
| Birkholz, et al. | Expires 29 August 2026 | [Page] |
Autonomous agents based on large language models increasingly perform consequential tasks on behalf of humans and other agents. Demonstrating that recorded agent behavior truthfully represents actual behavior is essential for accountability, compliance, and human oversight. This document defines a data format for verifiable agent conversation records using CDDL, with representations in both JSON and CBOR. The format captures session metadata, message exchanges, tool invocations, reasoning traces, and system events in a structured, extensible CDDL definition for verifiable agent conversation records. COSE is used as the signing method to allow for native interoperability in SCITT Transparency Services and the CDDL definition allows for seemless integration in Evidence as specified in RFC 9334. The specification supports cross-vendor interoperability by defining a common representation that accommodates translation from multiple existing agent implementations with distinct data structure layouts that are typically represented in JSON.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 29 August 2026.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
The question of whether the recorded output of an autonomous agent faithfully represents an agent's actual behavior has found new urgency as the number of consequential tasks that are delegated to agents increases rapidly. Autonomous Agents--typically workload instances of agentic artificial intelligence (AI) based on large language models (LLM)--interact with other actors by design. This creates an interconnected web of agent interactions and conversations that is currently rarely supervised in a systemic manner. In essence, the two main types of actors interacting with autonomous agents are humans and machines (e.g., other autonomous agents), or a mix of them. In agentic AI systems, machine actors interact with other machine actors. The number of interactions between machine actors grows significantly more than the number of interactions between human actors and machine actors. While the responsible parties for agent actions ultimately are humans--whether a natural legal entity or an organization--agents act on behalf of humans and on behalf of other agents. To demonstrate due diligence, responsible human parties require records of agent behavior to demonstrate policy compliant behavior for agents acting under their authority. These increasingly complex interactions between multiple actors that can also be triggered by machines (recursively) increase the need to understand decision making and the chain of thoughts (CoT) of autonomous agents, retroactively (i.e., accountability and auditability after the fact).¶
The verifiable records of agent conversations that are specified in this document provide an essential basis for operators to detect divergences between intended and actual agent behavior after the interaction has concluded.¶
For example:¶
This document defines conversation records representing activities of autonomous agents such that long-term preservation of the evidentiary value of these records across chains of custody (CoC) is possible.¶
This document defines verifiable records of agent conversations as a building block towards seven dedicated goals:¶
Most agent conversations today are represented in "human-readable" text formats. For example, JSON [STD90] is considered to be "human-readable" as it can be presented to humans in human-computer-interfaces (HCI) via off-the-shelf tools, e.g., pre-installed text editors that allow such data to be consumed or modified by humans. The Concise Binary Object Representation (CBOR [STD94]) is used as an alternative representation next to the established representation that is JSON.¶
In this version of the document the signing of JSON payloads is done via [STD90]. Using [STD90] enables interoperability with Transparency Services specified by the IETF [I-D.ietf-scitt-architecture] and enables low-threshold cross-application and cross-stakeholder interoperability across the Internet.¶
Note: further improvements in support of in-memory processing, further compacting human-readable text strings, and using CBOR as an alternative representation for verifiable records of agent conversations will follow.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
In this document, CDDL [RFC8610] is used to describe the data formats of agent conversations for JSON and CBOR (with no optimization for CBOR, currently).¶
The reader is assumed to be familiar with the vocabulary and concepts defined in [RFC9334] and [I-D.ietf-scitt-architecture].¶
This section identifies the intersection of logging, traceability, and record-keeping requirements across major compliance frameworks applicable to AI systems. The verifiable agent conversation format defined in this document addresses these requirements by providing a standardized, cryptographically verifiable record of AI agent interactions.¶
The following frameworks were analyzed for their requirements on AI agent traceability and session logging:¶
| Framework | Jurisdiction | Sector | Status |
|---|---|---|---|
| EU AI Act [EU_AI_ACT_2024] | EU | Cross-sector | In force Aug 2024 |
| Cyber Resilience Act [EU_CRA_2024] | EU | Products with digital elements | In force Dec 2024 |
| NIS2 Directive [EU_NIS2_2022] | EU | Essential/important entities | Transposed Oct 2024 |
| ETSI TS 104 223 [ETSI_TS_104223_2025] | EU/International | AI systems | Published Apr 2025 |
| SOC 2 Trust Services Criteria [AICPA_TSC_2017] | US/International | Service organizations | Active |
| FedRAMP [NIST_SP_800_53_R5] [OMB_M_21_31] | US | Federal cloud services | Active |
| PCI DSS [PCI_DSS_V4_0_1] | International | Payment card industry | Mandatory Mar 2025 |
| ISO/IEC 42001 [ISO_IEC_42001_2023] | International | AI management systems | Published 2023 |
| FFIEC IT Handbook [FFIEC_IT_HANDBOOK_2024] | US | Financial institutions | Updated 2024 |
| BSI AI Finance Test Criteria [BSI_AI_FINANCE_2024] | Germany | Financial sector AI | Published 2024 |
| NIST AI 100-2 [NIST_AI_100_2_E2025] | US | Cross-sector | Published 2025 |
The analysis of the frameworks listed above results in eleven categories of requirements that appear across ALL or MOST frameworks. These categories frame and represent a minimum baseline that verifiable agent conversation records MUST support.¶
All frameworks require automatic, system-generated logging of events without reliance on manual recording. Explicit requirements are listed as follows:¶
| Framework | Requirement |
|---|---|
| EU AI Act Art. 12 | "High-risk AI systems shall technically allow for the automatic recording of events (logs)" |
| ETSI TS 104223 5.4.2-1 | "System Operators shall log system and user actions" |
| SOC 2 CC7.2 | "Complete and chronological record of all user actions and system responses" |
| FedRAMP AU-12 | "Audit Record Generation" control requirement |
| PCI DSS 4.0 Req 10 | "Audit logs implemented to support detection of anomalies" |
| ISO 42001 A.6.2.8 | "AI system recording of event logs" |
Mapping to this specification:
The entries array in session-trace captures all events automatically.
Each entry represents a discrete, system-recorded event with structured metadata.¶
Most frameworks require precise temporal information for each logged event. Explicit requirements are listed as follows:¶
| Framework | Requirement |
|---|---|
| EU AI Act Art. 12(2) | "Precise timestamps for each usage session" (biometric systems) |
| PCI DSS 4.0 Req 10.6 | "Time-synchronization mechanisms support consistent time settings" |
| SOC 2 | "When the activity was performed via timestamp" |
| NIS2 | "Precise logging of when an incident was first detected" |
Mapping to this specification:
The timestamp field in each entry uses abstract-timestamp which accepts both RFC 3339 strings and POSIX Seconds since Epoch, ensuring interoperability across implementations.¶
Most frameworks require some attribution of actions to identifiable actors (human or system). Explicit requirements are listed as follows:¶
| Framework | Requirement |
|---|---|
| EU AI Act Art. 12(3)(d) | "Identification of the natural persons involved in the verification of results" |
| SOC 2 | "The process or user who initiated the activity (Who)" |
| PCI DSS 4.0 | Attribution to "Who" performed each action |
| FedRAMP AC-2 | Account management and identification |
Mapping to this specification:
The contributor type captures actor attribution with type (human/ai/mixed/unknown) and optional model-id.
Session-level agent-meta identifies the AI system.¶
All frameworks require recording of what action or event occurred. Explicit requirements are listed as follows:¶
| Framework | Requirement |
|---|---|
| EU AI Act Art. 12 | "Events relevant for identifying situations that may result in...risk" |
| ETSI TS 104223 5.2.4-3 | "Audit log of changes to system prompts or other model configuration" |
| SOC 2 | "The action they performed such as file transferred, created, or deleted (What)" |
| PCI DSS 4.0 | "What" component of audit trail |
Mapping to this specification:
The type field in each entry discriminates event types: user, assistant, tool-call, tool-result, reasoning, system-event.¶
All AI-specific frameworks require recording of inputs (prompts) and outputs (responses). Explicit requirements are listed as follows:¶
| Framework | Requirement |
|---|---|
| EU AI Act Art. 12(3)(c) | "The input data for which the search has led to a match" |
| PCI DSS AI Guidance | "Logging should be sufficient to audit the prompt inputs and reasoning process" |
| ETSI TS 104223 5.1.2-3 | "Operation, and lifecycle management of models, datasets and prompts" |
| FFIEC VII.D | "Lack of explainability...unclear how inputs are translated into outputs" |
Mapping to this specification:¶
Most frameworks specify minimum retention periods for audit logs. Explicit requirements are listed as follows:¶
| Framework | Minimum Retention |
|---|---|
| EU AI Act Art. 19 | 6 months (longer for financial services) |
| FedRAMP (M-21-31) | 12 months active + 18 months cold storage |
| PCI DSS 4.0 | 12 months total, 3 months immediate access |
| NIS2 | Per member state law |
Recommendation: Implementations SHOULD retain verifiable agent conversation records for at least 12 months to satisfy the most common requirement threshold.¶
All frameworks require some protection against unauthorized modification of logs. Explicit requirements are listed as follows:¶
| Framework | Requirement |
|---|---|
| PCI DSS 4.0 Req 10.5 | "Tamper-proof audit trails...logs cannot be altered retroactively" |
| FedRAMP | "Effective chain of evidence to ensure integrity" |
| SOC 2 | Log integrity as security control |
| CRA | "Tamper-proof SBOMs and vulnerability disclosures" |
Mapping to this specification:
The signed-agent-record type (COSE_Sign1 envelope) provides cryptographic integrity protection.
The content-hash field in trace-metadata enables verification of payload integrity.¶
All frameworks require some logs to support incident investigation and response. Explicit requirements are listed as follows:¶
| Framework | Requirement |
|---|---|
| NIS2 Art. 23 | 24-hour initial notification, 72-hour assessment |
| CRA | 24-hour vulnerability notification to ENISA |
| ETSI TS 104223 5.4.2-1 | Logs for "incident investigations, and vulnerability remediation" |
| FedRAMP | Incident reporting and continuous monitoring |
Mapping to this specification: The structured format enables rapid extraction of relevant entries by timestamp range, event type, or tool invocation for incident reconstruction.¶
All frameworks require some logs to enable detection of anomalous or risky behavior. Explicit requirements are listed as follows:¶
| Framework | Requirement |
|---|---|
| EU AI Act Art. 12(2)(a) | "Identifying situations that may result in...risk" |
| ETSI TS 104223 5.4.2-2 | "Detect anomalies, security breaches, or unexpected behaviour" |
| FedRAMP SI-4 | "Anomaly detection" |
| SOC 2 | "Anomaly detection" for security monitoring |
Mapping to this specification:
The standardized entry types and structured tool-call/tool-result pairs enable automated analysis for detecting:¶
All AI-specific frameworks require logs to support human review and oversight. Explicit requirements are listed as follows:¶
| Framework | Requirement |
|---|---|
| EU AI Act Art. 26(5) | "Monitoring the operation of high-risk AI systems" |
| ETSI TS 104223 5.1.4-1 | "Capabilities to enable human oversight" |
| ISO 42001 | Human responsibility and accountability |
| FFIEC VII.D | "Dynamic updating...challenges to monitoring and independently reviewing AI" |
Mapping to this specification:
The reasoning-entry type captures chain-of-thought content (where available), enabling human reviewers to understand AI decision-making processes.
The hierarchical children field preserves conversation structure.¶
All frameworks require some ability to trace system behavior and reconstruct events. Explicit requirements are listed as follows:¶
| Framework | Requirement |
|---|---|
| EU AI Act Art. 12 | "Level of traceability of the functioning...appropriate to the intended purpose" |
| ISO 42001 | "Traceability" as key factor including "data provenance, model traceability" |
| CRA | "Traceability in the software supply chain" |
| ETSI TS 104223 5.2.1-2 | "Track, authenticate, manage version control" |
Mapping to this specification:¶
For AI systems classified as high-risk under Annex III of the EU AI Act [EU_AI_ACT_2024], additional requirements apply:¶
Biometric identification systems (Annex III, 1(a)) require logging of:¶
ETSI TS 104 223 [ETSI_TS_104223_2025] provides the most detailed AI-specific logging requirements:¶
| Provision | Requirement | This Spec Mapping |
|---|---|---|
| 5.1.2-3 | Audit trail for "operation, and lifecycle management of models, datasets and prompts" |
session-trace, agent-meta
|
| 5.2.4-1 | "Document and maintain a clear audit trail of their system design" |
recording-agent, open maps |
| 5.2.4-3 | "Audit log of changes to system prompts or other model configuration" |
event-entry with prompt changes |
| 5.4.2-1 | "Log system and user actions to support security compliance, incident investigations" |
entries array |
| 5.4.2-2 | "Analyse their logs to ensure...desired outputs and to detect anomalies" | Structured format enables analysis |
| 5.4.2-3 | "Monitor internal states of their AI systems" |
reasoning-entry, token-usage
|
The PCI Security Standards Council has published guidance on AI in payment environments [PCI_DSS_V4_0_1]: "Where possible, logging should be sufficient to audit the prompt inputs and reasoning process used by the AI system that led to the output provided."¶
This specification directly addresses this requirement through:¶
Financial institutions face additional scrutiny for AI systems per [FFIEC_IT_HANDBOOK_2024] and [BSI_AI_FINANCE_2024]:¶
| Requirement Area | FFIEC | BSI AI Finance |
|---|---|---|
| Explainability | "Lack of transparency or explainability" risk | Test criteria for explainability |
| Dynamic updating | "Challenges to monitoring and independently reviewing AI" | Continuous validation |
| Audit trail | Log management (VI.B.7) | Complete audit trail |
The following table maps this specification's data elements to compliance requirements:¶
| Data Element | EU AI Act | ETSI 104223 | SOC 2 | FedRAMP | PCI DSS | ISO 42001 | NIS2 |
|---|---|---|---|---|---|---|---|
timestamp
|
Art. 12(2) | 5.4.2-1 | CC7.2 | AU-8 | 10.6 | A.6.2.8 | Art. 23 |
session-id
|
Art. 12 | 5.2.4-1 | CC7.2 | AU-3 | 10.2 | A.6.2.8 | - |
entry.type
|
Art. 12(2) | 5.4.2-1 | CC7.2 | AU-3 | 10.2 | A.6.2.8 | - |
contributor
|
Art. 12(3)(d) | 5.1.4 | CC6.1 | AC-2 | 10.2 | A.6.2.8 | - |
message-entry.content
|
Art. 12(3)(c) | 5.1.2-3 | - | - | AI Guide | - | - |
reasoning-entry
|
Art. 12 | 5.4.2-3 | - | - | AI Guide | A.7.1 | - |
tool-call-entry / tool-result-entry
|
Art. 12 | 5.4.2-1 | CC7.2 | AU-12 | 10.2 | A.6.2.8 | - |
signed-agent-record
|
Art. 19 | 5.2.4-1.2 | CC6.1 | AU-9 | 10.5 | - | - |
vcs-context
|
- | 5.2.1-2 | - | CM-3 | - | A.6.2.8 | - |
token-usage
|
- | 5.4.2-4 | - | - | - | - | - |
Per PCI DSS [PCI_DSS_V4_0_1] Req 10.5 and FedRAMP [NIST_SP_800_53_R5] AU-9, logs MUST be protected against modification. Implementations SHOULD:¶
Per FedRAMP [NIST_SP_800_53_R5] AC-3 and ETSI [ETSI_TS_104223_2025] 5.2.2-1, access to logs MUST be controlled:¶
This section defines each complex data type specified in the verifiable agent conversation record CDDL data definition. Each subsection illustrates a CDDL fragment for one type, a brief description, and per-member documentation.¶
The schema uses the following generic type definitions throughout.¶
An RFC 3339 date-time string or numeric epoch milliseconds. New implementations SHOULD use RFC 3339 strings; consumers MUST accept both forms.¶
An opaque string uniquely identifying a conversation session. Values may be UUID v4, UUID v7, SHA-256 hashes, or other formats.¶
A per-entry unique reference within a session, enabling parent-child linking and tool call-result correlation.¶
The CDDL definition for the verifiable-agent-record map is specified as follows:¶
verifiable-agent-record = {
version: tstr
id: tstr
session: session-trace
? created: abstract-timestamp
? file-attribution: file-attribution-record
? vcs: vcs-context
? recording-agent: recording-agent
* tstr => any
}
¶
The verifiable-agent-record is the top-level container for all data produced by or about an agent conversation.
It unifies two complementary perspectives: the session trace captures how code was produced (the full conversation replay), while file attribution captures what code was produced (which files were modified and by whom).¶
The following describes each member of this map.¶
The schema version string following semantic versioning (e.g., "3.0.0-draft"). Consumers use this field to select the appropriate parser or validation logic.¶
A unique identifier for this record, typically a UUID. Distinguishes records when multiple are stored or transmitted together.¶
The full conversation trace including all entries, tool calls, reasoning steps, and system events.¶
The timestamp when this record was generated. Distinct from session timestamps, which record when the conversation occurred.¶
Structured data about which files were modified and which line ranges were written by the agent.¶
Version control metadata at the record level (repository, branch, revision).¶
Identifies the tool or agent that generated this record, as distinct from the agent that conducted the conversation.¶
The CDDL definition for the session-trace map is specified as follows:¶
session-trace = {
? format: tstr
session-id: session-id
? session-start: abstract-timestamp
? session-end: abstract-timestamp
agent-meta: agent-meta
? environment: environment
entries: [* entry]
* tstr => any
}
¶
A session-trace captures the full conversation between a user and an autonomous agent.
It contains an ordered array of entries representing messages, tool invocations, reasoning steps, and system events.
The session-trace preserves the complete interaction history including all native agent metadata, enabling both replay and audit of the conversation.¶
The following describes each member of this map.¶
Classifies the session style, such as "interactive" (human-in-the-loop) or "autonomous" (fully automated). Informative only; does not change the structure.¶
Unique identifier for this session.¶
When the session began.¶
When the session ended.¶
Metadata about the agent and model that conducted this conversation.¶
Execution environment context, such as working directory and version control state.¶
An ordered array of conversation entries.¶
The CDDL definition for the agent-meta map is specified as follows:¶
agent-meta = {
model-id: tstr
model-provider: tstr
? models: [* tstr]
? cli-name: tstr
? cli-version: tstr
* tstr => any
}
¶
The agent-meta type identifies the coding agent and language model used during a conversation session.
Agent identification is essential for provenance tracking: knowing which model produced which output enables auditing, capability assessment, and compliance verification.¶
The following describes each member of this map.¶
The primary language model identifier, using the naming convention of the provider (e.g., "claude-opus-4-5-20251101", "gemini-2.0-flash").¶
The provider of the primary model (e.g., "anthropic", "google", "openai").¶
List of all model identifiers used during the session. Relevant for multi-model sessions where the agent switches between models.¶
The name of the CLI tool or agent framework (e.g., "claude-code", "gemini-cli", "codex-cli").¶
The version of the CLI tool.¶
The CDDL definition for the recording-agent map is specified as follows:¶
recording-agent = {
name: tstr
? version: tstr
* tstr => any
}
¶
The recording-agent map identifies the tool that generated this verifiable agent record, as distinct from the agent that conducted the conversation.
This distinction matters for provenance chains: the recording tool's version affects how native data is translated into the canonical CDDL data definition specified in this document.¶
The following describes each member of this map.¶
The CDDL definition for the environment map is specified as follows:¶
environment = {
working-dir: tstr
? vcs: vcs-context
? sandboxes: [* tstr]
* tstr => any
}
¶
The environment type captures execution context for the conversation: where the agent was running, what version control state was active, and whether sandboxing was in effect.
This context is important for reproducibility and for understanding the scope of file modifications.¶
The following describes each member of this map.¶
The primary working directory path. File paths in tool calls are typically relative to this directory.¶
Version control state at the time of the session (branch, revision, etc.).¶
Paths to sandbox mount points. Some agents run in sandboxed environments where the working directory is a temporary mount.¶
The CDDL definition for the vcs-context map is specified as follows:¶
vcs-context = {
type: tstr
? revision: tstr
? branch: tstr
? repository: tstr
* tstr => any
}
¶
The vcs-context type captures version control metadata for reproducibility. Knowing the exact repository, branch, and commit at the time of a conversation enables consumers to reconstruct the codebase state and verify file attributions.¶
The following describes each member of this map.¶
The CDDL definition specifies five entry types representing the different kinds of events in an agent conversation.
Each type uses a type field as the discriminator.
All entry types support optional children for hierarchical nesting and * tstr => any for preserving native agent fields that do not map to canonical fields.¶
entry = message-entry
/ tool-call-entry
/ tool-result-entry
/ reasoning-entry
/ event-entry
¶
The CDDL definition for the message-entry map is specified as follows:¶
message-entry = {
type: "user" / "assistant"
? content: any
? timestamp: abstract-timestamp
? id: entry-id
? model-id: tstr
? parent-id: entry-id
? token-usage: token-usage
? children: [* entry]
* tstr => any
}
¶
A message-entry represents a conversational turn: either human input (type: "user") or agent response (type: "assistant").
This is the most common entry type, carrying the primary dialogue content of a session.
For assistant messages, additional metadata may be present: the model that generated the response and token usage statistics.¶
The following describes each member of this map.¶
The message direction. "user" indicates human (or upstream agent) input; "assistant" indicates the agent's response.¶
The message body. May be a plain text string, an array of typed content parts, or absent when the agent places content exclusively in child entries.¶
When this message was produced.¶
Unique identifier for this entry within the session.¶
The model that generated this response. Present on assistant entries; absent on user entries.¶
References the parent entry, enabling tree-structured conversations.¶
Token consumption metrics for this response.¶
Nested entries within this message. Used when the native format embeds tool calls or reasoning blocks inside an assistant message.¶
The CDDL definition for the tool-call-entry map is specified as follows:¶
tool-call-entry = {
type: "tool-call"
name: tstr
input: any
? call-id: tstr
? timestamp: abstract-timestamp
? id: entry-id
? children: [* entry]
* tstr => any
}
¶
A tool-call-entry represents a tool invocation: which tool was called and with what arguments.
Tool calls are central to agent conversation records because tool use is the primary mechanism by which agents interact with external environment.¶
The following describes each member of this map.¶
Fixed discriminator value "tool-call".¶
The tool name (e.g., "Bash", "Edit", "Read", "apply_patch").¶
The arguments passed to the tool, preserved in their native structure.¶
Links this call to its corresponding result.¶
When this tool call occurred.¶
Unique identifier for this entry.¶
Nested entries within this tool call.¶
The CDDL definition for the tool-result-entry map is specified as follows:¶
tool-result-entry = {
type: "tool-result"
output: any
? call-id: tstr
? status: tstr
? is-error: bool
? timestamp: abstract-timestamp
? id: entry-id
? children: [* entry]
* tstr => any
}
¶
A tool-result-entry represents the output returned by a tool after execution.
It is linked to its corresponding tool-call-entry via the call-id field.
The result carries the tool's response data and optional status metadata indicating success or failure.¶
The following describes each member of this map.¶
Fixed discriminator value "tool-result".¶
The tool's response, preserved in native structure.¶
Links this result to its corresponding call.¶
Outcome status of the tool execution, such as "success", "error", or "completed".¶
Boolean error flag, present when the tool execution failed.¶
When this tool result was returned.¶
Unique identifier for this entry.¶
Nested entries within this tool result.¶
The CDDL definition for the reasoning-entry map is specified as follows:¶
reasoning-entry = {
type: "reasoning"
content: any
? encrypted: tstr
? subject: tstr
? timestamp: abstract-timestamp
? id: entry-id
? children: [* entry]
* tstr => any
}
¶
A reasoning-entry captures CoT, thinking, or internal reasoning content from the agent. Not all agents expose reasoning traces; when they do, the content may be plaintext, structured blocks, or encrypted. Reasoning entries are valuable for auditing decision-making processes and understanding why an agent took particular actions.¶
The following describes each member of this map.¶
Fixed discriminator value "reasoning".¶
The reasoning text or structured content. May be an empty string when only encrypted content is available.¶
Encrypted reasoning content. Used where the model provider encrypts chain-of-thought output.¶
A topic label for the reasoning block.¶
When this reasoning was produced.¶
Unique identifier for this entry.¶
Nested entries within the reasoning block.¶
The CDDL definition for the event-entry map is specified as follows:¶
event-entry = {
type: "system-event"
event-type: tstr
? data: { * tstr => any }
? timestamp: abstract-timestamp
? id: entry-id
? children: [* entry]
* tstr => any
}
¶
An event-entry records system lifecycle events that are not part of the conversation dialogue but are relevant for understanding the session context.
Examples include session start/end markers, token usage summaries, permission changes, and configuration events.¶
The following describes each member of this map.¶
Fixed discriminator value "system-event".¶
Classifies the event, such as "session-start", "session-end", "token-count", or "permission-change". The values are not enumerated in the schema to accommodate vendor-specific event types.¶
Event-specific payload. The structure varies by event type.¶
When this event occurred.¶
Unique identifier for this entry.¶
Nested entries within this event.¶
The CDDL definition for the token-usage map is specified as follows:¶
token-usage = {
? input: uint
? output: uint
? cached: uint
? reasoning: uint
? total: uint
? cost: number
* tstr => any
}
¶
The token-usage type captures token consumption metrics for a model response.
Token usage data is essential for cost tracking, quota management, and understanding model behavior.
All fields are optional because different agents report different subsets of token metrics.¶
Editor's Note: add a non-empty generic here¶
The following describes each member of this map.¶
The number of input tokens consumed by this response.¶
The number of output tokens generated.¶
The number of input tokens served from cache rather than reprocessed.¶
Tokens consumed by chain-of-thought or reasoning computation.¶
The total token count.¶
The monetary cost in US dollars for this response.¶
NOTE: This section is specified but not yet validated against real session data. Implementation is pending.¶
File attribution captures what code was produced: which files were modified, which line ranges were changed, and who authored them.¶
The CDDL definition for the file-attribution-record map is specified as follows:¶
file-attribution-record = {
files: [* file]
}
¶
The file-attribution-record is the top-level container for file attribution data.
It holds an array of files, each with their attributed line ranges and contributor information.¶
The following describes each member of this map.¶
Array of files with attributed ranges.¶
The CDDL definition for the file map is specified as follows:¶
file = {
path: tstr
conversations: [* conversation]
}
¶
A file represents a single source file that was modified during the conversation.
It groups all conversations that contributed changes to this file.¶
The following describes each member of this map.¶
The CDDL definition for the conversation map is specified as follows:¶
conversation = {
? url: tstr .regexp uri-regexp
? contributor: contributor
ranges: [* range]
? related: [* resource]
}
¶
A conversation links a specific session to the line ranges it produced in a file.
This enables tracing from a line of code back to the conversation that generated it.¶
The following describes each member of this map.¶
A URL pointing to the conversation source (e.g., a web UI permalink).¶
The default contributor for all ranges in this conversation. Can be overridden per-range.¶
The line ranges in the file that were produced by this conversation.¶
External resources related to this conversation (e.g., issue trackers, documentation).¶
The CDDL definition for the range map is specified as follows:¶
range = {
start-line: uint
end-line: uint
? content-hash: tstr
? content-hash-alg: tstr
? contributor: contributor
}
¶
A range identifies a contiguous block of lines in a file that were produced by a specific conversation.
Line numbers are 1-indexed and inclusive.
The optional content hash enables position-independent tracking when lines move due to later edits.¶
The following describes each member of this map.¶
The first line of the range (1-indexed).¶
The last line of the range (1-indexed, inclusive).¶
A hash of the range content for position-independent identification.¶
The hash algorithm used (default: "sha-256").¶
Overrides the conversation-level contributor for this specific range.¶
The CDDL definition for the contributor map is specified as follows:¶
contributor = {
type: "human" / "ai" / "mixed" / "unknown"
? model-id: tstr
}
¶
A contributor identifies who authored a range of code.
The type field distinguishes between human-authored, AI-generated, mixed, and unknown authorship.¶
The following describes each member of this map.¶
The CDDL definition for the resource map is specified as follows:¶
resource = {
type: tstr
url: tstr .regexp uri-regexp
}
¶
A resource represents an external reference related to a conversation, such as an issue tracker entry, a pull request, or a documentation page.¶
The following describes each member of this map.¶
The signing envelope provides cryptographic integrity protection for verifiable agent records using COSE_Sign1 ([STD96]).¶
The CDDL definition for a signed-agent-record structure is specified as follows:¶
signed-agent-record = #6.18([
protected: bstr .cbor protected-header
unprotected: unprotected-header
payload: bstr / null
signature: bstr
])
¶
A signed-agent-record is a COSE_Sign1 envelope (CBOR Tag 18) that wraps a verifiable agent record with a cryptographic signature.
Signing provides data provenance and tamper evidence, satisfying some requirements of RATS Evidence generation ([RFC9334]) and SCITT auditability ([I-D.ietf-scitt-architecture]) requirements.
The payload may be included or detached (null); in detached mode, the record is supplied separately during verification.¶
The following describes each element of this structure.¶
The serialized protected header containing the algorithm identifier, content type, and CWT claims.¶
The unprotected header carrying trace metadata at label 100.¶
The serialized record bytes, or null for detached payloads.¶
The cryptographic signature over the protected header and payload.¶
The CDDL definition for the trace-metadata map is specified as follows:¶
trace-metadata = {
session-id: session-id
agent-vendor: tstr
trace-format: trace-format-id
timestamp-start: abstract-timestamp
? timestamp-end: abstract-timestamp
? content-hash: tstr
? content-hash-alg: tstr
}
¶
The trace-metadata type carries summary information about the signed record in the COSE_Sign1 unprotected header.
This enables consumers to inspect key properties of a signed record without deserializing the full payload.¶
The following describes each member of this map.¶
The session identifier from the signed record.¶
The agent provider name (e.g., "anthropic", "google").¶
Identifies the format of the signed payload (e.g., "ietf-vac-v3.0" for canonical records).¶
When the session began.¶
When the session ended.¶
SHA-256 hex digest of the payload bytes, enabling integrity checking independent of the COSE signature.¶
The hash algorithm used (default: "sha-256").¶
start = verifiable-agent-record / signed-agent-record
; RFC 3339 string OR epoch milliseconds (for interop).
abstract-timestamp = tstr .regexp date-time-regexp / uint
; Opaque string: UUID, SHA-256 hash in base64url, etc.
session-id = tstr / bstr
; Per-entry unique reference within a session.
entry-id = tstr
; RFC 3339 date-time pattern
date-time-regexp = "([0-9]{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):([0-5][0-9]):(60|[0-5][0-9])([.][0-9]+)?(Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9])"
; URI pattern (RFC 3986)
uri-regexp = "(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\\?([^#]*))?(#(.*))?"
verifiable-agent-record = {
version: tstr ; Schema version (semver)
id: tstr ; Record identifier
session: session-trace ; Conversation trace (required)
? created: abstract-timestamp ; Record creation time
? file-attribution: file-attribution-record
? vcs: vcs-context ; Record-level VCS context
? recording-agent: recording-agent ; Tool that generated this record
* tstr => any
}
session-trace = {
? format: tstr ; "interactive" / "autonomous" / vendor
session-id: session-id
? session-start: abstract-timestamp
? session-end: abstract-timestamp
agent-meta: agent-meta
? environment: environment
entries: [* entry]
* tstr => any
}
agent-meta = {
model-id: tstr ; e.g., "claude-opus-4-5-20251101"
model-provider: tstr ; e.g., "anthropic", "google"
? models: [ * tstr ] ; All models (multi-model sessions)
? cli-name: tstr ; e.g., "claude-code", "gemini-cli"
? cli-version: tstr
* tstr => any
}
recording-agent = {
name: tstr
? version: tstr
* tstr => any
}
environment = {
working-dir: tstr
? vcs: vcs-context
? sandboxes: [ * tstr ] ; Sandbox mount paths
* tstr => any
}
vcs-context = {
type: tstr ; "git" / "jj" / "hg" / "svn"
? revision: tstr ; Commit SHA or change ID
? branch: tstr
? repository: tstr ; Repository URL
* tstr => any
}
entry = message-entry
/ tool-call-entry
/ tool-result-entry
/ reasoning-entry
/ event-entry
message-entry = {
type: "user" / "assistant"
? content: any ; Text string or structured content blocks
? timestamp: abstract-timestamp
? id: entry-id
? model-id: tstr ; Model (assistant only)
? parent-id: entry-id ; Parent message reference
? token-usage: token-usage
? children: [ * entry ]
* tstr => any
}
tool-call-entry = {
type: "tool-call"
name: tstr ; Tool name (e.g., "Bash", "Edit", "Read")
input: any ; Tool arguments
? call-id: tstr ; Links call ↔ result
? timestamp: abstract-timestamp
? id: entry-id
? children: [ * entry ]
* tstr => any
}
tool-result-entry = {
type: "tool-result"
output: any ; Tool output
? call-id: tstr ; Links call ↔ result
? status: tstr ; "success" / "error" / "completed"
? is-error: bool
? timestamp: abstract-timestamp
? id: entry-id
? children: [ * entry ]
* tstr => any
}
reasoning-entry = {
type: "reasoning"
content: any ; Plaintext reasoning or structured
? encrypted: tstr ; Encrypted content (provider-protected)
? subject: tstr ; Topic label
? timestamp: abstract-timestamp
? id: entry-id
? children: [ * entry ]
* tstr => any
}
event-entry = {
type: "system-event"
event-type: tstr ; Event classifier
? data: { * tstr => any } ; Event-specific payload
? timestamp: abstract-timestamp
? id: entry-id
? children: [ * entry ]
* tstr => any
}
token-usage = {
? input: uint ; Input tokens
? output: uint ; Output tokens
? cached: uint ; Cached input tokens
? reasoning: uint ; Reasoning/thinking tokens
? total: uint ; Total tokens
? cost: number ; Dollar cost
* tstr => any
}
file-attribution-record = {
files: [* file]
}
file = {
path: tstr ; Relative path from repo root
conversations: [* conversation]
}
conversation = {
? url: tstr .regexp uri-regexp
? contributor: contributor ; Default contributor for ranges
ranges: [* range]
? related: [* resource]
}
range = {
start-line: uint ; 1-indexed
end-line: uint ; 1-indexed, inclusive
? content-hash: tstr
? content-hash-alg: tstr ; Default: "sha-256"
? contributor: contributor ; Override for this range
}
contributor = {
type: "human" / "ai" / "mixed" / "unknown"
? model-id: tstr
}
resource = {
type: tstr
url: tstr .regexp uri-regexp
}
; SCITT-interoperable COSE Envelope
; including from draft-ietf-cose-merkle-tree-proofs and
; draft-ietf-scitt-architecture for validation
signed-agent-record = #6.18([ ; COSE_Sign1 tag
protected: bstr .cbor protected-header ; {alg, content-type, scitt-stuff}
unprotected: unprotected-header ; Trace metadata
payload: bstr / null ; Detached if null
signature: bstr
])
protected-header = {
&(CWT_Claims: 15) => CWT_Claims
? &(alg: 1) => int
? &(content_type: 3) => tstr / uint
? &(kid: 4) => bstr
? &(x5t: 34) => COSE_CertHash
? &(x5chain: 33) => COSE_X509
* label => any
}
CWT_Claims = {
&(iss: 1) => tstr
&(sub: 2) => tstr
* label => any
}
unprotected-header = {
? &(trace-metadata-key: 100) => trace-metadata ; 100 is placeholder
? &(x5chain: 33) => COSE_X509
? &(receipts: 394) => [ + Receipt ]
* label => any
}
trace-metadata = {
session-id: session-id
agent-vendor: tstr
trace-format: trace-format-id
timestamp-start: abstract-timestamp
? timestamp-end: abstract-timestamp
? content-hash: tstr ; SHA-256 hex digest of payload
? content-hash-alg: tstr
}
; Known values: "ietf-vac-v3.0" (canonical), "claude-jsonl", "gemini-json",
; "codex-jsonl", "opencode-json", "cursor-jsonl". Extensible via tstr.
trace-format-id = tstr
COSE_X509 = bstr / [ 2*certs: bstr ]
COSE_CertHash = [ hashAlg: (int / tstr), hashValue: bstr ]
label = int / tstr
; COSE Receipt CDDL for use in SCITT compliant COSE Envelope
Receipt = #6.18(COSE_Sign1)
cose-label = int / tstr
cose-value = any
Protected_Header = {
* cose-label => cose-value
}
Unprotected_Header = {
&(receipts: 394) => [+ bstr .cbor Receipt]
* cose-label => cose-value
}
COSE_Sign1 = [
protected : bstr .cbor Protected_Header,
unprotected : Unprotected_Header,
payload : bstr / null,
signature : bstr
]
Verifiable agent conversation records reveal substantial information about agent behavior, system state, and user interactions. The privacy considerations of [RFC6973] apply.¶
User prompts captured in message entries may contain personal identifiers, business confidential information, credentials inadvertently included in prompts, or behavioral patterns. Agent responses and reasoning traces may reveal inference results that expose information about users not explicitly provided, confidential information retrieved by tools, or system architecture details through tool names and parameters. Implementations MUST treat user-provided content as potentially containing personally identifiable information.¶
Record metadata exposes operational details that may have privacy implications. Model identifiers reveal AI capabilities, CLI versions enable targeted attacks against known vulnerabilities, working directories expose file system structure, and VCS context discloses repository names and commit timing. Token usage patterns may enable inference about conversation content even when the content itself is protected.¶
Reasoning entries may contain inferences that constitute special category data, including health-related inferences from user queries, political opinions derived from conversation context, or biometric data processed by AI systems.
The reasoning-entry.encrypted field reflects that some model providers encrypt chain-of-thought content; when reasoning is encrypted, audit capabilities depend on the provider's cooperation.¶
Tool inputs and outputs warrant particular attention. Tool call inputs may contain credentials, API keys, or file contents. Tool results may contain query results with personal data from databases or external services. Implementations SHOULD provide configurable redaction rules for common patterns and support selective entry type recording based on deployment requirements.¶
Multiple frameworks impose retention requirements that may conflict with data minimization principles. Organizations must balance compliance obligations requiring extended retention against privacy principles requiring timely deletion.¶
Compliant data management may require separating raw personal data from audit trail metadata, implementing automated deletion for personal data after compliance-minimum periods, and maintaining cryptographic commitments enabling verification without retaining content.¶
Presentations of the same record to multiple parties can be correlated by matching on the signature component. Session identifiers enable linking of records across time, potentially revealing long-term behavioral patterns or organizational structure. Implementations SHOULD use unlinkable session identifiers where correlation is not required.¶
Without accessing record content, observers may infer conversation frequency and duration patterns, types of tools used, error rates, or timing correlations with external events.
Metadata exposure in unprotected headers warrants careful consideration; the trace-metadata in the COSE unprotected header reveals session identifiers, agent vendor, and timestamps even when the payload is encrypted.¶
The signed-agent-record envelope provides cryptographic integrity protection for the serialized record payload.
A valid signature establishes that the claimed signer produced the record but does not guarantee the truthfulness of its contents.
Modifications to the record structure after signing invalidate the signature, but modifications before signing cannot be detected.
Implementations generating records incrementally during a conversation MUST sign only after the conversation concludes or at defined checkpoints.¶
The security of signed records depends critically on the protection of private signing keys. If an attacker obtains a signing key, they can forge records indistinguishable from genuine ones. Protection mechanisms range from operating system process isolation in development environments to hardware security modules with physical tampering resistance in high-assurance deployments. Compromised signing keys require rejection of records signed after the compromise date and notification to Relying Parties.¶
Key provisioning processes must guarantee that exclusively valid attestation key material is established. Off-device key generation requires confidentiality protection during transmission, creating recursive security dependencies. On-device key generation eliminates transmission risks but requires chain-of-custody integrity to prevent attackers from obtaining endorsement for keys they control.¶
Timestamps establish temporal ordering of events within records. Attackers who can manipulate timestamps can backdate records, freeze participants in chosen time periods to evade freshness checks, or manipulate perceived temporal relationships between entries. Timestamps within records are attested by the signer, not independently verified. Implementations requiring independent timestamp verification SHOULD use external timestamping services or transparency logs such as those defined in [I-D.ietf-scitt-architecture].¶
Processing verifiable agent conversation records involves parsing content that may be produced by adversaries.
This applies both to user-supplied prompts and to model outputs that may have been influenced by adversarial inputs.
The open extensibility (* tstr => any) in record types allows arbitrary additional fields; implementations MUST NOT assume that unrecognized fields are safe to process or display.¶
Records may contain content designed to exploit downstream systems. Malicious prompts preserved in records may execute if records are subsequently processed by AI systems. Tool results may contain executable content that executes if rendered unsafely in web interfaces. File paths in tool calls or file attribution entries may attempt directory traversal. Implementations MUST apply appropriate sanitization before rendering content, executing it in agent contexts, or using paths for file system operations.¶
The signed-agent-record envelope alone provides authenticity and integrity, not non-repudiation.
A signer can claim key compromise or dispute the signing time without independent evidence.
Non-repudiation requires additional infrastructure such as transparency services [I-D.ietf-scitt-architecture] that provide independent timestamp proof via registration receipts, append-only logs preventing retroactive denial, and third-party witnesses to the signing event.¶
Verifiable agent conversation records primarily enable detection of anomalous behavior rather than prevention.
Detection requires that records accurately reflect actual agent behavior; an agent that controls its own recording can omit or falsify entries.
The recording-agent field distinguishes the recording tool from the conversing agent, enabling Relying Parties to assess trust in the recording process.¶
Trust boundaries exist between the agent runtime and recording system, between the recording system and storage, between storage and verification, and between verification and decision-making. Attacks at any boundary may compromise record integrity or confidentiality.¶
IANA is requested to add "application/agent-conversation" as a new media type for Verifiable Agent Conversation Records to the "Media Types" registry [IANA.media-types] in the Standards Tree [RFC6838]:¶
| Name | Template | Reference |
|---|---|---|
agent-conversation
|
application/agent-conversation
|
RFCthis |
application¶
agent-conversation¶
N/A¶
N/A¶
byte string¶
See Security Considerations {secconsec}¶
N/A¶
RFCthis¶
Applications that need to describe AI agent conversation for verification and auditability.¶
N/A¶
TBD¶
COMMON¶
none¶
See Author's Addresses section¶
IETF¶
no¶
IANA is requested to assign a Content-Format ID for Verifiable Agent Conversation Records in the "CoAP Content-Formats" registry, within the "Constrained RESTful Environments (CoRE) Parameters" registry group [IANA.core-parameters]:¶
| Content-Type | Content Coding | ID | Reference |
|---|---|---|---|
| application/agent-conversation | - | TBD1 | RFCthis |
If possible, TBD1 should be assigned in the 256...9999 range.¶
IANA is requested to allocate a tag for Verifiable Agent Conversation Records in the "CBOR Tags" registry [IANA.cbor-tags], preferably with the specific value requested:¶
| Tag | Data Item | Semantics |
|---|---|---|
| 4149 | binary | Verifiable Agent Conversation Records as defined in RFCthis |
IANA is requested to allocated the COSE header parameter defined in Table 19 in the "COSE Header Parameters" registry [IANA.cose_header-parameters].¶
| Name | Label | Value Type | Value Registry | Description | Reference |
|---|---|---|---|---|---|
trace-metadata
|
TBD | CBOR map | - | A metadata summary of an Agent Conversation Record | RFCthis, Section 3.11.2 |
The authors would like to thank: xor-hardener¶