agent-uri

Portable agent identity for multi-agent systems

Multi-agent systems conflate identity with location. When an agent at https://agents.acme.com/approver migrates to a new cloud provider, the URL changes, and every workflow referencing that agent breaks. The agent's identity was its address.

The agent:// URI scheme separates identity from topology through three orthogonal components:

agent://acme.com/workflow/approval/agent_01h8xyz...
       └─────┬────┘└─────┬───────┘└──────┬──────┘
        trust root   capability    unique ID
                       path

• Trust root: The organization vouching for the agent (acme.com)
• Capability path: What the agent does (/workflow/approval)
• Unique ID: Stable reference across migrations (agent_01h8xyz...)

This repository contains the formal specification and evaluation tooling that validates the scheme against 513 production tools from major agent frameworks.

Rust implementation: agent-uri-rs

Quick Start

Run the evaluation corpus extraction:

cd evals/corpus-extraction
uv sync
uv run python scripts/extract_all.py
uv run python scripts/merge_corpus.py

Output appears in data/processed/unified_corpus.json.

Evaluation Results

The capability path grammar achieves complete coverage with minimal collision:

Framework	Tools	Notes
LangChain	163	langchain_community.tools introspection
CrewAI	107	crewai-tools introspection
MCP Official	79	TypeScript parsing of official servers
MCP Community	varies	Community MCP servers
AutoGen	12	Microsoft AutoGen tools
Smolagents	8	HuggingFace agent primitives
Total	513

Expressiveness: 100% of tools map to valid capability paths

Collision rate: ~1% (508 unique names across 513 tools)

Discovery precision: F1 = 1.0 for both prefix and exact matching (10,000 simulated agents, 1,000 queries)

These results validate that the hierarchical capability grammar represents real-world agent capabilities without namespace conflicts.

The Paper

Read the paper: arXiv:2601.14567

The paper/ directory contains the LaTeX source:

• Problem: Current agent identity schemes bind agents to network locations
• Solution: Three-component URI with trust root, capability path, and unique ID
• Proofs: Identity stability under migration, O(log N) resolution complexity
• Performance: All resolution operations under 5 microseconds

Build the PDF

cd paper
make

Requires pdflatex and bibtex.

Repository Structure

agent-uri/
├── paper/                    # Formal specification (LaTeX)
│   ├── main.tex             # Full paper with proofs
│   ├── references.bib       # Bibliography (50+ citations)
│   └── Makefile             # Build system
└── evals/
    ├── corpus-extraction/   # Python tooling for capability analysis
    │   ├── scripts/         # Per-framework extractors
    │   ├── data/            # Raw and processed corpora
    │   └── pyproject.toml   # Dependencies
    └── results/             # Evaluation outputs
        ├── eval1_expressiveness.json
        └── eval2_discovery.json

Detailed Usage

Extract All Frameworks

uv run python scripts/extract_all.py

Runs extractors for LangChain, smolagents, MCP (official and community), CrewAI, AutoGen, and generates synthetic collision tests. Results appear in data/raw/.

Merge to Unified Corpus

uv run python scripts/merge_corpus.py

Produces data/processed/unified_corpus.json with collision analysis.

Extract Individual Frameworks

uv run python scripts/extract_langchain.py
uv run python scripts/extract_smolagents.py
uv run python scripts/extract_mcp.py
uv run python scripts/extract_mcp_community.py [max_repos]
uv run python scripts/extract_crewai.py
uv run python scripts/extract_autogen.py
uv run python scripts/generate_synthetic_tools.py

Requirements and Installation

• Python 3.11+
• uv package manager
• gh CLI (authenticated) for MCP community extraction
• LaTeX distribution with pdflatex (for building the paper)

cd evals/corpus-extraction
uv sync

Output Format

The unified corpus JSON contains tool metadata and collision analysis:

{
  "metadata": {
    "total_tools": 513,
    "unique_names": 508,
    "collision_rate": 0.01,
    "sources": { ... }
  },
  "tools": [
    {
      "name": "gmail_search",
      "description": "Search Gmail messages",
      "source": "langchain_community.tools",
      "category": "gmail",
      "parameters": [ ... ]
    }
  ],
  "collisions": {
    "names_with_collisions": ["search", ...],
    "collision_details": { ... }
  }
}

Contributing

Contributions welcome. Priority areas:

1. Additional framework extractors: Semantic Kernel, OpenAI function registry
2. Mapping pipeline: Tool-to-capability-path conversion
3. Discovery simulation: DHT-based resolution benchmarks

License

See individual component licenses in subdirectories.

Citation

@misc{agent-uri-2025,
  title={The agent:// URI Scheme: Portable Identity for Multi-Agent Systems},
  author={...},
  year={2025},
  eprint={2601.14567},
  archivePrefix={arXiv},
  primaryClass={cs.MA}
}

See arXiv:2601.14567 for the full paper.