| Internet-Draft | Gateway Capability Directory for IoA | October 2026 |
| Zhang, et al. | Expires 22 April 2027 | [Page] |
This document describes a gateway capability-directory framework for Internet of Agents deployments that maintain persistent capability views and exchange selected information across gateways. It defines requirements for Agent Capability Specifications (ACSs), derived Capability Digests, lifecycle state, provenance, validation, and synchronization. It clarifies authority-scoped revisions, remaining-lifetime preservation, withdrawal handling, partial views, and recovery after disconnection or state loss.¶
The framework distinguishes source descriptions from gateway-accepted objects and distinguishes directory visibility from semantic compatibility, authorization, and execution admission. It does not define a discovery query protocol, ranking algorithm, storage substrate, distributed lookup algorithm, synchronization wire format, task orchestration protocol, or agent session protocol. It provides requirements that can inform subsequent gateway procedures and protocol bindings.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 22 April 2027.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Gateway deployments that need persistent capability views, policy-controlled disclosure, or inter-gateway visibility can use a gateway-managed directory to maintain accepted capability information. This is a deployment function, not a requirement that every gateway implement an independent directory service or that every collaboration use a gateway.¶
This document therefore 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.¶
Adjacent IETF work addresses complementary interoperability boundaries. The current DAWN proposed charter focuses on initial discovery of minimum public information about AI resources and excludes capability catalogs beyond that minimum, semantic matchmaking, ranking, and selection. AgentProto defines baseline dialog management and minimal dialog context propagation. This document concerns the gateway-managed capability information that may be consumed after initial discovery and before later interaction decisions. These relationships do not assign exclusive ownership of the remaining problem space to any particular effort.¶
The scope comparison above uses [DAWN-CHARTER] and [AGENTPROTO]. DAWN is a proposed charter under review at the time of this revision; no capability-directory or synchronization mechanism is implied to have been adopted by that effort.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] and [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
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.¶
Originating Authority: The administrative authority responsible for an assertion; distinct from a gateway forwarding that assertion.¶
Synchronization Binding: A concrete protocol mapping that realizes these requirements, including identity/authority checks, revision ordering, lifetime accounting, and recovery rules.¶
Withdrawal: Removal of an assertion from the scope of capability visibility it advertises. It does not by itself revoke the agent identity or a credential.¶
View Scope: The domain, tenant, category, or other explicit selection boundary of a synchronized or returned directory view.¶
Validation Time: When a gateway performed a particular check; it is not the source publication time or an interchangeable content revision.¶
This document specifies:¶
This document does not specify:¶
This Informational framework uses requirement keywords to describe the behavior expected of mechanisms claiming to realize it. It does not define a complete interoperable synchronization protocol. A concrete binding must specify the choices left open here, including ordering representation, authority transitions, delivery confirmations, and recovery parameters.¶
Within a gateway-based IoA deployment, 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 later 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.¶
+----------------------------------+
| Registration / Authorization |
+----------------------------------+
| Gateway Capability Directory |
| - ACS |
| - Digest |
| - Validation Metadata |
+----------------------------------+
| Resolution / Handoff / TIP / A2A |
+----------------------------------+
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.¶
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:¶
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.¶
Source-description versions, gateway-accepted ACS revisions, digest revisions, and local validation times SHOULD be recorded separately. A gateway-local transformation or policy change can require a new ACS or digest revision even when its source description is unchanged. Conversely, a source refresh does not extend source validity unless it is an authenticated authoritative refresh under the applicable binding.¶
A Capability Digest is a derived summary for inter-gateway visibility and synchronization. It SHOULD reveal only what is needed for coarse-grained matching, routing preparation, or further query forwarding. "Digest" here means an abstracted capability summary, not necessarily a cryptographic hash.¶
A Capability Digest SHOULD contain:¶
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.¶
A source description, a gateway-accepted ACS, and a Capability Digest are distinct objects with distinct assertion scopes. A gateway MUST preserve enough provenance to identify the source descriptions and accepted ACS revisions from which a synchronized digest was derived. Acceptance or normalization of a source description does not establish authorization for a particular invocation.¶
Where classification identifiers are exchanged, the applicable classification scheme and version MUST be identifiable. A category match is an input to coarse-grained discovery and MUST NOT be interpreted as proof that the parameters of a particular operation fall within a grant or satisfy current execution conditions.¶
A digest MUST NOT disclose information beyond the applicable export policy and SHOULD minimize unnecessary detail. A digest derived from multiple ACS objects MUST define the scope of the aggregation and how changes to its contributing objects affect its revision and validity.¶
An assertion returned by a remote gateway remains that gateway authority's assertion. The receiving gateway MAY maintain a separate local acceptance status but MUST NOT rewrite the originating assertion and republish it as if the origin had made the local decision.¶
Directory entries SHOULD support an explicit lifecycle. The following states are RECOMMENDED:¶
Implementations MAY define equivalent states, but the effect on visibility and use MUST be clear.¶
Expiry and verification availability are separate from the source-declared lifecycle state. A cached active assertion may be stale or temporarily unverifiable. A binding MUST specify whether and how those conditions affect visibility. A source withdrawal, a revoked directory assertion, and a revoked identity credential MUST NOT be treated as interchangeable events.¶
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:¶
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.¶
Suspension and revocation MUST prevent new handoff decisions that depend on the affected entry being usable. Reactivation or replacement requires an authorized, newer transition under the binding; old active messages cannot reactivate an entry. Local removal MUST retain any ordering information needed to prevent rollback. Effects on already running tasks are defined by the applicable interaction and authorization procedures.¶
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:¶
When different authorities assert related or apparently conflicting capability information, a receiver MUST preserve their distinct provenance and authority scopes. Local policy can choose which assertions to use, but MUST NOT impose a fictitious global revision ordering or overwrite an independent authority's assertion solely because another message arrived later.¶
Synchronization procedures SHOULD be able to carry, or reference, the following metadata:¶
Synchronization MUST distinguish an authoritative refresh from the forwarding of a previously issued assertion. Receiving or forwarding a cached copy MUST NOT reset the assertion's original validity interval or grant it a new full lifetime. A binding MUST specify how remaining lifetime, clock uncertainty where relevant, and replay protection are handled.¶
Withdrawal at the origin does not establish that every cached copy has been removed. A deployment MUST account for propagation delay, disconnection, and the remaining validity of copies when deciding whether synchronized information remains suitable for operational use. Discovery-record lifetime is not a substitute for the current authorization or revocation checks required at invocation time.¶
A withdrawal or revocation assertion MUST identify the originating authority, affected entry, and revision or ordering boundary to which it applies. A receiving gateway MUST prevent an older active assertion within that scope from restoring the withdrawn or revoked entry.¶
An implementation MAY retain a versioned withdrawal record for this purpose. If that record is garbage-collected, the implementation MUST retain another effective means of preventing rollback, such as a persistent ordering boundary, a bounded replay model, or a newly validated authoritative baseline. Deleting the local record without preserving the required protection is insufficient.¶
After disconnection or state loss, a gateway MUST NOT assume that its prior view is complete and current. The synchronization binding MUST define when incremental recovery is sufficient, when baseline resynchronization is required, and what information is ineligible for operational use until recovery is complete. These requirements do not imply instantaneous revocation across partitioned domains.¶
The binding MUST state the ordering and authorization rules for reinstatement after withdrawal, retention and replay bounds for suppression information, and which state survives restart. A local deny or suppression override MUST NOT be propagated as an origin withdrawal without the authority to make that assertion.¶
Gateways MAY exchange selected subsets by domain, tenant, capability category, or other declared scope. A binding MUST identify the scope and baseline to which each incremental update applies and define what establishes completeness within that scope. A missing entry in a partial view is not evidence of global absence.¶
A synchronization acknowledgment or equivalent confirmation MUST have defined semantics: delivery, validation, and installation are distinct events. A transport acknowledgment alone MUST NOT be interpreted as proof that the peer has installed the update or applied it to a decision. The binding MUST define recovery when an acknowledgment is lost, without extending the lifetime of repeated content.¶
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:¶
Validation failure handling SHOULD distinguish between:¶
A directory MAY synchronize only a policy-selected subset of entries. The scope of a synchronized view or returned result MUST be identifiable. A receiver MUST distinguish a complete result within that scope from a partial, unavailable, or policy-restricted result. A failed or incomplete lookup MUST NOT be represented internally as an established finding that the requested entry does not exist.¶
Validation processing MUST distinguish invalid content, unverifiable provenance, stale information, revoked information, and locally disallowed use. Information known to be revoked or to have failed a required integrity check MUST NOT be presented as valid or used as a valid basis for a new operational decision. Any permitted use of stale information MUST have an explicit, bounded policy and MUST preserve its stale status; such use does not establish invocation authorization.¶
The decision-making gateway MUST retain the relevant distinctions. A binding MAY expose less detailed failure information to another party when required by disclosure policy, provided that the reduced disclosure does not convert an incomplete result into a false success or absence claim.¶
An implementation MAY retain invalid, revoked, stale, or unverifiable entries for audit or troubleshooting, but MUST preserve those distinctions and MUST NOT present retained information as currently validated. A policy allowing stale candidate hints cannot bypass a required integrity, lifecycle, authorization, or admission check.¶
Within DMSC architecture, the capability directory is a gateway-side control-plane function that supports other DMSC functions such as semantic resolution, task-based invocation, and inter-gateway visibility [MACP] [ACPS-ARC] [IOA-TASK].¶
This document is intended to be complementary to other DMSC work. It refines the control-plane objects and requirements needed by protocol-suite elements such as ACS/CDSP in MACP, by capability-management and discovery functions in ACPs Architecture, and by gateway functions such as delegated discovery, ID-based resolution, and task-based searching [MACP] [ACPS-ARC] [GW-REQ].¶
It also provides a substrate that can be used by task-level procedures and semantic-interoperability work, while remaining below gateway-facing intent-routing behavior such as IAIP [IOA-TASK] [IOA-SEM] [IAIP-00]. 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:¶
Directory visibility, semantic compatibility, provider selection, authorization, and execution admission are separate determinations. An active entry or successful directory lookup MUST NOT be interpreted as a grant to execute an operation.¶
Information handed to a later interaction procedure MUST retain the relevant entry revision, assertion scope, provenance, and validity information, either directly or through a verifiable reference. The consuming procedure remains responsible for the current identity, delegation, authorization, and operational checks required by its protocol and deployment. An unresolved required condition MUST NOT silently become an authorization or admission success.¶
This document does not define parameter-level authorization semantics, an execution controller, or a new credential format. Such mechanisms can be integrated through optional bindings without becoming mandatory dependencies of the directory framework.¶
The current MACP architecture discusses capability directory synchronization in its CDSP component [MACP]. Gateway mediation can consume directory records, semantic interpretation, and separate policy/trust inputs [MEDIATION]. Neither reference makes this framework a working-group-adopted synchronization protocol.¶
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 [A2A-SPEC].¶
An ACS is not the same object as an external description such as an A2A Agent Card. An external description states what an agent claims or offers for publication or exchange, while an ACS is a gateway-managed, normalized, and policy-constrained directory object used by DMSC infrastructure. 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, externally supplied description content is not automatically suitable for directory synchronization or operational use; it remains subject to local validation, normalization, provenance tracking, and policy application.¶
ANML documents and operator-managed descriptors are additional possible sources [ANML]. A deployment-specific mapping MUST identify preserved fields, transformations, dropped information, and constraints that could not be represented. Those unresolved constraints MUST NOT silently disappear from decisions that depend on them. No lossless generic conversion is asserted.¶
Other proposals are considering broader directory-service mechanisms for agents. For example, the ADS draft discusses a distributed agent directory service with content-addressed storage, taxonomy-based discovery, content-routing, and peer-to-peer synchronization [ADS-01].¶
This document has a narrower focus. It defines the gateway-managed control-plane directory objects and requirements that a DMSC Gateway needs in order to maintain validated capability information for local use and inter-gateway visibility.¶
Accordingly, this document does not define a storage substrate, content-addressed artifact model, distributed lookup algorithm, taxonomy design, or generic search architecture. Such mechanisms could be complementary if they are used as one backend, one exchange environment, or one visibility mechanism for gateway-managed directory information.¶
DRISAC provides another proposal for capability classification, onboarding, and information distribution [DRISAC]. Its classification and distribution roles can be compared with the object lifecycle and validation requirements here without mandating its topology or category scheme. Both remain individual proposals. A category correspondence requires an explicit mapping; similar names are insufficient.¶
These examples describe logical records and expected behavior, not a mandatory wire format, a global ordering algorithm, or measured implementation results.¶
{
"authority": "https://gateway.example.org",
"entryId": "cap-17",
"events": [
{
"revision": 7,
"state": "active"
},
{
"revision": 8,
"operation": "withdraw"
},
{
"revision": 7,
"state": "active"
}
]
}
¶
Assume the authority is validated and the binding orders these integer revisions for this entry. After accepting revision 8, the receiver rejects the delayed active revision 7 as older. A legitimate re-publication requires an authorized transition newer than the withdrawal under that binding. Local garbage collection cannot remove rollback protection.¶
Gateway A issues a validated assertion at 12:00 with validity ending at 12:05. Gateway B receives it at 12:02 and forwards it to C at 12:03. Assuming synchronized clocks for this example, C can accept at most the remaining two minutes, not five new minutes. If A deletes its record at 12:04 but C receives no withdrawal, deletion alone does not tell C that its copy has been withdrawn. At 12:05 it is expired; any stale candidate use must be explicitly bounded and cannot establish invocation authorization.¶
Capability directories and synchronization channels are attractive targets for poisoning, replay, downgrade, and unauthorized disclosure attacks. Implementations SHOULD consider:¶
If semantic hooks are carried, implementations SHOULD also consider risks related to ontology substitution, invalid alignment references, or use of inconsistent semantic-profile versions.¶
The originating authority and entry scope MUST be authenticated by the applicable synchronization binding. Revision ordering without source authentication can let an attacker inject an apparently newer withdrawal or advertisement. Required integrity checks, replay protection, export policy, and binding-specific trust validation apply before information is accepted.¶
Partition and clock assumptions limit withdrawal timeliness. A deployment SHOULD document its stale-state budget and the operational uses that must stop when required current information is unavailable. Synchronization freshness cannot eliminate the time-of-check/time-of-use gap at invocation; the consuming security mechanism remains responsible for current authorization and revocation checks.¶
Even minimized digests can reveal membership, capability categories, or operational changes through enumeration and update timing. Gateways SHOULD apply scope-limited visibility, access controls and retention limits; smaller byte size alone does not establish privacy. Sensitive failure details SHOULD be withheld externally when appropriate while retaining accurate internal validation results.¶
This document makes no request for IANA action.¶
RFC Editor: Please remove this appendix before publication.¶