The 'prompt' URI Scheme for AI Agent Sessions and Prompts

Introduction AI agent systems produce interactions — prompts from users, tool calls by agents, responses, and observations — that generate artifacts (files, analyses, transformed documents) whose provenance is difficult to trace after the fact. Existing identifier schemes are insufficient for this use case:

A session identifier alone does not distinguish which prompt within a session produced a given artifact.
A wall-clock timestamp alone does not identify the agent or session.
An agent-internal correlation identifier (such as a promptId or interactionId) is not exposed to callers of agent tools at call time.

The prompt URI scheme addresses this gap by providing a stable, human-readable identifier that encodes the three pieces of information consistently available to any tool executing within an agent session: the agent identity, the session identifier, and the approximate call time. The resulting URI is suitable for embedding in file provenance metadata, log cross-references, and audit records. It is NOT a globally unique identifier in the strict sense; see and for a full treatment of ambiguity. The scheme has been implemented and deployed as an open-source Model Context Protocol (MCP) server that resolves, generates, and searches prompt URIs against local agent session logs. This implementation validates the design under real-world agent workloads involving both Claude Code and GitHub Copilot sessions. Several proposals currently under active consideration in IETF AI-focused forums address broader questions of AI agent accountability, transparency, auditability, and interoperability. The prompt URI scheme is intended as a composable, low-level building block for those frameworks: any mechanism that tracks, attests to, or makes claims about AI-generated artifacts needs a stable, lightweight way to reference the specific agent interaction that produced them. This document defines that reference.

Terminology 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 when, and only when, they appear in all capitals, as shown here. The following terms are used throughout this document:

Agent:: A software system that processes user prompts, invokes tools, and produces responses. Examples include Claude Code, GitHub Copilot, and similar AI-assisted development tools.
Session:: A bounded interaction context shared between a user and an agent, identified by a session identifier assigned at session initiation.
Prompt:: A single user message that initiates one or more agent actions within a session.
Session log:: A persistent record maintained by the agent of all interactions within a session, including prompts, tool calls, and responses, together with timestamps and internal correlation identifiers.
Tool call:: An invocation of an external capability (such as a file write operation) by the agent in response to a prompt. The Model Context Protocol is one standardized mechanism by which agents invoke such capabilities.
Provenance record:: Metadata attached to an artifact describing its origin, including the agent, session, and prompt responsible for its creation.
Prompt URI:: A URI conforming to this specification that identifies a prompt within a specific agent session.
Session alias:: A human-readable string registered by the user or agent as an alternative identifier for a session, usable in place of the session identifier in a prompt URI. An alias is scoped to a single agent and MUST be unique within that agent's alias registry.
Alias registry:: A local store, maintained by an implementation, that maps registered session aliases to their corresponding session identifiers.

URI Syntax

Scheme Name The scheme name is prompt. It SHALL be written in lowercase in all generated URIs. Implementations processing incoming URIs SHOULD treat the scheme name as case-insensitive per Section 6.2.2.1.

Authority Component The authority component of a prompt URI identifies the agent that generated the URI. It consists solely of the agent name; no userinfo or port subcomponents are defined. The authority MUST be present and MUST NOT be empty.

Path Component The path component SHALL consist of exactly two segments separated by a slash:

A session reference — either a session identifier () or a registered session alias ().
The prompt reference — either a timestamp or a prompt identifier ().

The path MUST begin with a slash. Both segments MUST NOT be empty.

Query and Fragment Components This specification does not define semantics for query (?) or fragment (#) components. Implementations MAY append a fragment to a prompt URI as an implementation-specific disambiguation hint (see ), but SHALL NOT rely on fragment processing in interoperable contexts. The query component SHOULD NOT be used; its presence does not affect identity or comparison.

Complete ABNF The following grammar, expressed in Augmented Backus-Naur Form , defines the syntax of a prompt URI. Terms not defined here are imported from (unreserved, pct-encoded) and (date-time). ; Colons within date-time are valid in URI path ; segments per RFC 3986 Section 3.3 ; Example: 2026-07-07T16:45:23.856Z prompt-id = "~" 1*( unreserved / pct-encoded ) ; Agent-internal prompt correlation identifier; ; "~" (U+007E, unreserved per RFC 3986) distinguishes ; prompt-id from date-time in all syntactic contexts ; Example: ~abc123, ~promptId%3Axyz ]]> The following prompt URIs are all syntactically valid. The first uses a session identifier with a timestamp; the second uses a session alias with a timestamp; the third uses a session identifier with a prompt identifier (the canonical preferred form; see ): Breaking the alias-based example into components: Breaking the canonical prompt-id example into components:

URI Components and Semantics

Agent Name The agent name identifies the software agent that generated the URI. It is NOT a globally registered identifier; implementations SHOULD use a stable, recognizable short name (e.g., claude-code, github-copilot, cursor). Agents operated by different organizations SHOULD use distinct names to avoid collision. The agent name MAY include a dot-separated hierarchy for namespacing (e.g., anthropic.claude-code), but this structure carries no defined semantics in this specification. The agent name SHALL remain constant across all sessions and versions of a given agent implementation. Including a version number in the agent name is NOT RECOMMENDED, as it would render URIs from different versions incomparable even when they refer to the same logical agent.

Session Identifier The session identifier SHALL be an opaque string assigned by the agent at session initiation. Implementations SHOULD use a UUID for the session identifier to minimize collision probability across agents and deployments. UUID version 7 is RECOMMENDED over version 4 because its monotonically increasing structure supports chronological ordering of sessions. The session identifier SHALL be consistent throughout a session and SHALL NOT change during a session's lifetime.

Timestamp The timestamp SHALL be formatted as an RFC 3339 date-time value and SHALL use UTC (the Z suffix). The timestamp records the wall-clock time at which the tool call generating the URI was executed. Implementations SHOULD include sub-second precision (milliseconds) in the timestamp to reduce the probability of within-session collisions (see ). A timestamp with second-level precision is REQUIRED; millisecond precision is RECOMMENDED; microsecond precision MAY be used. The timestamp is NOT the time at which the originating prompt was submitted. It is the time at which the tool call was executed. For a given prompt, multiple tool calls MAY be executed, potentially spanning multiple seconds. Each tool call produces a URI with its own timestamp; all such URIs are considered to refer to the same prompt for resolution purposes (see ). When the agent maintains an internal prompt correlation identifier, the canonical form of the URI SHOULD use that identifier in place of the timestamp (see ).

Session Aliases A session alias is a human-readable string that a user or implementation MAY register as an alternative to the session identifier in a prompt URI. Aliases improve legibility: prompt://claude-code/md-csv-mcp-design/... is more immediately meaningful than prompt://claude-code/5674b542-.../.... Registration: Aliases SHALL be registered in a local alias registry that maps each alias to the session identifier it represents. An alias is scoped to a single agent name and MUST map to exactly one session within that agent's registry. A session MAY have more than one alias registered to it. Attempting to register an alias that is already registered to a different session SHALL be rejected with a conflict error. Attempting to register an alias that is already registered to the same session is idempotent and SHALL succeed without modifying the registry. Case insensitivity: Alias lookup SHALL be case-insensitive. The alias MD-CSV-MCP-Design, md-csv-mcp-design, and Md-Csv-Mcp-Design MUST all resolve to the same session. Implementations SHOULD store aliases in normalized lowercase and normalize incoming aliases to lowercase before lookup. Canonical URI form: In a prompt URI, an alias SHALL appear in its canonical URI form, which is the percent-encoded representation of the alias string with all characters encoded per as required. Handling of spaces and special characters: Spaces (U+0020) and any other characters not permitted in a URI path segment by MUST be percent-encoded in the canonical URI form of an alias. The alias md-csv-mcp design is canonically encoded as md-csv-mcp%20design in a prompt URI. Hyphens and spaces remain distinct: the alias md-csv-mcp design and the alias md-csv-mcp-design are different aliases and resolve to different sessions (if both are registered). Implementations that accept prompt URIs as input MAY repair aliases containing unencoded special characters by applying percent-encoding before lookup, in the same manner that web browsers correct malformed URIs. Implementations MUST preserve the original human-readable alias string (as supplied at registration time, before percent-encoding) in the alias registry. This allows the original label to be displayed in user interfaces without loss of information. Alias persistence: Alias registries are implementation-defined and may not persist indefinitely. Agents are not required to maintain alias registries across restarts, updates, or deployments. Users and systems requiring long-term, portable provenance references SHOULD use the session-identifier form of the prompt URI rather than the alias form, since session identifiers are generated by the agent and stored in its session log independently of any alias registry. Prompt URIs using an alias remain valid provenance references as long as the alias registry is intact, but are subject to becoming unresolvable () if the registry is lost or unavailable. Alias-to-session-id URIs: When a session has both a registered alias and a session identifier, both forms of prompt URI are valid and refer to the same session. Implementations MAY use the alias form in newly generated provenance records when an alias is registered, as it improves human readability.

Canonical Prompt URI A prompt URI is canonical if its prompt-ref component is the most specific and stable identifier available for the prompt it represents. The canonical form determines which URI SHOULD be stored in provenance records. Prompt identifier form (preferred): When the agent maintains an internal correlation identifier for each prompt (for example, promptId in Claude Code session logs or interactionId in Copilot session logs ), the canonical URI SHOULD use the prompt-id form () with a leading ~ character: A canonical prompt-id URI uniquely identifies the prompt regardless of when tool calls execute within the prompt's processing. Because all tool calls from the same prompt share the same prompt identifier, two prompt-id URIs with the same session-ref and prompt-id components can be detected as equivalent by string comparison, without consulting the session log. Timestamp form (fallback): When no prompt identifier is available, the canonical URI SHOULD use the timestamp at which the originating prompt was submitted by the user — not the timestamp of any particular tool call within the prompt's processing. An implementation that records prompt-submission timestamps MAY use that timestamp in the canonical URI even if individual tool calls use their own tool-call timestamps (). Tool-call timestamp URIs (those generated at the time a tool call executes) are valid provenance references but are not canonical: multiple such URIs from the same prompt are not equivalent by comparison (), even though they resolve to the same prompt (). Normalizing to canonical form: Implementations SHOULD normalize all prompt URI references for a given prompt to the canonical URI before writing provenance records. Normalizing to the prompt-id form, when available, enables deduplication of provenance entries across the tool calls of a single prompt without requiring session log access.

Normalization and Comparison Two prompt URIs SHOULD be considered equivalent if and only if all of the following hold after applying the normalization rules in Section 6:

Their scheme components are identical (case-insensitively).
Their agent-name components are identical (case-insensitively).
Their session-ref components identify the same session, determined as follows:
- If both are session identifiers: they are identical after percent-decoding (case-sensitive).
- If both are session aliases: they are identical after percent-decoding and case-folding to lowercase.
- If one is a session identifier and the other a session alias: they are equivalent if and only if the alias resolves to the same session identifier per the alias registry ().
Their prompt-ref components identify the same prompt reference, as determined by the following rules:
- If both are timestamps (date-time): they represent the same instant in time, after normalizing to UTC and applying the date-time comparison rules of .
- If both are prompt identifiers (prompt-id): they are identical after percent-decoding (case-sensitive, following percent-decoding).
- If one is a timestamp and the other is a prompt identifier: they are NOT equivalent; resolution () is required to determine whether they refer to the same prompt.

Timestamps that differ by any amount of time, however small, are NOT equivalent and SHALL NOT be treated as identifying the same prompt URI. Equivalence and resolution are distinct concepts: two non-equivalent URIs MAY nonetheless resolve to the same prompt (), and a single URI MAY be ambiguous (). Two URIs that differ only in their prompt-ref form (one using a timestamp, one using a prompt identifier) are likewise non-equivalent by this definition, even if they identify the same underlying prompt.

Resolution

Resolution Algorithm Resolution is the process of mapping a prompt URI to one or more candidate prompts in an agent's session log. Resolution is OPTIONAL; a prompt URI is valid and useful as a provenance reference even when the referenced session log is unavailable. A conformant resolver SHALL apply the following steps:

Parse the prompt URI and extract agent-name, session-ref, and prompt-ref. If session-ref is an alias, resolve it per to obtain the session identifier.
Locate the session log associated with the session identifier for the agent identified by agent-name. If no such log is accessible, the URI is unresolvable ().
If prompt-ref is a prompt-id (begins with ~): strip the ~ prefix, percent-decode the remainder, and locate all session log entries whose prompt correlation identifier matches. If exactly one entry is found, the URI resolves to that prompt. Proceed to step 5. If prompt-ref is a date-time: convert the timestamp to UTC milliseconds and identify all session log entries whose recorded timestamp falls within a resolution window centered on the URI timestamp. The RECOMMENDED resolution window is ±1 second; resolvers MAY use a narrower window when the URI timestamp has sub-second precision and the session log records sub-second timestamps.
From the candidate entries, identify those that are prompt-type entries (user messages that initiated a turn), as opposed to tool call or response entries.
If exactly one prompt-type candidate is found, the URI resolves to that prompt.
If multiple prompt-type candidates are found, the URI is ambiguous (). The resolver SHOULD report all candidates and SHOULD NOT silently select one.
If the session log records an agent-internal correlation identifier (e.g., promptId in Claude Code session logs , interactionId in Copilot session logs ), implementations MAY use that identifier to narrow candidate selection to a single result.

Alias Resolution When the session-ref component of a prompt URI does not parse as a UUID and is not otherwise recognizable as a session identifier, the resolver SHALL treat it as a session alias and apply the following steps before proceeding with :

Normalize the alias: percent-decode, then fold to lowercase.
Look up the normalized alias in the alias registry for the agent identified by agent-name.
If a matching entry is found, substitute the corresponding session identifier into the resolution process and continue with step 2.
If no matching entry is found, the URI is unresolvable (). Implementations SHOULD report "alias not registered" as a distinct unresolvable condition, separate from "session log not found."

Unresolvable URIs A prompt URI is unresolvable if any of the following conditions hold:

The session-ref is a session alias that is not registered in the alias registry.
The session log for the resolved session identifier is not accessible to the resolver.
The session log has been deleted, expired, or is otherwise unavailable.
The agent-name is not recognized by the resolver.
No session log entries fall within the resolution window.

An unresolvable URI is NOT invalid. The URI remains a valid provenance identifier and SHALL be preserved in provenance records even when the referenced session is no longer accessible. Resolvers SHOULD distinguish between "unresolvable" and "invalid" when reporting resolution status.

Ambiguity: Multiple URIs for One Prompt A single prompt MAY be the source of multiple tool calls, each of which produces a prompt URI with a distinct timestamp. This is the common case in agent workflows, where a single user message triggers a sequence of file reads, web fetches, and file writes, each implemented as a separate tool call. All prompt URIs generated within the same session from the same originating prompt refer to that same prompt, even though their prompt-ref components differ. Implementations SHOULD treat these URIs as semantically equivalent for provenance purposes, even though they are not syntactically equivalent () and will not compare as equal. When the agent provides a prompt correlation identifier, implementations SHOULD normalize all such URIs to the canonical prompt-id form () before writing provenance records. This eliminates the proliferation of distinct URIs for the same prompt and enables deduplication by string comparison, without session log access. Additionally, the same prompt may be identifiable by URIs with different timestamp precision: Both of the above URIs identify the same instant in time at different precision levels. Per , these URIs are NOT equivalent. Per , they SHOULD resolve to the same candidate when the resolution window is applied. Implementations that store provenance records SHOULD use a consistent timestamp precision to minimize the proliferation of distinct URIs for the same prompt.

Ambiguity: One URI for Multiple Prompts A single prompt URI MAY be ambiguous when multiple distinct prompts occur within the resolution window of its timestamp. This arises in the following conditions: Within-session collision: Two or more distinct user prompts within the same session are submitted and processed within the same second (or within the resolution window of a sub-second timestamp). This is uncommon in interactive agent sessions, where user prompts are typically separated by seconds to minutes, but MAY occur in automated pipelines where prompts are submitted programmatically without human pacing. Cross-session collision: Two sessions with different session identifiers are not a source of ambiguity for a given URI, since the session identifier is a URI component. However, if a resolver has access to session logs from multiple agents with the same agent-name, and two such logs share a session-id value (which SHOULD NOT occur when UUIDs are used), a cross-log collision is possible.

Mitigation Implementations SHOULD use millisecond-precision timestamps (rather than second-precision) to reduce the probability of within-session collisions. With millisecond precision, a collision requires two distinct prompts to arrive within the same millisecond, which is negligible in interactive use. Implementations MAY append a fragment identifier to a prompt URI to encode an agent-internal correlation identifier when that identifier is known at call time: Fragment identifiers used for this purpose are implementation-specific and are OPTIONAL and not required for interoperability. Resolvers that do not recognize a fragment identifier SHOULD ignore it and apply the standard resolution algorithm.

Disclosure Requirement Implementations that generate prompt URIs SHOULD document the timestamp precision they use and the conditions under which within-session collisions are possible, so that consumers of provenance records can assess the reliability of URI-based prompt identification in their deployment context.

Security Considerations Confidentiality: A prompt URI encodes the agent identity, session identifier, and approximate timestamp of a tool call. This information MAY be sensitive in deployments where session identifiers are treated as access credentials or where the existence of a particular agent interaction is confidential. Implementors SHOULD treat prompt URIs with the same access controls applied to session logs. Spoofability: Prompt URIs are not cryptographically signed. Any party with knowledge of a valid agent name, session identifier, and approximate timestamp can construct a syntactically valid URI. Resolvers SHALL NOT treat a prompt URI as proof of authenticity; they SHOULD verify that the referenced session log actually contains a prompt at the indicated time. Log availability: Resolution depends on the availability of session logs, which are typically stored on the client machine. Logs may be deleted, corrupted, or unavailable to the resolver. Provenance systems SHALL NOT treat an unresolvable URI as evidence of tampering; unresolvability is an expected operational condition. Session identifier reuse: If an agent implementation reuses session identifiers across sessions (which SHOULD NOT occur when UUIDs are used), URIs from different sessions would become ambiguous. Implementations SHALL use session identifiers with negligible collision probability.

IANA Considerations This document requests registration of the prompt URI scheme in the IANA Uniform Resource Identifier (URI) Schemes registry, established by .

Scheme name:: prompt
Status:: Provisional
Applications/protocols that use this scheme:: AI agent provenance metadata, session log indexers, agent tool frameworks.
Contact:: Keith W. Boone
Change controller:: Keith W. Boone
References:: This document.

Pending IANA registration, implementations SHALL treat the prompt scheme as an unregistered provisional scheme per Section 3.3.