AgentFacts Schema: Unified AI Agent Metadata

Updated 3 July 2026

AgentFacts Schema is a comprehensive standard that defines AI agent identity, capabilities, provenance, and operational state using structured, machine-verifiable formats.
It supports interoperability across enterprise, blockchain, and memory-driven systems with cryptographic validation and multi-authority endorsement.
The schema enables secure, scalable agent coordination through extensible modules for permissions, audit trails, and schema evolution.

AgentFacts Schema is a comprehensive, formalized metadata standard for representing, verifying, and integrating the identity, capabilities, provenance, and operational state of AI agents and agentic workflows across contemporary agent ecosystems, including enterprise, multi-agent, agentic memory, web, and blockchain-based deployments. The AgentFacts concept unifies the representation of agent "facts"—key properties and assertions—using structured, machine-verifiable formats, delivering strong guarantees for trust, discoverability, auditability, and schema-based reasoning (Grogan, 11 Jun 2025, Raskar et al., 18 Jul 2025, Liu, 24 Apr 2026, Gao et al., 24 Jun 2026, Petrov et al., 30 Apr 2026, Yao et al., 18 Jun 2026, Yuan et al., 15 Oct 2025). Derived and extended across several domains, AgentFacts achieves interoperability through typed schemas, cryptographic validation, multi-authority endorsement, and composable protocol extension.

1. Core Schema Structure and Variants

AgentFacts manifests as a schema-centric, extensible metadata container, typically realized in JSON, JSON-LD, or similar formats. Its structural backbone is a collection of field sets covering identity, capability, provenance, permissions, and domain-specific attributes. The universal superset version comprises at least ten primary categories, such as core identity (agent_id, name, version, timestamps), baseline model specifications (foundation_model, training data), classification (agent type, operational attributes), capability and interface declarations (APIs, protocols, supported modalities), authentication and permission scoping, compliance mappings (regulatory, audit, jurisdiction), performance and reputation (quantitative metrics and user feedback), supply chain traceability (component, dependency, and infrastructure lineage), cryptographic signatures and authority proofs, and extensibility hooks for custom facts or integrations (Grogan, 11 Jun 2025, Raskar et al., 18 Jul 2025).

Variant schemas appear across applications:

Enterprise/Registry/Internet: AgentFacts as registry entries, DID-linked documents, or NANDA index resolutions, all with verifiable, signed sections.
Agentic Memory and Knowledge: Schema-bound object definitions and extraction contracts, as in memory systems for persistent, queryable self-knowledge (Petrov et al., 30 Apr 2026, Yao et al., 18 Jun 2026).
Blockchain/Ethereum: ERC-8004 and similar, mapping on-chain agent NFTs, services, and reputational events to a normalized AgentFacts layout (Liu, 24 Apr 2026).
Data Exchange: Extension with Data Facts specifying datasets held or exposed by agents, referenceable via a data_facts_url, supporting audit and integrity guarantees (Gao et al., 24 Jun 2026).
Agentic Workflows: Schema describing table structure, agent-driven SQL template instantiation, and privacy compliance for tabular summarization (Yuan et al., 15 Oct 2025).

A canonical form in JSON is exemplified by the FinancialReportAgent record, which combines a globally unique identifier, versioning, detailed capability specs, cryptographic signatures by multiple authorities, and extensibility via custom fields (Grogan, 11 Jun 2025). Blockchain-derived schemas map these ideas into on-chain and off-chain segments (Liu, 24 Apr 2026).

2. Identity, Provenance, and Multi-Authority Verification

AgentFacts encodes strong agent identity via globally unique IDs (DIDs, urn:agent:, integer ids), version markers, creation/update timestamps, and identity provider fields. For provenance and governance, all fields or field subtrees are cryptographically signed, allowing for multi-authority attestation. Each authority signs only the sections it verifies; this signature structure is modular and supports threshold (t-of-n) and aggregate signature verification (Grogan, 11 Jun 2025, Raskar et al., 18 Jul 2025). The effect is distributed trust, with no central point of failure and graduated confidence: signatures over critical fields are tracked (e.g., compliance, baseline model), with verification policies specifying required coverage and minimum authority counts for document validity (see formal rules in (Grogan, 11 Jun 2025)).

All signatures are executed over hash digests of canonically encoded section data:

$\sigma_i = \mathrm{Sign}_{sk_i}(H(M_i)),$

where $M_i$ is the set of metadata fields attested by authority $A_i$ . Signature blocks are attached per-section or, in some W3C VC-based flows, over the full document, distributing assurance horizontally over the data (Raskar et al., 18 Jul 2025).

3. Capability, Interface, and Extension Modeling

The AgentFacts schema records agent capabilities—programmatic APIs, supported protocols (OpenAPI, GraphQL, MCP, A2A, etc.), input/output modalities (text, audio, streaming, batch), authentication methods (OAuth2, JWT, mTLS), and domain expertise. Capability fields are formalized for machine-readability and sometimes parameterized for dynamic invocation. Extensions, such as Data Facts, encode dataset-level metadata (identity, endpoint, access scope, integrity proofs) and are linked into agent records using fields like data_facts_url, ensuring separation between agent description and data asset specification (Gao et al., 24 Jun 2026). Custom extensions for domain- or application-specific facts are inserted via extensibility hooks or schema extensions, usually under a custom_facts or analogous field.

A distinguishing feature, especially in agentic memory or workflow settings, is the schema-first constraint: agent capabilities and state must be grounded in a typed schema. This enables constrained query, verifiable memory mutations, and deters free-text or model-based inference for fields marked as unknown or null (Petrov et al., 30 Apr 2026, Yao et al., 18 Jun 2026). Schema-bound contracts are critical for “negative queries,” joins over relations, and for ensuring reliable operations under strict audit requirements.

4. Permissioning, State, and Audit

Dynamic permission management is intrinsic to AgentFacts metadata. Permissions are not mere static claims but are represented with expiration (TTL), escalation policy, signed authority, and full modification trace (audit trail). The permission set $P_t$ at time $t$ evolves via deterministic transition functions driven by grant/revoke/escalate events:

$P_{t+1} = \delta(P_t, e),$

with formal inference rules enforcing time-bounded access:

$(a, r) \in P_t \wedge t < \mathrm{ttl}_{perm} \implies \text{Permit}(a, r, t) = \mathrm{true}.$

These permissions map to RBAC/ABAC policies in backend infrastructure, ensuring end-to-end compliance and visibility (Grogan, 11 Jun 2025). Security-critical extensions (e.g., in Data Facts) implement three-layer pipelines (JWT authentication, capability-scoped gateway filtering, delegated A2A flows), achieving 100% adversarial block rate, zero data leakage, and strict runtime check latencies (Gao et al., 24 Jun 2026).

5. Schema Evolution, CRDTs, and Update Protocols

AgentFacts supports collaborative, concurrent evolution via a CRDT (Conflict-free Replicated Data Type) protocol, notably utilizing OR-set and LWW-register structures for multi-valued fields. For example, new endpoints or skills are merged across replicas, supporting decentralized federation without loss of information:

$(A_1, R_1) \sqcup (A_2, R_2) = (A_1 \cup A_2, R_1 \cup R_2),$

where $A$ and $R$ are addition and removal sets, and the value set at any replica is $M_i$ 0 (Raskar et al., 18 Jul 2025). This guarantees strong eventual consistency for all non-singleton fields. For singleton fields (e.g., schema version), a timestamped LWW-register (last-write-wins) is used.

Short-lived TTLs and revocation status-lists (VC-Status) enable rapid key rotation and sub-second credential revocation. Consumers periodically fetch and verify the freshest AgentFacts (and Data Facts, if applicable), reloading after each expiry cycle. In NANDA/NANDini and blockchain index flows, lean “AgentAddr” records index into full AgentFacts metadata, allowing quilt-like, horizontally scalable lookup (Raskar et al., 18 Jul 2025, Gao et al., 24 Jun 2026).

6. Application Domains and Empirical Results

AgentFacts and descendants underpin a diverse range of system architectures:

Enterprise Governance and AI Workforce Management: Providing "nutrition label"-style metadata for procurement, compliance, and orchestration in regulated or large-scale agent deployments, including CI/CD integration and registry-less DID discovery (Grogan, 11 Jun 2025).
Internet-scale Agent Discovery: AgentFacts as the basis for rapid, verifiable endpoint lookup (NANDA index), supporting adaptive routing, zero-trust access, and privacy-preserving queries. Guarantees include <1 s global resolution, instant revocation, and schema-validated capability assertions (Raskar et al., 18 Jul 2025).
Blockchain and Decentralized Trust: ERC-8004-derived AgentFacts encode on-chain agent identity, ownership, service endpoints, reputation feedback, and cross-chain registration, mapping to the agentic Web3 economy (Liu, 24 Apr 2026).
Memory and Knowledge Extraction: Schema-grounded “facts” serve as the atomic units in persistent memory systems, supporting accurate, high-F1 retrieval, explicit unknowns, stateful update, and episodic aggregation (Petrov et al., 30 Apr 2026, Yao et al., 18 Jun 2026).
Data and Table Summarization: FACTS/AgentFacts encode table schemas and agentic template workflows for offline, privacy-preserving SQL/Jinja2-based summaries, with 100% SQL pass rate and wall-clock speedups linear in table count (Yuan et al., 15 Oct 2025).
Multi-Agent Data Exchange: AgentFacts + Data Facts deliver structured data discovery, tiered access, 100% integrity check detection (SHA-256), and 76.6% stale-data error reduction with TTL. Security pipelines block all forgeries in empirical testing (Gao et al., 24 Jun 2026).

Empirical metrics in these domains span micro-F1, pass rates, query latency, revocation latencies, corruption detection, and decision accuracy, with multi-agent studies specifically demonstrating 100% accuracy uplift in data-informed settings over self-decide baselines (Gao et al., 24 Jun 2026).

7. Best Practices, Extensions, and Future Directions

Best practices for AgentFacts include schema-first design, minimal registry bloat (use of URLs for external metadata), capability-scoped signing, audit logging of permission changes, negative-value handling (explicit nulls), and validation-driven iteration at every ingestion and query stage (Grogan, 11 Jun 2025, Gao et al., 24 Jun 2026, Petrov et al., 30 Apr 2026). Extension guidelines recommend keeping Data Facts and similar metadata documents lightweight, using pointers from AgentFacts, and adopting W3C DCAT/PROV lineage for broad data governance compatibility (Gao et al., 24 Jun 2026).

Planned evolutions involve richer audience binding, revocation registries, dataset catalogs, deep integration with knowledge distillation markets, and extensible storage of derived artifacts (e.g., embeddings, aggregates, distilled facts) with explicit provenance. In memory systems, migration scripts and schema versioning routines are recommended for safe evolution and backward compatibility (Petrov et al., 30 Apr 2026).

AgentFacts, across all contemporary research and application variants, offers a universal substrate for verified, composable, schema-rich agent descriptions, enabling scalable, auditable, and automation-ready agent coordination in both traditional and decentralized ecosystems.

References: