Gateway Capability Directory and Synchronization for Internet of Agents

As agent systems become increasingly distributed across heterogeneous networks and administrative domains, gateways need a control-plane representation of capability information. A gateway cannot rely only on transient advertisements, static endpoint bindings, or local capability representations if it is expected to support capability visibility, semantic resolution, policy enforcement, and interconnection. At the same time, adjacent work is separating discovery from other interoperability layers. DAWN is focusing on discovery problem statements, terminology, and requirements, while explicitly excluding registration processes, capability negotiation, task orchestration, and agent-to-agent communication protocols . This leaves DMSC-specific work on the gateway-side capability directory that supports registration, synchronization, validation, and handoff to collaboration protocols. This document describes a framework for gateway capability directories and synchronization in IoA. It focuses on what information a gateway-managed directory entry needs to contain, how that information is derived and maintained, how much of it can be synchronized across gateways, and what validation and provenance guarantees are required before the information can be used by routing, task invocation, or other collaboration functions.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in and . The following terms are used in this document: Agent Capability Specification (ACS): A gateway-managed, structured capability description associated with an Agent Identity Code (AIC) and constrained by local authorization and policy. Capability Digest: A gateway-generated summary derived from one or more ACS objects, intended for inter-gateway visibility and synchronization rather than full capability disclosure. Directory Entry: A versioned object stored or managed by a gateway capability directory. A directory entry MAY contain a full ACS, a derived digest, or related validation metadata. Handoff Reference: Information returned by a gateway that enables a subsequent interaction, invocation, or session establishment step. Source Description: An externally or internally supplied capability description that a gateway can ingest, normalize, or constrain. Examples include an A2A Agent Card, a local registration payload, or an operator-managed descriptor. Freshness: The degree to which synchronized or cached information is still valid for operational use. Provenance: Evidence indicating where a directory entry originated, how it was transformed, and what authority or gateway asserted it.

This document specifies: - A common framework for gateway capability directory objects in IoA deployments. - Requirements for ACS objects, capability digests, and directory entry lifecycle. - Requirements for synchronization, freshness, provenance, and validation across gateways. - The relationship between gateway-managed ACS objects and externally published descriptions such as the A2A Agent Card. This document does not specify: - A discovery query protocol, query syntax, ranking algorithm, or candidate selection policy. - A naming system, global identifier resolution protocol, or generic registry architecture for all entities. - Agent-to-gateway advertisement messages, intent submission messages, candidate-list response messages, routing-feedback messages, or other wire-format exchanges of an intent-routing protocol. - Task orchestration, session establishment, or agent-to-agent message exchange procedures. - A domain-specific ontology or a full semantic negotiation protocol, although semantic hooks MAY be carried by directory objects. - A complete identity framework, trust framework, or credential issuance system.

Within DMSC architecture, the capability directory is a gateway-side control-plane function. It receives or derives capability descriptions during onboarding, associates them with an AIC and authorized operational scope, maintains local directory entries, and exposes suitable information to other DMSC functions such as semantic resolution, task-based invocation, and inter-gateway visibility . The capability directory sits between registration/authorization and collaboration/runtime procedures, as illustrated in Figure 1.

Figure 1: Capability Directory Position A gateway capability directory manages directory entries. A directory entry may carry a full ACS, a derived Capability Digest, or related validation metadata, depending on local use and disclosure scope. This position is consistent with the MACP view that registration, capability synchronization, semantic resolution, and task coordination are related but distinct stages of the collaboration lifecycle . It is also consistent with the ACPs architecture, where agent onboarding publishes capability information and discovery functions use indexed capability data without redefining the underlying onboarding or inter-agent communication procedures . The relationship to existing DMSC work is as follows: - MACP introduces ACS and CDSP as protocol-suite building blocks. This document refines the common object model, lifecycle expectations, synchronization metadata, and validation requirements those building blocks need . - ACPs Architecture defines the functional decomposition around onboarding, description management, discovery, and interconnection. This document focuses on the capability-directory objects exchanged and maintained across those functions . - Gateway Requirements identifies delegated discovery, ID-based resolution, and task-based searching as gateway functions. This document does not redefine those functions; it defines the directory substrate they depend on . - IoA Task Protocol identifies distributed registration/discovery and semantic alignment as future enhancement directions. This document provides a control-plane basis that such task-level procedures can use . - The IoA semantic interaction draft defines ontology-based semantic profiles, ontology identifiers and versions, and alignment-related information for interoperable meaning across domains. This document does not redefine those semantics; it provides the gateway directory substrate that can carry or reference such semantic hooks inside ACS objects and capability digests . - IAIP defines gateway-facing protocol behavior for capability advertisement, intent submission, candidate matching, routing decisions, and related message formats. This document is intended to be lower-layer and complementary: it defines what the gateway stores, validates, and synchronizes, while IAIP-like protocols can define how agents advertise capabilities to the gateway, how intents are submitted, and how candidates are selected and forwarded . Accordingly, this document does not define discovery query syntax or routing algorithms. Instead, the capability directory defined here is intended to support other DMSC functions as follows: - semantic resolution procedures MAY use ACS or digest content as inputs to capability matching and route preparation; - task-based invocation procedures MAY use handoff references and capability constraints derived from ACS content; - gateway policy enforcement MAY use lifecycle state, provenance, and local constraints stored with the directory entry; and - semantic interoperability procedures MAY use optional ontology or semantic-profile hooks carried by ACS content without redefining the semantic layer itself.

A gateway capability directory can ingest or reference externally supplied descriptions. Such external descriptions MAY be published by an agent endpoint, a management system, or another authoritative source. They are treated by this document as source descriptions rather than as gateway-native directory objects. A2A defines the Agent Card as one example of such an external description. The Agent Card is a self-describing object published by an agent endpoint for discovery and interaction setup, and includes information such as identity, skills, supported interfaces, security requirements, and other public metadata . An ACS is not the same object as an external description such as an A2A Agent Card. The relationship is as follows: - An external description is typically published by or on behalf of an agent endpoint or management source. An ACS is managed by a DMSC Gateway. - An external description is a source description intended for publication or exchange. An ACS is a normalized, policy-constrained directory object used by DMSC infrastructure. - An external description can describe what an agent claims or offers. An ACS represents what the gateway has accepted, authorized, and organized for directory use. - A Capability Digest is a further abstraction derived from ACS content for inter-gateway visibility. A gateway MAY ingest an A2A Agent Card as one source description when constructing an ACS. However, the gateway MUST NOT assume that all externally supplied description content is suitable for directory synchronization or operational use without local validation and policy application. When an ACS is derived from an external description such as an A2A Agent Card, the gateway SHOULD preserve provenance indicating: - the source Agent Card identifier or retrieval location; - the time of ingestion or last confirmation; - any fields removed, transformed, or constrained during normalization; and - the local policy or authorization basis under which the ACS was accepted.

An ACS is the primary full directory object. An ACS MUST be bound to a single AIC or equivalent local agent identity reference. An ACS SHOULD be sufficient for local directory use, semantic resolution input, handoff preparation, and policy evaluation. An ACS SHOULD contain at least: - a stable local identifier for the ACS entry; - the bound AIC or equivalent identity reference; - one or more capability references; - input/output or modality references relevant to invocation and compatibility; - interface binding references and handoff references, if available; - local status and version information; - provenance and integrity metadata; and - optional semantic hooks such as ontology identifier, ontology version, or semantic-profile reference. An ACS MAY additionally carry local policy constraints, region or domain scope, deployment visibility, or runtime limitations. Such information SHOULD be clearly distinguished from core capability assertions.

A Capability Digest is a derived object intended for synchronization and visibility across gateways. A digest MUST be smaller in disclosure scope than the corresponding ACS. It SHOULD reveal enough information for coarse-grained matching, routing preparation, or further query forwarding, while minimizing unnecessary internal detail. A Capability Digest SHOULD contain: - a digest identifier and version; - the asserting gateway or administrative domain identifier; - one or more abstracted capability references or categories; - visibility scope and freshness metadata; and - provenance and integrity metadata. A digest MAY contain handoff hints, interface categories, trust indicators, or semantic summary references, provided these do not disclose more information than permitted by local policy.

Directory entries SHOULD support an explicit lifecycle. The following states are RECOMMENDED: - active: entry is valid for operational use; - suspended: entry is temporarily not usable but retained; - deprecated: entry remains visible for compatibility but SHOULD be replaced; and - revoked: entry MUST NOT be used for new operational decisions. Implementations MAY define equivalent states, but the effect on visibility and use MUST be clear.

A gateway MUST be able to create, update, deprecate, suspend, revoke, and remove directory entries under local lifecycle control. Registration and credential issuance themselves are out of scope, but this document defines what the directory layer requires after onboarding has completed. At a minimum: - a new ACS entry MUST be versioned at creation time; - changes to bound identity, capability references, interface binding references, semantic hooks, or integrity metadata SHOULD create a new version or equivalent version transition; - state changes MUST be auditable; - revoked entries MUST be excluded from new handoff or resolution results; and - deprecated entries SHOULD indicate replacement or migration information if available. If an ACS is derived from an external source description such as an A2A Agent Card, the gateway SHOULD distinguish source changes from gateway-local changes. A source refresh that does not alter accepted operational semantics MAY update freshness metadata without changing the ACS semantic version.

Gateways in the same collaboration environment or across federated domains MAY synchronize capability visibility information. Synchronization MUST be policy-aware and SHOULD default to Capability Digest exchange rather than full ACS replication. A synchronization mechanism for directory information SHOULD support: - initial establishment of baseline visibility; - incremental updates for entry creation, modification, withdrawal, and state transitions; - version comparison or ordering sufficient to detect stale updates; - explicit acknowledgement or equivalent delivery confirmation; - conflict detection and local conflict resolution policy; and - recovery after disconnection or partial state loss. When multiple gateways provide conflicting information about the same effective capability or identity reference, the receiving gateway SHOULD consider provenance, signature status, administrative trust policy, lifecycle state, and update freshness before accepting the new information. Synchronization procedures SHOULD be able to carry, or reference, the following metadata: - source gateway identifier; - entry identifier and version; - operation type; - effective time or update time; - optional replacement or revocation information; and - integrity and provenance evidence.

A gateway MUST evaluate whether directory information is still suitable for operational use before returning it to semantic resolution, handoff preparation, or task-routing logic. Directory validation SHOULD include: - integrity validation of the entry or synchronized update; - freshness validation against local policy or advertised validity information; - lifecycle-state validation, including revocation awareness; - provenance validation indicating which gateway or source asserted the information; and - semantic or profile reference validation when semantic hooks are present. Validation failure handling SHOULD distinguish between: - invalid entry content; - unverifiable provenance; - stale information; - revoked information; and - locally disallowed disclosure or use. An implementation MAY retain invalid or stale entries for audit or troubleshooting purposes, but such entries MUST NOT be used for new operational decisions unless explicitly allowed by local policy.

Capability directories and synchronization channels are attractive targets for poisoning, replay, downgrade, and unauthorized disclosure attacks. Implementations SHOULD consider: - integrity protection for ACS entries and synchronized digests; - provenance continuity for derived objects, especially when ingesting external descriptions such as A2A Agent Cards; - freshness enforcement to prevent stale or replayed capability visibility; - access control over which entries may be disclosed, synchronized, or returned for operational use; and - auditability of lifecycle changes and synchronization decisions. If semantic hooks are carried, implementations SHOULD also consider risks related to ontology substitution, invalid alignment references, or use of inconsistent semantic-profile versions.

This document makes no request for IANA action.