agent:// Protocol

The agent:// URI scheme provides unique identity for AI agents.

URI Scheme

The agent URI follows this format:

agent://name

Where name must:

• Start with a letter (a-zA-Z)
• Contain only alphanumeric characters, hyphens, or underscores
• Be 1-63 characters long
• Be globally unique (registered in DNS)

Valid Examples

agent://alice
agent://search-engine
agent://my_agent_v2
agent://GPT4Assistant

Invalid Examples

agent://123invalid     # Cannot start with number
agent://my agent       # No spaces allowed
agent://-invalid       # Cannot start with hyphen
agent://a             # Too short (min 1 char is ok, but registration requires 3+)

Identity Components

Each agent identity consists of:

1. Name

The unique identifier in the agent:// URI:

const agent = createAgent('alice');
console.log(agent.getURI());
// Output: agent://alice

2. Public Key

An Ed25519 public key for authentication:

const identity = agent.getIdentity();
console.log(identity.publicKey);
// Output: "sLCkXG4FN7N4gH5K..." (base64-encoded)

3. Endpoint

The HTTPS URL where the agent listens:

console.log(agent.getEndpoint('example.com'));
// Output: https://example.com:8443

4. Capabilities

Features the agent supports:

const agent = createAgent('alice', {
  capabilities: ['messaging', 'streaming', 'file-transfer']
});

URI Resolution

The agent:// URI is resolved to an endpoint via DNS:

agent://search
     │
     ├─ DNS Lookup ─────▶ 185.204.169.26:3000
     │                    
     └─ Returns: {
           name: "search",
           publicKey: "sLCkXG4FN7N4gH5K...",
           endpoint: "https://search.agenium.net:8443",
           capabilities: ["messaging", "streaming"]
        }

Protocol Versions

AGENIUM uses semantic versioning for protocol compatibility:

const PROTOCOL_VERSION = '1.0';

During handshake, agents negotiate the highest common version:

// Alice supports v1.0, v1.1
// Bob supports v1.0
// Negotiated: v1.0

Identity Verification

Public key pinning ensures you're talking to the right agent:

1. DNS Resolution

const result = await resolver.resolve('agent://bob');
// Returns: { publicKey: "xyz123..." }

2. Handshake Verification

// During handshake, verify public key matches DNS record
if (handshakeResponse.agentId.publicKey !== resolvedAgent.publicKey) {
  throw new Error('Public key mismatch!');
}

3. Certificate Pinning

// TLS certificate must match agent's public key
const cert = createAgentCert(name, publicKey, ca);

URI Utilities

AGENIUM provides utilities for working with agent URIs:

Parsing

import { parseAgentURI } from 'agenium';

const parsed = parseAgentURI('agent://alice');
console.log(parsed);
// Output: { name: 'alice' }

Validation

import { isValidAgentURI, validateAgentName } from 'agenium';

console.log(isValidAgentURI('agent://alice'));      // true
console.log(isValidAgentURI('https://alice.com'));  // false

console.log(validateAgentName('alice'));    // true
console.log(validateAgentName('123abc'));   // false

Construction

import { toAgentURI } from 'agenium';

const uri = toAgentURI('alice');
console.log(uri);
// Output: agent://alice

Registration

To use an agent URI in production, register it in the marketplace:

1. Choose a Name

# Check availability (via marketplace web UI)
agent://myagent

2. Generate Keys

const agent = createAgent('myagent');
const identity = agent.getIdentity();

console.log('Public Key:', identity.publicKey);
// Save this for registration

3. Register via Marketplace

1. Visit marketplace.agenium.net
2. Enter desired name: myagent
3. Provide public key
4. Complete TON payment
5. Receive API key

4. Configure DNS

The marketplace automatically configures DNS:

{
  "name": "myagent",
  "publicKey": "sLCkXG4FN7N4gH5K...",
  "endpoint": "https://your-server.com:8443",
  "capabilities": ["messaging"],
  "protocolVersions": ["1.0"],
  "ttl": 3600
}

Best Practices

Naming

• Use descriptive names: search-engine not se
• Avoid version numbers: myagent not myagent-v2 (use capabilities instead)
• Keep it short: Easier to type and remember
• Use hyphens for readability: weather-forecast not weatherforecast

Security

• Never share private keys: Only share public keys
• Rotate keys periodically: Update DNS records when changing keys
• Verify public keys: Always check DNS-returned keys during handshake
• Use strong entropy: Let AGENIUM generate keys (Ed25519)

Availability

• Use static IPs: Easier DNS management
• Set appropriate TTL: Balance caching vs. flexibility (3600s recommended)
• Monitor uptime: DNS assumes your endpoint is reachable
• Graceful failover: Update DNS when migrating servers

See Also

• DNS Resolution - How agent URIs are resolved
• Transport Layer - How agents connect after resolution
• Marketplace - Registering your agent URI