AgentFacts

AgentFacts are rich metadata documents that describe an AI agent's identity, capabilities, and trust profile. They complement the lean AgentAddr index records (~120 bytes) with detailed, verifiable information encoded as W3C Verifiable Credentials.

AgentAddr vs AgentFacts AgentAddr is the minimum discovery record (ID, URL, protocol, capability summary). AgentFacts is the full metadata dossier — skills, trust scores, compliance, and more — cryptographically signed and independently verifiable.

API Endpoints

GET /agentfacts/:id

Retrieve the AgentFacts document for a given agent ID. Returns 404 if no facts are stored.

PUT /agentfacts/:id

Store or update the AgentFacts document for an agent. The agent must already be registered.

Document Structure

An AgentFacts document is a JSON-LD object that includes:

🆔 Identity

Agent ID, DID (Decentralized Identifier), display name, description, and the agent's primary and API endpoint URLs.

🧠 Skills & Capabilities

Structured list of capabilities (e.g., text-generation, code-review, data-analysis) with optional confidence scores and supported input/output modes.

⭐ Trust Profile

Trust scores computed via Wilson confidence intervals from multi-trial capability evaluations. Includes overall trust score, per-capability scores, and evaluation history.

Compliance Attestations

Declarations of compliance with governance policies — data handling rules, PII protections, regional routing constraints, and operational limits.

Cryptographic Proof

EdDSA (Ed25519) proof block making the entire document a W3C Verifiable Credential — independently verifiable by any party with the public key.

W3C VC Encoding

AgentFacts are encoded as W3C Verifiable Credentials with the following structure:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://nanda.nexartis.com/contexts/agentfacts/v1"
  ],
  "type": ["VerifiableCredential", "AgentFactsCredential"],
  "issuer": "https://nanda.nexartis.com",
  "issuanceDate": "2026-02-19T12:00:00Z",
  "credentialSubject": {
    "id": "did:nanda:my-agent",
    "type": "AgentFacts",
    "skills": ["text-generation", "summarization"],
    "trustScore": 0.87
  },
  "proof": { "..." }
}

Validation Rules

  • The agent_id in the facts document must match an existing registered agent
  • The credentialSubject.id should reference the agent's DID
  • Capability names should follow a lowercase hyphenated convention (e.g., text-generation)
  • Trust scores are decimal values between 0.0 and 1.0
  • The proof block is generated server-side using the node's latest Ed25519 key

Relationship to the NANDA Index

The NANDA Index stores AgentAddr records for fast global lookup. When a client discovers an agent via the index, they can fetch the full AgentFacts from the agent's home registry for detailed evaluation before interaction.

References

See also Trust & Security for credential signing and revocation · API Reference for endpoint details · NANDA Overview for the full architecture
Related reading AgentFacts: The Agent Nutrition Label — the design rationale behind AgentFacts · Agent Identity — how identity and metadata fit into the Agentic Web

Coming Soon

By Invitation Only