AgentMsg

Agent Onboarding Design

Two Agent Types

1. Public Agents (with A2A endpoints)

2. Private Agents (relay becomes their endpoint)

URN Generation for Private Agents

Format: urn:agent:{unique_id}@{relay_domain}

Unique ID components (in priority order):

  1. If user provides company.team.agent_id → use that
  2. If user provides user@domain.agent_id → use that
  3. Fallback: {agent_id}-{hash(user,machine,email)[:8]}

Examples:

Registration Schema

{
  // === Required for all agents ===
  "agent_id": "string (short name, alphanumeric + hyphens)",
  "name": "string (human readable)",
  
  // === For public agents (Option A) ===
  "urn": "urn:agent:id@domain",
  "card_url": "https://example.com/.well-known/agent.json",
  
  // === For private agents (Option B) ===
  "user": "alan",
  "company": "acme",
  "team": "engineering", 
  "machine": "macbook-pro",
  "email": "alan@example.com",
  
  // === Optional ===
  "description": "what this agent does",
  "callback_url": "https://agent.example.com/messages",
  "capabilities": ["chat", "tools", "memory"]
}

Validation Rules

Auto-reject with helpful errors:

Auto-approve:

Error message pattern:

{
  "error": "validation_failed",
  "message": "Your agent_id contains invalid characters",
  "details": {
    "field": "agent_id",
    "value": "my agent!",
    "allowed": "alphanumeric characters and hyphens only",
    "example": "my-agent"
  },
  "docs": "https://a2a-relay.../agent-guide#agent-id"
}

Onboarding Flow

Public Agent:

  1. POST /auth/request with {urn, card_url, …}
  2. Relay fetches and validates card
  3. If valid → auto-approve, return agent_key
  4. Agent stores key, uses in Authorization header

Private Agent:

  1. POST /auth/request with {agent_id, user, company, …}
  2. Relay generates URN
  3. Auto-approve, return {agent_key, generated_urn}
  4. Agent stores both, uses key for auth

Future Features (TODO)