The agent:// Protocol -- A URI-Based Framework for Interoperable Agents

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 23 October 2025.¶

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.¶

Table of Contents

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 agent communication protocols and libraries like [Agent2Agent], [FIPA-ACL], Contract Net Protocol [FIPA-CNP], [LangChain], Model Context Protocol [MCP], [AutoGen], [SemanticKernel] etc. It serves as an addressing and discovery layer that works alongside these communication protocol.¶

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.
+------------------+  +------------------+

The agent:// protocol supports:¶

• 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:¶

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+<protocol>://[authority]/[path]

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=...¶

agent-uri      = "agent" ["+" protocol] "://" authority ["/" path]
                 [ "?" query ] [ "#" fragment ]

protocol       = 1*( ALPHA / DIGIT / "-" )
authority      = [ userinfo "@" ] host [ ":" port ]
                 ; <authority, defined in RFC3986, Section 3.2>
path           = path-abempty
                 ; begins with "/" or is empty.
                 ; Defined in RFC3986, Section 3.3
query          = *( pchar / "/" / "?" )
                 ; <query, defined in RFC3986, Section 3.4>
fragment       = *( pchar / "/" / "?" )
                 ; <fragment, defined in RFC3986, Section 3.5>

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

5. Resolution Framework

Every agent MAY expose a self-describing document at:¶

<scheme>://<domain>/<path-to-agent>/agent.json

If a single agent is deployed at the top level then it should be under /.well-known to be compatible with Agent2Agent protocol.¶

• /.well-known/agent.json -- For single-agent deployments (compatible with Agent2Agent)¶

• /.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.¶

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.¶

https://<domain>/.well-known/agents.json

+---------+          +-------------+         +-------------+
|  Client | --URI--> |  Resolver   | -->URL->| Agent Server|
+---------+          +-------------+         +-------------+
                              |
                      (agent.json or agents.json)

{
  "agents": {
    "planner": "https://planner.example.com/.well-known/agent.json",
    "translator": "https://example.com/translator/agent.json"
  }
}

6. Transport Bindings

agent+local://<agent-name>

7. Capability Framework

Agents SHOULD expose a descriptor document at:¶

<agent-base-path>/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¶

  • 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).¶

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.¶

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.¶

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.¶

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 status and confidence metadata in responses where applicable.¶

GET /tasks/1234 HTTP/1.1
Host: planner.example.com
X-Session-ID: abcde-12345

+--------+       +-----------+       +-------------+
|  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             |

+----------+       +----------+       +------------+
|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     |                   |

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)¶

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.¶

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.¶

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¶

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.¶

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).¶

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¶

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.¶

agent:[+<protocol>]://<authority>/<path>[?<query>][#<fragment>]

13. Appendix A. Example Agent Descriptor

Following is an example of agent.json.¶

{
  "@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"
    }
  ]
}

A JSON-LD context is added to support semantic querying and graph-based processing.¶

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.¶

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

Author's Address