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.

Conformance Levels

The protocol is designed for incremental adoption:

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

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

Transport Agnostic

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

• HTTPS — Standard web APIs
• WebSocket — Real-time streaming
• gRPC — High-performance inter-agent calls
• MQTT — IoT and edge agents
• Local IPC — Same-machine agents
• Unix Socket — Co-located processes

One URI scheme, any transport.

IETF Status

The specification is submitted as draft-narvaneni-agent-uri-03 to the IETF as an experimental independent submission. It proposes:

• Registration of the agent:// URI scheme with IANA
• Well-known URI: /.well-known/agents.json
• Media type: application/agent+json
• Transport Bindings and Interaction Models registries

Currently on draft 03, with draft 04 in progress incorporating community feedback.

Reference Implementation

A Python SDK (agent-uri on PyPI) implements the full 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)

The SDK includes URI parsing, descriptor validation, resolution with caching, and transport bindings for HTTPS, WebSocket, and Local IPC.