Metadata Layer: AgentFacts

The hero layer: dynamic, signed, verifiable trust + capability documents that evolve independently of the index.

What Are AgentFacts?

AgentFacts are structured, cryptographically signed metadata documents (JSON-LD format) that encapsulate an AI agent's dynamic state, declared capabilities, endpoints, and trust-related credentials. Each AgentFacts document is signed as a W3C Verifiable Credential (VC).

  • JSON-LD format: Self-describing with @context for forward-compatible schema evolution
  • Signed (VC-style): W3C Verifiable Credentials for cryptographic attestation
  • Contains: Capabilities, endpoints, auth methods, telemetry config, evaluations
  • Enables rapid updates: Without touching the index, supports frequent changes to capabilities, telemetry, or endpoints

Explore AgentFacts

Declared Capabilities

[
  {
    "type": "translation",
    "languages": [
      "en",
      "es",
      "fr"
    ],
    "streaming": true
  }
]

Index Stability vs. Metadata Evolution

Lean Index (Stable)

{
  "agent_id": "nanda:550e8400-e29b-41d4-a716-4466554400",
  "agent_name": "urn:agent:salesforce:starbucks",
  "primary_facts_url": "https://TranslationAssistant.salesforce.com/.agent-facts",
  "private_facts_url": "https://agentfactshost.com/550e8400-e29b-41d4-a716",
  "adaptive_resolver_url": "https://resolver.salesforce.com/dispatch/translation",
  "ttl": 3600,
  "signature": "ed25519:..."
}

AgentAddr stays stable (≤120 bytes, 1-6h TTL). Only changes when agent identity or hosting infrastructure fundamentally shifts.

AgentFacts (Dynamic)

{
  "capabilities": [
    {
      "type": "translation",
      "languages": [
        "en",
        "es",
        "fr"
      ],
      "streaming": true
    }
  ],
  "endpoints": {
    "static": [
      "https://api.salesforce.com/v1/translate"
    ],
    "rotating": [
      "https://east.salesforce.com/translate",
      "https://west.salesforce.com/translate"
    ]
  }
}

AgentFacts evolve rapidly (5-15min TTL). Capabilities, endpoints, and trust signals update without index writes.

Sub-Second Revocation

AgentFacts supports sub-second revocation through W3C Verifiable Credential Status Lists (VC-Status-List). When an agent is compromised or needs immediate revocation:

  1. Credential issuer updates the VC-Status-List
  2. Status list change propagates via CDN/edge cache invalidation
  3. Clients verify status during credential validation
  4. Revoked credentials are rejected in <1 second globally

Privacy Path: PrivateFactsURL

PrivateFactsURL enables privacy-preserving metadata resolution:

  • Requester anonymity: Agent domain is never contacted
  • Access decoupling: Metadata is publicly readable without invoking agent infrastructure
  • Audit independence: Metadata remains available even if agent hosting goes offline
AgentName → Index → AgentAddr → PrivateFactsURL → AgentFacts (metadata only)

Metadata Layer Across Rollout Stages

Intranet

Internal capabilities + internal trust domain. AgentFacts hosted at PrimaryFactsURL within enterprise infrastructure.

Extranet

Partner trust exchange + federation. Cross-signing between trust zones. Third-party credential validation.

Internet

Public claims + layered verification. AgentFacts hosted using CRDT-based distributed storage for privacy and censorship resistance.