Independent Submission Y. Narvaneni Internet-Draft Independent Researcher Intended status: Experimental 16 October 2025 Expires: 19 April 2026 The agent:// Protocol -- A URI-Based Framework for Interoperable Agents draft-narvaneni-agent-uri-02 Abstract This document defines the agent:// protocol, a URI template-based framework as described in RFC 6570 for addressing, invoking, and interoperating with autonomous and semi-autonomous software agents. It introduces a layered architecture that supports minimal implementations (addressing and transport) and extensible features (capability discovery, contracts, orchestration). The protocol aims to foster interoperability among agents across ecosystems, platforms, and modalities, enabling composable and collaborative intelligent systems. Status of This Memo 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 19 April 2026. Copyright Notice Copyright (c) 2025 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. Narvaneni Expires 19 April 2026 [Page 1] Internet-Draft agent-uri October 2025 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Protocol Scope and Layering . . . . . . . . . . . . . . . . . 4 4. URI Scheme Specification . . . . . . . . . . . . . . . . . . 5 4.1. Components . . . . . . . . . . . . . . . . . . . . . . . 6 4.2. ABNF for agent:// URI . . . . . . . . . . . . . . . . . . 6 5. Resolution Framework . . . . . . . . . . . . . . . . . . . . 7 5.1. Ecosystem Registries . . . . . . . . . . . . . . . . . . 8 5.2. Trust Anchors . . . . . . . . . . . . . . . . . . . . . . 9 6. Transport Bindings . . . . . . . . . . . . . . . . . . . . . 9 6.1. Explicit Transport Binding . . . . . . . . . . . . . . . 9 6.2. Default Fallback Behavior . . . . . . . . . . . . . . . . 10 6.3. Use Cases and Recommended Bindings . . . . . . . . . . . 11 7. Capability Framework . . . . . . . . . . . . . . . . . . . . 11 8. Interaction Patterns {# interaction-patterns} . . . . . . . . 14 8.1. Stateful Interactions {# stateful-interactions} . . . . . 14 8.1.1. Recommended practices: . . . . . . . . . . . . . . . 15 8.2. Orchestration Patterns . . . . . . . . . . . . . . . . . 15 8.3. Typical Interaction Flows . . . . . . . . . . . . . . . . 15 8.3.1. Client-to-Agent Interaction . . . . . . . . . . . . . 15 8.3.2. Agent-to-Agent Interaction . . . . . . . . . . . . . 16 9. Error Handling {# error-handling} . . . . . . . . . . . . . . 17 10. Security and Privacy Considerations . . . . . . . . . . . . . 19 10.1. Compliance and Regulatory Considerations . . . . . . . . 20 11. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 21 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 12.1. URI Scheme Registration Template . . . . . . . . . . . . 21 12.2. Well-Known URI Registrations . . . . . . . . . . . . . . 22 12.3. Media Type Registration for application/agent+json . . . 23 13. Appendix A. Example Agent Descriptor . . . . . . . . . . . . 23 14. Appendix B. Use Cases . . . . . . . . . . . . . . . . . . . 25 15. Appendix C. Reference Implementation . . . . . . . . . . . . 25 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 26 References . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Normative References . . . . . . . . . . . . . . . . . . . . . 26 Informative References . . . . . . . . . . . . . . . . . . . . 27 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 28 1. Introduction The rise of intelligent software agents necessitates a standardized way to identify, invoke, and coordinate them across diverse platforms. While protocols like HTTP [RFC9110] provide a transport mechanism for static APIs, agents differ significantly in behavior, output variability, and interaction patterns. The agent:// proposes a URI scheme and resolution model designed to complement existing Narvaneni Expires 19 April 2026 [Page 2] Internet-Draft agent-uri October 2025 agent communication protocols and libraries like [Agent2Agent], [FIPA-ACL], Contract Net Protocol [FIPA-CNP], [LangChain], Model Context Protocol [MCP], [AutoGen], [SemanticKernel] etc. This document defines a resolution algorithm that maps agent:// URIs to transport endpoints using HTTPS, WebSocket, or local bindings as defined later. It serves as an addressing and discovery layer that works alongside these communication protocols. The agent:// protocol supports diverse agent deployment models through a unified addressing scheme: * Cloud-based agents accessible via standard web protocols * Local agents running on the user's device through the agent+local:// scheme * On-premises agents within organizational boundaries * Decentralized agents operating across distributed networks This flexibility addresses a critical gap in current agent ecosystems, enabling applications (including browsers) to discover and invoke agents consistently regardless of where they're hosted. By providing standardized URI[RFC6570] patterns for both remote and local agents, the protocol simplifies previously complex integration scenarios like browser-to-local-agent delegation for privileged operations. +------------------+ | Agent Applications| +------------------+ <-> +------------------+ | agent:// URI | <- Addressing, Resolution, Discovery +------------------+ <-> +------------------+ +------------------+ | Agent2Agent | | CNP,. etc | <- Communication Protocols +------------------+ +------------------+ <-> <-> +------------------+ +------------------+ | Transport Layer | | Transport Layer | <- HTTP, WebSockets, etc. +------------------+ +------------------+ Figure 1: Agent Protocol Stack Architecture The agent:// protocol supports: Narvaneni Expires 19 April 2026 [Page 3] Internet-Draft agent-uri October 2025 * Unique and resolvable addressing of agents * Optional self-describing capabilities * Consistent invocation semantics over existing transports * Progressive support for advanced patterns like delegation, collaboration, and orchestration This document outlines the specification for the agent:// protocol, beginning with its URI scheme and extending through capability description, transport bindings, and extensibility patterns. A reference implementation of the agent:// protocol is available to demonstrate resolution, transport bindings, capability discovery, and orchestration patterns. Implementers and adopters can find this example implementation at: [AGENT-URI-REPO] 2. Terminology * *Agent*: An autonomous or semi-autonomous software entity that can receive instructions and perform actions. * *Agent Descriptor (agent.json)*: A machine-readable document that describes an agent's identity, capabilities, and behavior. * *Capability*: A self-contained function or behavior an agent offers. * *Resolver*: A service or mechanism that maps a URI to a network endpoint or metadata. * *Invocation*: The act of calling a capability on an agent with input parameters. 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 RFC 2119, BCP 14 [RFC2119], [RFC8174] when, and only when, they appear in all capitals, as shown here. 3. Protocol Scope and Layering The agent:// protocol is designed as a layered framework: Narvaneni Expires 19 April 2026 [Page 4] Internet-Draft agent-uri October 2025 +===================+================================+===========+ | Layer | Purpose | Mandatory | +===================+================================+===========+ | URI Scheme | Unique addressing | Yes | +-------------------+--------------------------------+-----------+ | Transport Binding | Mechanism for invocation | Yes | | | (e.g., HTTP, WSS, Matrix, IPC) | | +-------------------+--------------------------------+-----------+ | Agent Descriptor | Self-describing agent | Optional | | | interface | | +-------------------+--------------------------------+-----------+ | Resolution | Maps agent URIs to endpoints | Optional | | Framework | | | +-------------------+--------------------------------+-----------+ | Application | Shared vocab for capability | Optional | | Semantics | naming | | +-------------------+--------------------------------+-----------+ Table 1: Protocol Layering Structure This layering allows implementations to adopt minimal or full- featured configurations, depending on their needs. 4. URI Scheme Specification The format of agent:// URIs is: agent://[authority]/[path]?[query]#[fragment] agent+://[authority]/[path] Figure 2: Agent URI Format Examples: * agent://example.com/planning/gen-iti?city=Paris * agent://planner.example.com/claude?text=Hello * agent+https://example.com/assistants/chatgpt?query=hello * agent+local://examplelocalagent * agent:///did:web:example.com:agent:researcher/get-article?doi=... Narvaneni Expires 19 April 2026 [Page 5] Internet-Draft agent-uri October 2025 To resolve agent:///?: 1. Fetch https:///.well-known/agents.json (if present) 2. Locate mapping -> agent descriptor URL 3. Fetch descriptor (agent.json) 4. Extract transport.endpoint or transport metadata 5. Invoke using indicated method or default: - GET for read-only, POST for state-changing 6. If none found -> agent+https:// fallback 4.1. Components * *Authority*: Uniquely identifies the agent or agent namespace (e.g., DNS or DID). * *Path*: Specifies the agent being invoked. The [path] is opaque to agent:// and can represent either a namespace or direct capability. * *Query*: Contains serialized parameters. Query parameters SHOULD be URL-encoded as key=value pairs. If more complex structures are needed, clients SHOULD use HTTP POST requests with application/ json bodies rather than base64-encoding payloads into query parameters. * *Fragment*: Optional reference for context or sub-capability. * The optional + indicates explicit transport binding. * If not specified, clients use resolution or fall back to HTTPS- based invocation. 4.2. ABNF for agent:// URI Narvaneni Expires 19 April 2026 [Page 6] Internet-Draft agent-uri October 2025 agent-uri = "agent" ["+" protocol] ":" hier-part [ "?" query ] [ "#" fragment ] ; hier-part from RFC3986, allowing both //authority and path-rootless protocol = 1*( ALPHA / DIGIT / "-" ) authority = [ userinfo "@" ] host [ ":" port ] ; path = path-abempty ; begins with "/" or is empty. ; Defined in RFC3986, Section 3.3 query = *( pchar / "/" / "?" ) ; fragment = *( pchar / "/" / "?" ) ; pchar = unreserved / pct-encoded / sub-delims / ":" / "@" unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" pct-encoded = "%" HEXDIG HEXDIG sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" ; Character sets like pchar, unreserved, etc. are defined in RFC3986 Figure 3: ABNF Grammar for agent:// URI Scheme 5. Resolution Framework Every agent MAY expose a self-describing document at: :////agent.json Agents reachable over the network SHOULD publish /.well-known/ agent.json If a single agent is deployed at the top level then it should be under /.well-known. * /.well-known/agent.json -- For single-agent deployments (compatible with AgentCard) Multi-agent domains MAY additionally expose /.well-known/agents.json. * /.well-known/agents.json -- For multi-agent domains (maps agent names -> descriptors) This descriptor is OPTIONAL but RECOMMENDED. It enables capability discovery, transport resolution, and compatibility with ecosystem tools. Narvaneni Expires 19 April 2026 [Page 7] Internet-Draft agent-uri October 2025 When present, the descriptor MAY use the [AgentCard] (as defined by Agent2Agent protocol by Google as of April 2025) schema as one possible format, or any equivalent [JSON-LD11] based structure that expresses the agent's identity, capabilities, and behavioral metadata. If the agent is deployed at a subdomain (e.g., planner.example.org), the agent descriptor SHOULD be published at /.well-known/agent.json on that domain. Resolvers MUST restrict fetches to HTTPS schemes and MUST NOT resolve to private or loopback IP ranges. Resolvers SHOULD verify TLS certificates and may require signed descriptors. 5.1. Ecosystem Registries Domains MAY publish: https:///.well-known/agents.json This file should map agent names to their agent.json URLs for simplified enumeration. It is OPTIONAL but RECOMMENDED for better ecosystem interoperability. Implementations MAY support resolution of agent URIs via: * Static resolution maps * DID resolution * WebFinger or custom resolvers Resolvers SHOULD support caching and capability introspection where applicable. +---------+ +-------------+ +-------------+ | Client | --URI--> | Resolver | -->URL->| Agent Server| +---------+ +-------------+ +-------------+ | (agent.json or agents.json) Figure 4: Agent URI Resolution Process *Example*: Narvaneni Expires 19 April 2026 [Page 8] Internet-Draft agent-uri October 2025 { "agents": { "planner": "https://planner.example.com/.well-known/agent.json", "translator": "https://example.com/translator/agent.json" } } Agents SHOULD use standard HTTP caching mechanisms (Cache-Control, ETag, Last-Modified) to enable efficient resolution and minimize unnecessary descriptor fetches. Clients SHOULD respect these headers and cache descriptors appropriately 5.2. Trust Anchors Domains MAY use trust anchors (e.g., DNSSEC, HTTPS certificates, or DID-based verification) to enhance identity assurance. A practical example of URI resolution, agent descriptor fetching, and caching strategies is included in the reference implementation available at: [AGENT-URI-REPO] 6. Transport Bindings 6.1. Explicit Transport Binding Use the agent+:// scheme for clarity: +===========+================+=============+====================+ | Transport | Format | Method | Description | +===========+================+=============+====================+ | HTTPS | agent+https:// | GET/POST | Secure HTTP-based | | | | | invocation | +-----------+----------------+-------------+--------------------+ | WebSocket | agent+wss:// | NDJSON | Real-time | | Secure | | stream | streaming | +-----------+----------------+-------------+--------------------+ | Local | agent+local:// | IPC/broker | Runtime-registered | | | | call | local agents | +-----------+----------------+-------------+--------------------+ | Unix | agent+unix:// | Unix domain | IPC for co-located | | Socket | | socket | agents | +-----------+----------------+-------------+--------------------+ Table 2: Transport Binding Formats Narvaneni Expires 19 April 2026 [Page 9] Internet-Draft agent-uri October 2025 The agent+:// scheme allows explicit declaration of such bindings, enabling clarity, extensibility, and optimized routing. When no explicit transport is declared, clients MAY rely on resolution metadata (e.g., agent.json) or default to HTTPS-based invocation. This flexibility ensures the protocol can adapt to different performance, privacy, or coordination requirements while remaining consistent at the addressing and invocation layer. Local agents should be accessed using: agent+local:// agent+local:// requires explicit user consent and origin binding. Implementations MUST prompt before first use. This allows agent runtimes to register their presence using a local resolver (e.g., via IPC, sockets, or service registry). The transport mechanism is implementation-specific. The agent+local:// scheme specifically addresses the current lack of standardized methods for browser-based applications to invoke locally installed agents. This enables web applications to delegate tasks to local agents that can perform privileged operations such as file system access, desktop automation, or hardware interaction - capabilities that are typically restricted in browser environments. Security considerations for such invocations are discussed in Section 10. 6.2. Default Fallback Behavior If the protocol is omitted (i.e., agent:// is used), clients: 1. Check .well-known/agents.json (if available) 2. Retrieve the agent descriptor at agent.json for the specified path 3. Use the transport or endpoint hints from the descriptor If nothing is found, clients MAY fall back to: * HTTPS (default transport protocol) * HTTP POST if payload present, otherwise GET Narvaneni Expires 19 April 2026 [Page 10] Internet-Draft agent-uri October 2025 Note: This fallback behavior is provided for convenience and basic interoperability, but production systems SHOULD prefer explicit transport bindings or resolver-based discovery for robustness and clarity. Clients SHOULD prefer explicit transport bindings (agent+https://) where available, and fall back to resolution-based discovery (agent://) when agent transport metadata is reliably available. Explicit binding reduces resolution ambiguity and improves latency. 6.3. Use Cases and Recommended Bindings The following table outlines some use cases and recommended bindings +=================================+==========================+ | Use Case | Recommended Binding | +=================================+==========================+ | Agent with known HTTPS endpoint | agent+https:// | +---------------------------------+--------------------------+ | Local runtime agent | agent+local:// | +---------------------------------+--------------------------+ | Dynamic/multi-transport agents | agent:// with agent.json | +---------------------------------+--------------------------+ | Inter-agent calls within a | agent:// or | | known context | agent+matrix:// | +---------------------------------+--------------------------+ Table 3: Recommended Bindings for Common Use Cases 7. Capability Framework Agents SHOULD expose a descriptor document at: /agent.json This descriptor MAY follow: * The AgentCard structure (as defined by Google's Agent2Agent protocol as of April 2025), or another equivalent format * Any format other than AgentCard SHOULD be expressed in [JSON-LD11] to enable semantic discovery Agent descriptors SHOULD include: * Agent name and version Narvaneni Expires 19 April 2026 [Page 11] Internet-Draft agent-uri October 2025 - MAY include supportedVersions indicating the list of older versions and their end-points. - Versioning should follow [SemVer] or later - Clients SHOULD verify compatibility based on documented major, minor, and patch versions * Human-readable description * Input/output schemas (e.g., JSON Schema) * Capability list with IDs, descriptions, tags, version * Optional behavioral metadata (e.g., isDeterministic, expectedOutputVariability, requiresContext: boolean, memoryEnabled: boolean, responseLatency: "low" | "medium" | "high", confidenceEstimation: boolean) - isDeterministic (boolean): Indicates whether repeated calls with identical inputs yield identical outputs. - expectedOutputVariability: indicates typical variability in outputs, similar to temperature setting - responseLatency: Expected response time. - requiresContext (boolean): Indicates whether the input needs context or the agent can work on its own - memoryEnabled (boolean): Indicates whether the agent will remember the interactions * Optional transport or invocation hints * Optional authentication or permission requirements * Optional state management practices * Optional interactionModel to indicate a way to interact (e.g. agent2agent, fipa-acl, kqml, contract-net, emergent etc). If mentioned, the message payload SHOULD follow the model's defined parameters if any. Agents MAY expose inputFormats and outputFormats per capability using standard MIME types (e.g., application/json, application/ld+json, application/fipa-acl). Narvaneni Expires 19 April 2026 [Page 12] Internet-Draft agent-uri October 2025 Agent descriptors SHOULD include input/output schemas (e.g., JSON Schema) and MAY document content negotiation support via the contentTypes field per capability. This allows clients to understand and negotiate payload encoding, enabling interoperability across ecosystems that use JSON, [JSON-LD11], RDF/XML, [FIPA-ACL], or other formats. Clients MAY use standard negotiation mechanisms such as Content-Type and Accept headers (in HTTP), or envelope metadata (in protocols like [JSON-RPC], [Matrix], etc.). Implementations MAY advertise protocol compatility via metadata fields such as interactionModel, orchestration, or supported envelopeSchemas etc. These metadata fields enable clients and agent runtimes to interoperate across heterogeneous ecosystems and communication models. This extensibility ensures agent:// can serve as a unifying addressing and invocation layer, bridging agents that follow established standards, platform-specific conventions, or learned behaviors in dynamic environments. If an agent.json is provided, it SHOULD contain at least: name, version, and one or more capabilities. Clients SHOULD explicitly specify the agent version either as a URI path segment, query parameter (?version=3.1.4), or HTTP header (X- Agent-Version). If omitted, servers SHOULD assume the latest version. Agents MUST document their preferred method for version negotiation clearly in their descriptor. Major version increments indicate breaking changes; clients default only within same major. While .well-known/agents.json MAY be used to enumerate all available agents under a domain, the individual agent.json files serve as the canonical source of truth. All published descriptors MUST use media type application/agent+json (or JSON-LD profile). Expressing descriptors in [JSON-LD11] enables semantic interoperability and supports alignment with common web-based data models. Implementers MAY choose to embed, proxy, or map to other protocols within the agent.json descriptor or transport bindings, allowing for seamless orchestration and hybrid deployments. Narvaneni Expires 19 April 2026 [Page 13] Internet-Draft agent-uri October 2025 8. Interaction Patterns {# interaction-patterns} Supported interaction types include: * Request/Response (synchronous) * Deferred response (polling or webhook) SHOULD include a taskId and polling interval hint. * Streaming responses (e.g., Server-Sent Events, WebSocket). Streaming responses over agent+wss:// SHOULD use newline-delimited JSON (NDJSON) * Delegated invocation (calling other agents on behalf of user) * Asynchronous event notifications via HTTP webhooks or WebSockets. Event notifications if available SHOULD include event types, payloads, and identifiers. All interaction patterns (e.g., streaming, event-driven, polling) are transport-agnostic but MAY impose format constraints (e.g., NDJSON over WebSockets). Agents SHOULD include traceparent or X-Task-ID headers to correlate multi-agent workflows. Agents SHOULD include status and confidence metadata in responses where applicable. 8.1. Stateful Interactions {# stateful-interactions} The agent:// protocol leverages HTTP's established mechanisms for state management. Clients and agents SHOULD use standard HTTP headers or query parameters to pass identifiers such as sessionId or taskId. Agents MAY maintain state across interactions using these identifiers. Clients and agents SHOULD agree on session semantics via capability descriptors or invocation headers. Non-HTTP transports SHOULD include session or task identifiers within message envelopes (e.g., JSON-RPC headers, WebSocket message metadata, Matrix events). These fields SHOULD follow naming conventions similar to sessionId, taskId, etc. When the transport lacks a native header mechanism, agents SHOULD extract session information from the body or envelope metadata. Narvaneni Expires 19 April 2026 [Page 14] Internet-Draft agent-uri October 2025 When content negotiation fails or the requested format is not supported, agents SHOULD respond with a 406 Not Acceptable HTTP error or equivalent, and MAY include supported formats in the response metadata. 8.1.1. Recommended practices: * Use HTTP headers (e.g., X-Session-ID, X-Task-ID) or query parameters for session and task identifiers. * Clearly document state identifiers and their expected lifecycle in the agent's descriptor (agent.json). *Example*: GET /tasks/1234 HTTP/1.1 Host: planner.example.com X-Session-ID: abcde-12345 8.2. Orchestration Patterns Agents MAY invoke other agents as part of delegated or composite tasks. Agents SHOULD explicitly provide orchestration workflows, delegation chains, or composite interactions either in their agent.json or in their response metadata. 8.3. Typical Interaction Flows 8.3.1. Client-to-Agent Interaction A typical user-driven invocation of an agent using the agent:// protocol follows these steps: Narvaneni Expires 19 April 2026 [Page 15] Internet-Draft agent-uri October 2025 +--------+ +-----------+ +-------------+ | User | --> | Client | --> | Agent Host | +--------+ +-----------+ +-------------+ | | | | Initiates | | | intent (e.g., | | | "Plan my trip")| | | | | | | Resolves agent URI | | | --> agents.json / agent.json | | Retrieves capabilities | | | | | Constructs request | | | --> agent://plan.example.com/gen-iti?city=Rio | | | | | | Validate input | | | Process logic/call tools | | | May call sub-agents | | | | | Receives response | | | <== itinerary JSON | | Presents result to user | Figure 5: Client-to-Agent Interaction Flow *Notes*: * The client MAY handle fallback logic if the agent cannot be resolved initially. * Authentication MAY be required before invocation. * The invocation can be a simple GET or POST depending on input size and structure. 8.3.2. Agent-to-Agent Interaction Agents MAY interact with each other using agent:// URIs to delegate tasks or compose workflows. *Example: A planning agent invoking a translation agent*: Narvaneni Expires 19 April 2026 [Page 16] Internet-Draft agent-uri October 2025 +----------+ +----------+ +------------+ |Planning |------>|Resolver/ |------>|Translation | |Agent | |URI | |Agent | +----------+ +----------+ +------------+ | | | | Input: | | | {"city":"Paris"} | | | | | | Needs translation| | | | | | | Resolves URI: | |--agent://translator.example/translate?text=Bonjour-->| | | | | | --> Get | | | agent.json | | | --> Determine | | | transport | | | | | | | Process translation | | | Return translated JSON |<-----------------|<------------------| | Merge & return | | | to user/client | | | or continues | | Figure 6: Agent-to-Agent Interaction Flow *Chaining Behavior*: * The invoking agent MAY include X-Task-ID, X-Delegation-Chain, or equivalent headers. * The response MAY include intermediate metadata such as confidence, sourceAgent, taskTrace, or timeTaken. 9. Error Handling {# error-handling} The agent:// protocol MAY leverage HTTP standard status codes for signaling errors. Implementations MAY return errors using standard HTTP status codes along with structured JSON error responses conforming to [RFC9457] ("Problem Details for HTTP APIs"). **Recommended HTTP status codes include (but are not limited to) Narvaneni Expires 19 April 2026 [Page 17] Internet-Draft agent-uri October 2025 +=============+========================================+ | Status Code | Meaning | +=============+========================================+ | 400 | Bad Request (e.g., invalid parameters) | +-------------+----------------------------------------+ | 401 | Unauthorized | +-------------+----------------------------------------+ | 403 | Forbidden | +-------------+----------------------------------------+ | 404 | Capability or resource not found | +-------------+----------------------------------------+ | 409 | Conflict (e.g., state mismatch) | +-------------+----------------------------------------+ | 429 | Too Many Requests (rate limiting) | +-------------+----------------------------------------+ | 500 | Internal Server Error | +-------------+----------------------------------------+ | 503 | Service Unavailable | +-------------+----------------------------------------+ Table 4: Recommended HTTP status codes Example: HTTP/1.1 404 Not Found Content-Type: application/problem+json { "type": "https://example.com/errors/capability-not-found", "title": "Capability Not Found", "status": 404, "detail": "The requested capability 'gen-iti' was not found.", "instance": "/planner/gen-iti" } {: #fig-error-response title="Example HTTP Error Response"} This format is not prescriptive but aims to encourage consistency. Implementations MAY adapt the error schema based on their transport layer (e.g., JSON-RPC, HTTP status + body, WebSocket messages). For non-HTTP transports (e.g., WebSockets, Matrix), agents SHOULD still return structured errors using similar JSON structures (type, title, detail, status), encapsulated within the transport's native message envelope (e.g., JSON-RPC error objects, Matrix event content fields). Implementers SHOULD document chosen structures clearly in their capability descriptors. Narvaneni Expires 19 April 2026 [Page 18] Internet-Draft agent-uri October 2025 Where applicable, implementations SHOULD align with existing conventions such as: * JSON-RPC error objects (code, message, data) * [OpenAPI] or REST error payloads * [GraphQL] errors array format Recommended error categories: * CapabilityNotFound * InvalidInput * AmbiguousResponse * Timeout * PermissionDenied Clients SHOULD parse and utilize these structured responses to handle errors gracefully. 10. Security and Privacy Considerations The agent:// protocol explicitly relies on widely-adopted HTTP authentication and authorization standards. Agents SHOULD support standard authentication and authorization schemes such as OAuth2 (Bearer tokens), API keys, or signed payloads. When using HTTPS, mutual TLS MAY be employed. JSON Web Tokens (JWT) are RECOMMENDED for conveying signed claims between agents. For agent+local://, browsers and runtimes MUST enforce same-origin policy, token handshake, and user mediation before invoking a local agent. Security extensions MAY include: * OAuth2 [RFC6750] Bearer Tokens * JSON Web Tokens (JWT [RFC7519]) * Mutual TLS (mTLS [RFC8705]) authentication * API Keys via HTTP headers (e.g., X-API-Key) * Capability-based access control * Delegation chains Narvaneni Expires 19 April 2026 [Page 19] Internet-Draft agent-uri October 2025 For non-HTTP transports (e.g., WebSocket, Matrix), agents SHOULD leverage native authentication mechanisms, such as WebSocket protocol-level authentication tokens or Matrix homeserver authentication flows. Agents MUST clearly document supported security mechanisms per transport binding. If OAuth 2.0 is used, authorization flows MUST conform to [RFC6749]; bearer usage per [RFC6750]. When using Decentralized Identifiers [DID-CORE] as authority, agent descriptors MAY be cryptographically signed. Clients SHOULD verify such signatures against the corresponding DID Document. For agent-to-agent delegation, agents SHOULD include delegation metadata (e.g., X-Delegation-Chain) that identifies prior actors. These chains SHOULD be signed or verifiable via claims (e.g., using JWT, Verifiable Credentials, or DID-linked proofs). Resolvers SHOULD use HTTPS with certificate validation and SHOULD validate integrity using ETag/Last-Modified for caching; if signature metadata is present, SHOULD verify signature per the descriptor's signature scheme. Agents MUST minimize data retention and expose revoke/delete interfaces for user data. Privacy recommendations: Agents SHOULD adhere to privacy best practices, including: * Data minimization (collect only necessary data) * Explicit consent and revocation mechanisms * Clear logging/audit trails * Ethical AI guidelines, including bias detection and fairness assessments as they evolve 10.1. Compliance and Regulatory Considerations Implementers SHOULD ensure compliance with relevant legal frameworks (e.g., GDPR, CCPA) of the jurisdictions where the agent is hosted. Agents processing sensitive data SHOULD provide audit trails and explicit consent mechanisms clearly documented in capability descriptors. Narvaneni Expires 19 April 2026 [Page 20] Internet-Draft agent-uri October 2025 11. Extensibility The protocol supports extension via: * Namespaced capability vocabularies * Alternate transport bindings * Extended agent descriptors * Optional orchestration layers (task graphs, workflows) Extension proposals SHOULD be documented clearly, and ideally reviewed through established processes such as community forums, dedicated working groups, or public registries to ensure transparency and interoperability. 12. IANA Considerations This document requests the registration of the agent URI scheme in the IANA "Uniform Resource Identifier (URI) Schemes" registry. 12.1. URI Scheme Registration Template * *Scheme Name*: agent * *Status*: Provisional * *Applications/Protocols That Use This Scheme*: The agent URI scheme identifies and invokes autonomous or semi-autonomous software agents across systems. It provides transport-agnostic addressing layer supporting discovery, invocation and orchestration. The scheme is compatible with existing schemes such as https, did and web+ schemes where appropriate. * *Contact*: Yaswanth Narvaneni * *Change Controller*: The author or a relevant standards body such as the IETF if adopted. * *References*: This document (Internet-Draft): _agent:// Protocol -- A URI-Based Framework for Interoperable Agents_ [RFC3986] - Uniform Resource Identifier (URI): Generic Syntax [RFC7595] - Guidelines and Registration Procedures for URI Schemes * *URI Syntax*: The general form of an agent URI is: * *Related Registrations:* Narvaneni Expires 19 April 2026 [Page 21] Internet-Draft agent-uri October 2025 - Well-Known URIs (Section 12.2): /.well-known/agent.json, /.well-known/agents.json - Media Type (Section 12.3): application/agent+json agent:[+]:///[?][#] Where: - authority is typically a domain name or Decentralized Identifier (DID) - path is an opaque agent-specific capability or namespace - query includes serialized key-value parameters - fragment MAY reference a sub-capability or context - The optional + segment indicates an explicit transport binding (e.g., agent+https://) Detailed ABNF is specified in Section 4.2 of this document. * *Security Considerations*: The agent scheme does not introduce new transport-layer vulnerabilities but inherits risks from underlying protocols such as HTTP, WebSocket, or local execution environments. Implementers should apply standard authentication and authorization measures, such as OAuth2, JWTs, or mutual TLS. See Section 10 for security and privacy guidance. 12.2. Well-Known URI Registrations This document registers the following Well-Known URIs under the "Well-Known URIs" registry established by RFC 8615: 1. *Name:* agent.json *Purpose:* Provides the self-describing metadata document (agent.json) for a single network-addressable agent. *Expected Content:* JSON object conforming to application/ agent+json. *Reference:* This document. *Security Considerations:* Accessible only via HTTPS. Agents SHOULD sign or ETag-pin the descriptor. 2. *Name:* agents.json *Purpose:* Provides a registry mapping of agent names to descriptor URLs for multi-agent domains. *Expected Content:* JSON object mapping agent identifiers to agent.json URLs. *Reference:* This document. *Security Considerations:* Same as above. Narvaneni Expires 19 April 2026 [Page 22] Internet-Draft agent-uri October 2025 12.3. Media Type Registration for application/agent+json Type name: application Subtype name: agent+json Required parameters: none Optional parameters: profile (for JSON-LD contexts) Encoding considerations: 8bit; uses UTF-8 encoded JSON Security considerations: Carries metadata that can affect network routing and authorization; publishers SHOULD serve only over HTTPS and validate signatures or ETags. Interoperability considerations: Compatible with JSON-LD 1.1 and plain JSON processors. Published specification: This document Applications that use this media type: Agent resolvers and runtimes using the agent:// protocol. Additional information: None Person & email address to contact for further information: Yaswanth Narvaneni Intended usage: COMMON Author/Change controller: IETF if standardized; author for independent submissions. The profile parameter usage follows the concept in RFC 6906 [RFC6906] (Profiles), and media type registration procedures follow RFC 6838 [RFC6838]. 13. Appendix A. Example Agent Descriptor Following is an example of agent.json. Narvaneni Expires 19 April 2026 [Page 23] Internet-Draft agent-uri October 2025 { "@context": "https://example.org/agent-context.jsonld", "name": "planner.example.com", "description": "Agent helps in researching & planning itineraries", "url": "agent://planner.example.com/", "provider": { "organization": "Example AI Org" }, "documentationUrl": "https://planner.example.com/docs", "interactionModel": "agent2agent", "orchestration": "delegation", "envelopeSchemas": ["fipa-acl"], "version": "3.1.4", "supportedVersions": { "3.0.0": "/v3/", "2.1.2": "/olderversion/v2.1.2/", "1.0": "/version-1/" }, "capabilities": [ { "name": "gen-iti", "version": "2.1.5", "description": "Creates a travel itinerary for a given city.", "input": { "city": "string" }, "output": { "itinerary": "array" }, "isDeterministic": false, "expectedOutputVariability": "medium", "contentTypes": { "inputFormat": ["application/json", "application/ld+json"], "outputFormat": ["application/json"] } } ], "authentication": { "schemes": ["OAuth2"] }, "skills": [ { "id": "agent-skill-1", "name": "research-location" } ] } Figure 7: Example Agent Descriptor in JSON-LD A JSON-LD context is added to support semantic querying and graph- based processing. Narvaneni Expires 19 April 2026 [Page 24] Internet-Draft agent-uri October 2025 14. Appendix B. Use Cases * Composing workflows with agents from different vendors * Enabling discovery and invocation in agent marketplaces * Facilitating human-in-the-loop workflows with agent transparency * Building knowledge-based agents that invoke retrieval agents * Real-time collaboration among specialized agents * Browser-to-local-agent delegation for privileged operations and desktop automation * Consistent addressing for agents across network boundaries and security contexts 15. Appendix C. Reference Implementation A reference implementation of the agent:// protocol is available to guide implementers, demonstrating the following functionalities: * URI parsing and resolution (agent.json, .well-known endpoints) * Transport bindings including HTTPS, WebSocket, Matrix, and Local IPC * Capability descriptor discovery, caching, and semantic processing * Orchestration and delegation chaining examples * Error handling, payload negotiation, and versioning patterns * Security examples covering OAuth2, JWT, and mutual TLS (mTLS) The implementation is open-source and maintained at: [AGENT-URI-REPO] Implementers are encouraged to use this as a starting point or reference during their implementation efforts. Narvaneni Expires 19 April 2026 [Page 25] Internet-Draft agent-uri October 2025 Acknowledgements This draft reflects observations and aspirations drawn from emerging agent ecosystems. It builds on publicly available research, community discussions, and early experimentation with agent-oriented protocols. It is intended as a foundation for future refinement and collaboration. References Normative References [DID-CORE] Sporny, M., Longley, D., Sabadello, M., Reed, D., Steele, O., and C. Allen, "Decentralized Identifiers (DIDs) v1.0", W3C Recommendation, July 2022, . [JSON-LD11] Sporny, M., Longley, D., Kellogg, G., Lanthaler, M., Champin, P., and N. Lindstrom, "JSON-LD 1.1: A JSON-based Serialization for Linked Data", W3C Recommendation, July 2020, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, March 2012, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, . Narvaneni Expires 19 April 2026 [Page 26] Internet-Draft agent-uri October 2025 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines and Registration Procedures for URI Schemes", BCP 35, RFC 7595, DOI 10.17487/RFC7595, June 2015, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens", RFC 8705, DOI 10.17487/RFC8705, February 2020, . [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . [RFC9457] Nottingham, M., Wilde, E., and S. Dalal, "Problem Details for HTTP APIs", RFC 9457, DOI 10.17487/RFC9457, July 2023, . Informative References [AGENT-URI-REPO] Narvaneni, Y., "Agent URI Protocol Reference Implementation", 2025, . [Agent2Agent] Google LLC, "Agent2Agent Protocol", April 2025, . [AgentCard] Google LLC, "Agent Card Schema from Agent2Agent Protocol", April 2025, . [AutoGen] Microsoft Research, "AutoGen: Enabling LLM Applications with Multi-Agent Conversations", 2024, . Narvaneni Expires 19 April 2026 [Page 27] Internet-Draft agent-uri October 2025 [FIPA-ACL] Foundation for Intelligent Physical Agents, "FIPA ACL Message Structure Specification", 2002, . [FIPA-CNP] Foundation for Intelligent Physical Agents, "FIPA Contract Net Interaction Protocol Specification", 2002, . [GraphQL] GraphQL Foundation, "GraphQL: A Query Language for APIs", October 2021, . [JSON-RPC] JSON-RPC Working Group, "JSON-RPC 2.0 Specification", 4 January 2013, . [LangChain] LangChain Team, "LangChain Documentation", 2024, . [Matrix] The Matrix org Foundation, "Matrix Specification v1.14", 2014, . [MCP] Anthropic PBC, "Model Context Protocol (MCP)", March 2025, . [OpenAPI] OpenAPI Initiative, "OpenAPI Specification v3.1.0", October 2024, . [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013, . [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, DOI 10.17487/RFC6906, March 2013, . [SemanticKernel] Microsoft, "Semantic Kernel SDK", 2024, . [SemVer] Preston-Werner, T., "Semantic Versioning 2.0.0", 2013, . Author's Address Narvaneni Expires 19 April 2026 [Page 28] Internet-Draft agent-uri October 2025 Yaswanth Narvaneni Independent Researcher London United Kingdom Email: yaswanth+ietf@gmail.com Narvaneni Expires 19 April 2026 [Page 29]