agent:// Protocol

The Gap

Protocols like Agent2Agent (A2A), MCP, and FIPA-ACL define how agents communicate. But none of them answer: how do you address an agent in the first place?

There's no standard way to say "this resource is an agent" and discover what it can do — not a web page, not an API, an agent with capabilities, interaction models, and transport preferences.

That's what agent:// solves.

The URI Scheme

agent://example.com/my-agent
agent+https://api.example.com/agents/assistant/chat
agent+wss://streaming.example.com/generate#continuous
agent+local://assistant

The agent:// scheme tells clients: this is an agent. The optional +protocol suffix specifies the transport. Without it, the client resolves the agent's preferred transport through discovery.

How Resolution Works

1. Client encounters agent://planner.acme.ai/travel
2. Fetches https://planner.acme.ai/.well-known/agents.json
3. Looks up the travel agent → gets descriptor URL
4. Fetches the agent descriptor (capabilities, transports, auth)
5. Invokes using the agent's preferred transport

No central registry. DNS-based. Works like the web. Resolvers must block private, loopback, and link-local IP ranges to prevent SSRF.

Conformance Levels

The protocol is designed for incremental adoption:

Level	Name	What You Need
0	Direct Invocation	Parse agent+<protocol>:// URIs, call directly
1	Discoverable	Publish /.well-known/agents.json
2	Resolvable	Implement full resolution with caching, multiple transports
3	Full	Capabilities, authentication, versioning, composition

Level 0 costs zero infrastructure — just use the URI format. Each level adds functionality without breaking what came before.

Transport Bindings

Agents don't all speak HTTP. The protocol registers six transport bindings:

• agent+https:// — Standard web APIs
• agent+wss:// — WebSocket Secure for real-time streaming
• agent+grpc:// — High-performance inter-agent calls
• agent+mqtt:// — MQTT 5.0 for IoT and edge agents
• agent+local:// — Same-machine agents (requires explicit user consent)
• agent+unix:// — Co-located processes via Unix domain socket

One URI scheme, any transport.

What's New in Draft 03

Draft 03 (published 18 April 2026) adds the layers you need to actually run agents in production, not just address them:

• Authentication & delegation — Reuses OAuth 2.0 Authorization Server Metadata (RFC 8414), Protected Resource Metadata (RFC 9728), and Token Exchange (RFC 8693) with nested act claims for delegation chains. HTTP Message Signatures (RFC 9421) for descriptor integrity. DID support for decentralized authorities.
• Skill-level metadata — Each skill declares id, name, description, plus optional input/output JSON Schema, streaming, idempotent, tags, contentTypes, depends[] (dependency graph), and per-skill auth overrides.
• Versioning — Profile-based negotiation via Accept: application/agent+json; profile="<version-uri>" (RFC 6906). Deprecation signaling through Sunset headers (RFC 8594) and Link: rel="successor-version".
• Multi-tenancy — Per-tenant registries at /.well-known/agents.json/<tenant>.
• Error handling — RFC 9457 Problem Details JSON for failures, plus standard rate-limit headers.
• Extension mechanisms — JSON-LD @context layering for semantic extensibility; x-<vendor> namespaces for non-standard fields.

What's deliberately not in the spec: pricing, performance SLAs, UI metadata, commerce terms. Those use external vocabularies (schema.org, OpenTelemetry semantic conventions) via the extension patterns. Keeping the normative scope narrow is a feature.

IETF Status

• draft-narvaneni-agent-uri-03 — published 18 April 2026, expires 20 October 2026
• Track: Experimental, Independent Submission

The draft proposes registration of:

• agent:// URI scheme with IANA (provisional)
• Well-known URI /.well-known/agents.json
• Media type application/agent+json
• Transport Bindings registry
• Interaction Models registry (agent2agent, mcp, fipa-acl, openapi)

Companion specifications planned: Dynamic Agent Registry Protocol (runtime registration), Local Agent Discovery, CBOR binary encoding for IoT, and a JSON-LD context document for descriptors.

Reference Implementation

A Python SDK (agent-uri on PyPI) implements the core stack:

from agent_uri import AgentClient

client = AgentClient()
result = await client.invoke(
    "agent://example.com/my-agent",
    {"message": "Hello"}
)

Server side:

from agent_uri import FastAPIAgentServer, capability

server = FastAPIAgentServer(name="my-agent", version="1.0.0")

@capability(name="echo", description="Echo back input")
async def echo(message: str) -> dict:
    return {"response": f"Echo: {message}"}

server.register_capability("echo", echo)

Today the SDK ships URI parsing, descriptor validation, resolution with caching, and transport bindings for HTTPS, WebSocket, and Local IPC. Catching the implementation up to draft-03 — adding the OAuth Token Exchange auth stack, profile-based versioning, gRPC / MQTT / Unix transports, multi-tenant registries, and a JSON-LD descriptor context — is in flight.