Agent URI Reference Implementation
This repository contains a reference implementation of the agent:// protocol as defined in the protocol specification.
Overview
The agent:// protocol is a URI-based framework 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).
This reference implementation provides a complete implementation of the protocol, including:
- URI parsing and validation
- Agent descriptor handling
- Resolution framework
- Transport bindings (HTTPS, WebSocket, Local)
- Security implementations
- Client and server SDKs
- Integration with other protocols (Agent2Agent, MCP)
- Example implementations and tools
Architecture
The implementation follows a modular, layered architecture:
agent-uri/
├── README.md # Project overview, setup instructions
├── pyproject.toml # Modern Poetry-based build configuration
├── Makefile # Development commands and workflows
├── agent_uri/ # Unified Python package
│ ├── __init__.py # Package initialization and public API
│ ├── parser.py # URI parsing and validation
│ ├── descriptor/ # Agent descriptor handling
│ │ ├── models.py # Data models for agent descriptors
│ │ ├── parser.py # Descriptor parsing and validation
│ │ ├── validator.py # Schema validation
│ │ └── compatibility.py # Agent Card compatibility layer
│ ├── resolver/ # Resolution framework
│ │ ├── resolver.py # Agent resolution logic
│ │ └── cache.py # Caching mechanisms
│ ├── transport/ # Transport bindings
│ │ ├── base.py # Abstract transport interface
│ │ ├── registry.py # Transport registry
│ │ └── transports/ # Transport implementations
│ │ ├── https.py # HTTPS transport
│ │ ├── websocket.py # WebSocket transport
│ │ └── local.py # Local/direct transport
│ ├── client.py # Client SDK for agent communication
│ ├── server.py # Server SDK for agent hosting
│ ├── capability.py # Capability framework and decorators
│ ├── auth.py # Authentication and authorization
│ ├── cli.py # Command-line interface
│ └── common/ # Shared utilities and types
│ └── error/ # Error handling framework
├── docs/ # Documentation
│ ├── rfc/ # RFC documents and specifications
│ ├── spec/ # Technical specifications
│ └── examples.md # Usage examples and tutorials
├── examples/ # Example implementations
│ └── echo-agent/ # Echo agent demonstration
└── scripts/ # Development and build scripts
Installation
Install from PyPI:
pip install agent-uri
Or install from source:
git clone https://github.com/agent-uri/agent-uri.git
cd agent-uri
make install-dev
Quick Start
Parsing Agent URIs
from agent_uri import parse_agent_uri
# Parse a basic agent URI
uri = parse_agent_uri("agent://example.com/my-agent")
print(f"Host: {uri.host}, Path: {uri.path}")
# Parse with protocol and capability
uri = parse_agent_uri("agent+https://api.example.com/agents/assistant/chat")
print(f"Protocol: {uri.protocol}, Capability: {uri.capability}")
Creating an Agent Server
from agent_uri import FastAPIAgentServer, capability
@capability(
name="echo",
description="Echo back the input message",
version="1.0.0"
)
async def echo_handler(message: str) -> dict:
return {"response": f"Echo: {message}"}
# Create and configure server
server = FastAPIAgentServer(
name="my-agent",
version="1.0.0",
description="A simple echo agent"
)
server.register_capability("echo", echo_handler)
# Run the server
if __name__ == "__main__":
server.run(host="0.0.0.0", port=8000)
Using the Agent Client
from agent_uri import AgentClient
# Connect to an agent
client = AgentClient("agent+https://api.example.com/my-agent")
# Invoke a capability
result = await client.invoke("echo", {"message": "Hello, World!"})
print(result["response"]) # "Echo: Hello, World!"
Development
This project uses Poetry and uv for dependency management:
# Install development dependencies
make install-dev
# Run tests
make test-all
# Run linting and formatting
make lint
make format
# Run type checking
make type-check
# Run security checks
make security
See the Makefile for all available commands.
Documentation
License
Metadata
Release files for agent-uri 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_uri-0.3.0.tar.gz | 128.7 kB | Without provenance | Details for agent_uri-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_uri-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for agent_uri-0.3.0-py3-none-any.whl |
Total release size: 289.5 kB
Release files / agent_uri-0.3.0.tar.gz
| Download URL | agent_uri-0.3.0.tar.gz |
|---|---|
| Size | 128.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a8ef879bd8f35117a771f2f1e2c4c814a28653118b04fca04ba3b3db1eefa7aa
|
|
BLAKE2b-256 checksum How to use checksums |
3489072ce78652878e52363050556abefad0d2f0825e1c978f64b30f3f14bb5a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Release files / agent_uri-0.3.0-py3-none-any.whl
| Download URL | agent_uri-0.3.0-py3-none-any.whl |
|---|---|
| Size | 160.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
51b1744be323001b7c9a8b62ee634f0ab3baede1e0c2d8568fcd74730b3d006f
|
|
BLAKE2b-256 checksum How to use checksums |
1744bf59df8f9189157255100b3ac50f9e80168f494ae2fa72b350066411bd26
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Security for agent-uri 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.