{"slug": "agent-trace-a-standard-format-for-tracing-ai-generated-code", "title": "Agent-trace: A standard format for tracing AI-generated code", "summary": "Agent Trace, an open specification for tracing AI-generated code, was released as an RFC in January 2026. It provides a vendor-neutral format to record AI contributions alongside human authorship in version-controlled codebases, aiming to improve attribution and interoperability.", "body_md": "**Version**: 0.1.0\n\n**Status**: RFC\n\n**Date**: January 2026\n\nAgent Trace is an open specification for tracing AI-generated code. It provides a vendor-neutral format for recording AI contributions alongside human authorship in version-controlled codebases.\n\n[Motivation](#1-motivation)[Goals](#2-goals)[Non-Goals](#3-non-goals)[Terminology](#4-terminology)[Architecture Overview](#5-architecture-overview)[Core Specification](#6-core-specification)[Extensibility](#7-extensibility)[Reference Implementation](#8-reference-implementation)[Appendix](#appendix)\n\nAs agents write more code, it's important to understand what came from AI versus humans. This attribution is both the models used as well as the related agent conversations. Agent Trace defines an open, interoperable standard for recording this attribution data.\n\n**Interoperability**: Any compliant tool can read and write attribution data.** Granularity**: Support attribution for models used at file and line granularity.** Extensibility**: Vendors can add custom metadata without breaking compatibility.** Human & Agent Readable**: Attribution data is readable without special tooling.\n\n**Code Ownership**: Agent Trace does not track legal ownership or copyright.** Training Data Provenance**: We don't track what training data influenced AI outputs.** Quality Assessment**: We don't evaluate whether AI contributions are good or bad.** UI Agnostic**: Agent Trace does not require any specific interface.\n\n| Term | Definition |\n|---|---|\nContribution |\nA unit of code change (addition, modification, or deletion) |\nContributor |\nThe entity that produced a contribution (human or AI) |\nTrace Record |\nMetadata describing a contribution's origin |\n\n| Type | Code | Description |\n|---|---|---|\n| Human | `human` |\nCode authored directly by a human developer |\n| AI | `ai` |\nCode generated by AI |\n| Mixed | `mixed` |\nHuman-edited AI output or AI-edited human code |\n| Unknown | `unknown` |\nOrigin cannot be determined |\n\nAgent Trace is a data specification, not a product. It defines how to record attribution data. Storage mechanisms are implementation-defined. The spec is unopinionated about where traces live.\n\nThe fundamental unit of Agent Trace is the **Trace Record**:\n\n```\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://agent-trace.dev/schemas/v1/trace-record.json\",\n  \"title\": \"Agent Trace Record\",\n  \"type\": \"object\",\n  \"required\": [\"version\", \"id\", \"timestamp\", \"files\"],\n  \"properties\": {\n    \"version\": {\n      \"type\": \"string\",\n      \"pattern\": \"^[0-9]+\\\\.[0-9]+\\\\.[0-9]+$\",\n      \"description\": \"Agent Trace specification version (e.g., '1.0.0')\"\n    },\n    \"id\": {\n      \"type\": \"string\",\n      \"format\": \"uuid\",\n      \"description\": \"Unique identifier for this trace record\"\n    },\n    \"timestamp\": {\n      \"type\": \"string\",\n      \"format\": \"date-time\",\n      \"description\": \"RFC 3339 timestamp when trace was recorded\"\n    },\n    \"vcs\": {\n      \"$ref\": \"#/$defs/vcs\",\n      \"description\": \"Version control system information for this trace\"\n    },\n    \"tool\": {\n      \"$ref\": \"#/$defs/tool\",\n      \"description\": \"The tool that generated this trace\"\n    },\n    \"files\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"$ref\": \"#/$defs/file\"\n      },\n      \"description\": \"Array of files with attributed ranges\"\n    },\n    \"metadata\": {\n      \"type\": \"object\",\n      \"description\": \"Additional metadata for implementation-specific or vendor-specific data\"\n    }\n  },\n  \"$defs\": {\n    \"vcs\": {\n      \"type\": \"object\",\n      \"required\": [\"type\", \"revision\"],\n      \"properties\": {\n        \"type\": {\n          \"type\": \"string\",\n          \"enum\": [\"git\", \"jj\", \"hg\", \"svn\"],\n          \"description\": \"Version control system type\"\n        },\n        \"revision\": {\n          \"type\": \"string\",\n          \"description\": \"Revision identifier (e.g., git commit SHA, jj change ID)\"\n        }\n      }\n    },\n    \"tool\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"name\": { \"type\": \"string\" },\n        \"version\": { \"type\": \"string\" }\n      }\n    },\n    \"file\": {\n      \"type\": \"object\",\n      \"required\": [\"path\", \"conversations\"],\n      \"properties\": {\n        \"path\": {\n          \"type\": \"string\",\n          \"description\": \"Relative file path from repository root\"\n        },\n        \"conversations\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"$ref\": \"#/$defs/conversation\"\n          },\n          \"description\": \"Array of conversations that contributed to this file\"\n        }\n      }\n    },\n    \"contributor\": {\n      \"type\": \"object\",\n      \"required\": [\"type\"],\n      \"properties\": {\n        \"type\": {\n          \"type\": \"string\",\n          \"enum\": [\"human\", \"ai\", \"mixed\", \"unknown\"]\n        },\n        \"model_id\": {\n          \"type\": \"string\",\n          \"maxLength\": 250,\n          \"description\": \"The model's unique identifier following models.dev convention (e.g., 'anthropic/claude-opus-4-5-20251101')\"\n        }\n      }\n    },\n    \"conversation\": {\n      \"type\": \"object\",\n      \"required\": [\"ranges\"],\n      \"properties\": {\n        \"url\": {\n          \"type\": \"string\",\n          \"format\": \"uri\",\n          \"description\": \"URL to look up the conversation that produced this code\"\n        },\n        \"contributor\": {\n          \"$ref\": \"#/$defs/contributor\",\n          \"description\": \"The contributor for ranges in this conversation (can be overridden per-range)\"\n        },\n        \"ranges\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"$ref\": \"#/$defs/range\"\n          },\n          \"description\": \"Array of line ranges produced by this conversation\"\n        },\n        \"related\": {\n          \"type\": \"array\",\n          \"items\": {\n            \"type\": \"object\",\n            \"required\": [\"type\", \"url\"],\n            \"properties\": {\n              \"type\": { \"type\": \"string\" },\n              \"url\": { \"type\": \"string\", \"format\": \"uri\" }\n            }\n          },\n          \"description\": \"Other related resources\"\n        }\n      }\n    },\n    \"range\": {\n      \"type\": \"object\",\n      \"required\": [\"start_line\", \"end_line\"],\n      \"properties\": {\n        \"start_line\": { \"type\": \"integer\", \"minimum\": 1 },\n        \"end_line\": { \"type\": \"integer\", \"minimum\": 1 },\n        \"content_hash\": {\n          \"type\": \"string\",\n          \"description\": \"Hash of attributed content for position-independent tracking\"\n        },\n        \"contributor\": {\n          \"$ref\": \"#/$defs/contributor\",\n          \"description\": \"Override contributor for this specific range (e.g., for agent handoffs)\"\n        }\n      }\n    }\n  }\n}\n{\n  \"version\": \"0.1.0\",\n  \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"timestamp\": \"2026-01-23T14:30:00Z\",\n  \"vcs\": {\n    \"type\": \"git\",\n    \"revision\": \"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0\"\n  },\n  \"tool\": {\n    \"name\": \"cursor\",\n    \"version\": \"2.4.0\"\n  },\n  \"files\": [\n    {\n      \"path\": \"src/utils/parser.ts\",\n      \"conversations\": [\n        {\n          \"url\": \"https://api.cursor.com/v1/conversations/12345\",\n          \"contributor\": {\n            \"type\": \"ai\",\n            \"model_id\": \"anthropic/claude-opus-4-5-20251101\"\n          },\n          \"ranges\": [\n            {\n              \"start_line\": 42,\n              \"end_line\": 67,\n              \"content_hash\": \"murmur3:9f2e8a1b\"\n            }\n          ],\n          \"related\": [\n            {\n              \"type\": \"session\",\n              \"url\": \"https://api.cursor.com/v1/sessions/67890\"\n            }\n          ]\n        }\n      ]\n    },\n    {\n      \"path\": \"src/utils/helpers.ts\",\n      \"conversations\": [\n        {\n          \"url\": \"https://api.cursor.com/v1/conversations/12345\",\n          \"contributor\": {\n            \"type\": \"ai\",\n            \"model_id\": \"openai/gpt-4o\"\n          },\n          \"ranges\": [\n            {\n              \"start_line\": 10,\n              \"end_line\": 25\n            }\n          ]\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"confidence\": 0.95,\n    \"dev.cursor\": {\n      \"workspace_id\": \"ws-abc123\"\n    }\n  }\n}\n```\n\nRanges are grouped by conversation, with contributor metadata at the conversation level. This reduces cardinality when one conversation produces many ranges.\n\n**Line-level attribution**:\n\n```\n{\n  \"files\": [\n    {\n      \"path\": \"src/utils.ts\",\n      \"conversations\": [\n        {\n          \"url\": \"https://api.example.com/v1/conversations/abc\",\n          \"contributor\": {\n            \"type\": \"ai\",\n            \"model_id\": \"anthropic/claude-sonnet-4-20250514\"\n          },\n          \"ranges\": [\n            { \"start_line\": 10, \"end_line\": 25 },\n            { \"start_line\": 30, \"end_line\": 45 },\n            { \"start_line\": 80, \"end_line\": 95 }\n          ]\n        },\n        {\n          \"url\": \"https://api.example.com/v1/conversations/def\",\n          \"contributor\": { \"type\": \"ai\", \"model_id\": \"openai/gpt-4o\" },\n          \"ranges\": [{ \"start_line\": 50, \"end_line\": 52 }]\n        }\n      ]\n    }\n  ]\n}\n```\n\nLine numbers are 1-indexed. Ranges reference positions at the recorded revision.\n\nAgent Trace supports multiple version control systems through the `vcs`\n\nfield:\n\n```\n// Git\n{ \"vcs\": { \"type\": \"git\", \"revision\": \"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0\" } }\n\n// Jujutsu (using change ID for stability across rebases)\n{ \"vcs\": { \"type\": \"jj\", \"revision\": \"kkmpptxz\" } }\n\n// Mercurial\n{ \"vcs\": { \"type\": \"hg\", \"revision\": \"a1b2c3d4e5f6\" } }\n```\n\nThe `revision`\n\nfield format is VCS-specific:\n\n**git**: 40-character hex commit SHA** jj**: Change ID (stable across amend/rebase operations)** hg**: Changeset identifier\n\nLine numbers in a trace refer to positions at the recorded revision, not current positions. To query ownership of a specific line of code:\n\n- Use VCS blame to find the revision that last touched line N\n- Look up the trace for that revision and file\n- Find the range containing line N\n\nFor tracking attribution across code movement, use content hashes at the range level:\n\n```\n{\n  \"files\": [\n    {\n      \"path\": \"src/parser.ts\",\n      \"conversations\": [\n        {\n          \"url\": \"https://api.example.com/v1/conversations/abc\",\n          \"contributor\": {\n            \"type\": \"ai\",\n            \"model_id\": \"anthropic/claude-opus-4-5-20251101\"\n          },\n          \"ranges\": [\n            {\n              \"start_line\": 10,\n              \"end_line\": 25,\n              \"content_hash\": \"murmur3:9f2e8a1b\"\n            }\n          ]\n        }\n      ]\n    }\n  ]\n}\n```\n\nThe hash applies to the specific range, allowing tracking even when code moves within or between files.\n\nModel identifiers follow the [models.dev](https://models.dev) convention:\n\n```\n{\n  \"contributor\": {\n    \"type\": \"ai\",\n    \"model_id\": \"anthropic/claude-opus-4-5-20251101\"\n  }\n}\n```\n\nFormat: `provider/model-name`\n\nEach conversation has a `url`\n\nfield and optional `related`\n\narray for linking to related sub-resources:\n\n```\n{\n  \"files\": [\n    {\n      \"path\": \"src/api.ts\",\n      \"conversations\": [\n        {\n          \"url\": \"https://api.example.com/v1/conversations/abc123\",\n          \"contributor\": {\n            \"type\": \"ai\",\n            \"model_id\": \"anthropic/claude-opus-4-5-20251101\"\n          },\n          \"ranges\": [{ \"start_line\": 10, \"end_line\": 50 }],\n          \"related\": [\n            {\n              \"type\": \"session\",\n              \"url\": \"https://api.example.com/v1/sessions/xyz789\"\n            },\n            {\n              \"type\": \"prompt\",\n              \"url\": \"https://api.example.com/v1/prompts/def456\"\n            }\n          ]\n        }\n      ]\n    }\n  ]\n}\n```\n\n- Major version: breaking changes to required fields\n- Minor version: additive changes (new optional fields)\n\nThe `metadata`\n\nfield can include implementation or vendor-specific data:\n\n```\n{\n  \"metadata\": {\n    \"confidence\": 0.95,\n    \"post_processing_tools\": [\"prettier@3.0.0\"],\n    \"dev.cursor\": {\n      \"workspace_id\": \"ws-abc123\"\n    }\n  }\n}\n```\n\nVendors may use reverse-domain notation (e.g., `dev.cursor`\n\n, `com.github.copilot`\n\n) within `metadata`\n\nto avoid key collisions.\n\nA [reference implementation](https://github.com/cursor/agent-trace/tree/main/reference) is provided in the `reference/`\n\ndirectory, demonstrating how to integrate Agent Trace with coding agents. The implementation includes:\n\n: A storage layer for reading and writing trace records`trace-store.ts`\n\n: Hook integration for automatic trace capture on file changes`trace-hook.ts`\n\nThe reference is an example for Cursor or Claude Code, but the patterns are applicable to any AI coding agent.\n\n```\n{\n  \"version\": \"0.1.0\",\n  \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"timestamp\": \"2026-01-25T10:00:00Z\",\n  \"files\": [\n    {\n      \"path\": \"src/app.ts\",\n      \"conversations\": [\n        {\n          \"contributor\": { \"type\": \"ai\" },\n          \"ranges\": [{ \"start_line\": 1, \"end_line\": 50 }]\n        }\n      ]\n    }\n  ]\n}\n```\n\n| Type | MIME Type |\n|---|---|\n| Trace Record | `application/vnd.agent-trace.record+json` |\n\n**How should I store the traces?**\n\nThis spec intentionally does not define how traces are stored. This could be local files, git notes, a database, or anything else.\n\n**How should I handle rebases or merge commits?**\n\nWe expect to see different implementations in open source. This may influence the spec in the future. We are open to feedback.\n\n**What happens when agents create scripts to write code?**\n\nThis is left to the implementation. Code generated this way should still be attributed to the agent. For example, you could snapshot files before and after the script runs, then use git diff to determine what the agent added.\n\nThis specification is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).\n\nThanks to the following partners for helping shape Agent Trace:\n\nThis specification is accepting suggestions on [GitHub](https://github.com/cursor/agent-trace).", "url": "https://wpnews.pro/news/agent-trace-a-standard-format-for-tracing-ai-generated-code", "canonical_source": "https://github.com/cursor/agent-trace", "published_at": "2026-06-21 07:48:17+00:00", "updated_at": "2026-06-21 08:07:52.248137+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-ethics"], "entities": ["Agent Trace"], "alternates": {"html": "https://wpnews.pro/news/agent-trace-a-standard-format-for-tracing-ai-generated-code", "markdown": "https://wpnews.pro/news/agent-trace-a-standard-format-for-tracing-ai-generated-code.md", "text": "https://wpnews.pro/news/agent-trace-a-standard-format-for-tracing-ai-generated-code.txt", "jsonld": "https://wpnews.pro/news/agent-trace-a-standard-format-for-tracing-ai-generated-code.jsonld"}}