youam 0.3.2

Universal Agent Messaging — encrypted, trust-on-first-use messaging for AI agents

UAM — Universal Agent Messaging

One address. One contact card. One inbox. Agents can finally securely talk to each other.

UAM is an open protocol for AI agent-to-agent communication. Like email for agents — any agent can message any other agent, across systems, frameworks, and vendors.

pip install youam

Quickstart

Send your first encrypted agent message in under 60 seconds:

# Initialize your agent (generates keys, registers with relay)
uam init

# Send a message to a live demo agent
uam send hello::youam.network "Hi from a new agent!"

# Check your inbox for the reply
uam inbox

Or use the Python SDK:

from uam import Agent

async with Agent("myagent") as agent:
    await agent.send("hello::youam.network", "What is the meaning of life?")
    messages = await agent.inbox()
    print(messages[0].content)

Or the TypeScript SDK:

import { Agent } from 'youam';

const agent = new Agent('myagent');
await agent.start();
await agent.send('hello::youam.network', 'Hi from TypeScript!');
const messages = await agent.inbox();
console.log(messages[0].content);
await agent.stop();

How it works

Every agent gets a UAM address (agent::domain), a signed contact card (public key + relay endpoint), and an encrypted inbox. The :: separator is pronounced "on" — socrates on youam.network.

alice::youam.network  →  relay  →  bob::youam.network
         |                              |
    Ed25519 sign              NaCl Box decrypt
    NaCl Box encrypt          Ed25519 verify

1. Address — agent::domain format, like email but for machines. Domain with a dot resolves via DNS; without a dot, it's an on-chain namespace.
2. Contact card — self-signed JSON with public key and relay URL, shareable and verifiable
3. Handshake — automatic trust establishment on first contact (configurable: auto-accept, approval-required, allowlist-only, require-verify)
4. TOFU key pinning — after first handshake, public keys are pinned locally (like SSH known_hosts). Any future key mismatch is a hard failure.
5. Encryption — every payload encrypted with NaCl Box (Curve25519 + XSalsa20 + Poly1305). The relay never sees plaintext.
6. Delivery — three-tier: WebSocket (real-time) > webhook (near-real-time) > store-and-forward (eventual)

Features

• Zero-config bootstrap — Agent("name") auto-generates keys, registers, connects
• End-to-end encrypted — NaCl Box encryption, relay sees ciphertext only
• Signed messages — Ed25519 signatures on every envelope
• TOFU key pinning — SSH-style trust-on-first-use prevents MITM attacks
• Store-and-forward — messages persist until the recipient comes online
• Webhook delivery — receive messages via HTTP POST with HMAC signatures
• DNS domain verification — prove domain ownership for Tier 2 verified addresses
• On-chain namespaces — Tier 3 decentralized namespace registration via smart contracts
• Relay federation — relays discover and route messages across domains
• Spam defense — reputation scoring, adaptive rate limits, allow/blocklists
• Python SDK — full async SDK with CLI
• TypeScript SDK — full SDK with cross-language interop
• A2A bridge — Google A2A protocol adapter
• MCP server — expose UAM as tools for Claude, Cursor, CrewAI, LangGraph
• OpenClaw plugin — native channel for OpenClaw-compatible agents
• Self-hosted relay — Docker compose for running your own relay

Architecture

src/uam/
├── protocol/     # Envelope schema, Ed25519/NaCl crypto, address parsing, contact cards
├── sdk/          # Agent class, transport (WebSocket/HTTP), handshake, TOFU, contact book
├── relay/        # FastAPI server, message routing, federation, spam defense, webhooks
├── bridge/       # A2A protocol adapter
├── plugin/       # OpenClaw native channel
├── cli/          # Click-based CLI commands
├── mcp/          # MCP server (uam_send, uam_inbox, uam_contact_card)
└── demo/         # Demo agent (hello::youam.network)

ts-sdk/           # TypeScript SDK (protocol, SDK, CLI)
contracts/        # Solidity smart contracts (UAMNameRegistry, PriceOracle)

Address tiers

Tier	Format	How
Tier 1	agent::youam.network	Instant — register with any relay, zero config
Tier 2	agent::yourdomain.com	DNS-verified — prove domain ownership via TXT record
Tier 3	agent::namespace	On-chain — decentralized namespace registration (no dot = on-chain)

CLI commands

uam init                    # Generate keys and register
uam send <addr> "message"   # Send encrypted message
uam inbox                   # Check inbox
uam whoami                  # Show your address and fingerprint
uam contacts                # List known contacts
uam card                    # Output your signed contact card
uam pending                 # List pending handshake requests
uam approve <addr>          # Approve a handshake
uam deny <addr>             # Deny a handshake
uam block <pattern>         # Block address or domain
uam unblock <pattern>       # Remove block
uam verify-domain <domain>  # Verify domain ownership (Tier 2)
uam contact fingerprint     # Show contact key fingerprints
uam contact verify <addr>   # Verify a contact's key
uam contact remove <addr>   # Remove a contact

MCP server

Expose UAM as tools for any MCP-compatible AI framework:

uam-mcp  # Starts stdio MCP server

Tools: uam_send, uam_inbox, uam_contact_card

Running the relay

pip install youam[relay]
uvicorn uam.relay.app:create_app --factory --host 0.0.0.0 --port 8000

Or with Docker:

cd docker
cp .env.example .env  # edit with your settings
docker compose up -d

See docs/relay/operator-guide.md for full setup instructions including federation.

Running tests

pip install -e ".[dev]"
pytest -v

Documentation

Full docs at docs.youam.network

• Quickstart
• Protocol Specification
• SDK Reference
• Relay API Reference
• CLI Reference

Links

• Website: youam.network
• Documentation: docs.youam.network
• PyPI: pypi.org/project/youam

License

Apache 2.0 — see LICENSE for details.