Agent Capability Advertisement Protocol (ACAP)

Status of This Memo

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 27 December 2026.¶

Copyright Notice

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.¶

Table of Contents

1. Introduction

The proliferation of AI agents deployed across heterogeneous administrative domains on the Internet creates a fundamental interoperability challenge: how can an agent or orchestration system discover the capabilities of agents it has never previously encountered, without relying on centralized registries or out-of-band coordination?¶

This document specifies the Agent Capability Advertisement Protocol (ACAP), a structured discovery protocol that fills this gap. ACAP is inspired by RFC 8615 (Well-Known URIs) [RFC8615] and the WebFinger protocol [RFC7033] and provides richer capability advertisement than DNS-SD TXT records.¶

ACAP defines:¶

• A well-known URI scheme for locating ACAP endpoints.¶

• An Agent Capability Document (ACD) format encoded as JSON, optionally carried as the payload of a JWT [RFC7519] when signing is required.¶

• Three HTTP/3 [RFC9114] operations: GET (retrieve), PUT (register/update), and POST (query by capability).¶

• A signing mechanism based on JSON Web Signature (JWS) [RFC7515] to ensure ACD integrity and agent operator authenticity.¶

A key motivation for ACD signatures is the multi-tenant deployment model, where multiple agent operators share the same hosting infrastructure. In such environments, the TLS end-entity certificate belongs to the infrastructure provider, not the agent operator. ACD signatures allow the agent operator to bind their identity directly to the ACD content, independent of the hosting infrastructure.¶

Note: A future revision of this document will provide a formal CDDL [RFC8610] representation covering both JSON and CBOR encodings, enabling the same ACD content to be represented in either encoding. When CBOR encoding is supported, COSE [RFC9052] will be used for signing in place of JWS. Clients and servers will negotiate the encoding using the Accept and Content-Type headers.¶

2. Terminology

Agent:

An autonomous software entity capable of performing tasks on behalf of a principal, potentially communicating with other agents.¶

Agent Capability Document (ACD):

A structured JSON document that describes an agent's identity, capabilities, and authentication requirements. In Model 2, an ACD MUST be carried as the payload of a JWT [RFC7519]. In Model 1, an ACD MAY be carried as plain JSON.¶

ACAP Endpoint:

An HTTP/3 server exposing ACD resources at well-known URIs.¶

Trust Domain:

An administrative domain that operates one or more ACAP endpoints and issues or validates agent identities within that domain.¶

Capability Descriptor:

A structured record within an ACD that describes a single capability offered by the agent.¶

Agent Operator:

The entity responsible for deploying and managing an agent, which holds the private key used to sign the ACD.¶

3. Motivation

When the domain of an agent operator is already known, the DNS provides what is needed to connect to it. Service Binding (SVCB) records [RFC9460] convey connection parameters such as the supported application protocols, port, and IP addresses in a single cached lookup, before any connection is established. ACAP does not duplicate this connection-layer information.¶

What the DNS does not provide is a way to learn what an agent can do. Agent capability information is structured and evolving: each capability has its own input and output types, performance characteristics, and authentication requirements, and discovery includes searching for agents by capability, not only resolving a known name. This is not a connection hint; it is capability data, and querying it is an application-layer operation. Encoding such data in the DNS is also a poor fit: capability data is far larger than a connection hint, and packing it into DNS records inflates response sizes and risks fragmentation and fallback to TCP.¶

ACAP therefore addresses a different concern than connection bootstrap. It defines the Agent Capability Document, its retrieval, and capability-based search, served over HTTPS at well-known URIs. Placing capability description at the application layer lets the protocol carry rich and extensible structure, be queried, and be signed by the agent operator independently of the infrastructure that hosts it (Section 5). Because the format is an application-layer document, new capabilities and fields can be introduced in future revisions without defining new DNS record types or registering new parameters. DNS-based connection discovery and ACAP are complementary: the former locates and connects to a known domain, while ACAP describes the capabilities of the agents within it and enables discovery across them.¶

4. Protocol Overview

ACAP operates as follows:¶

1. An agent operator registers an ACD at their ACAP endpoint by issuing a PUT request to the well-known URI for that agent.¶

2. A discovering party retrieves an ACD by issuing a GET request to the agent's well-known URI, or discovers agents by capability by issuing a POST query to the domain-level query endpoint.¶

3. Upon receipt of a signed ACD, the recipient MUST verify the JWS signature and check that the ACD has not expired.¶

The following diagram illustrates the basic discovery flow:¶

   Requester                                           ACAP Endpoint
       |                                                     |
       |--- GET https://{domain}/.well-known/            --->|
       |        agents[/{agent-local-id}]/acap               |
       |                                                     |
       |<------- 200 OK {JWT or JSON ACD} ------------------ |
       |                                                     |
       |         [If signed: Verify JWS signature]           |
       |         [If signed: Check exp claim]                |
       |                                                     |
       |-- Connect to agent endpoint (QUIC/WebTransport) --->|

5. Deployment Models

This section describes two common deployment models. Other deployment models are possible and may be defined in future revisions of this document.¶

https://example.com/.well-known/agents/scheduler/acap
https://example.com/.well-known/agents/docproc/acap
https://example.com/.well-known/agents/support/acap

6. Well-Known URIs

ACAP endpoints MUST be accessible at the following well-known URI ([RFC8615]):¶

https://{domain}/.well-known/agents[/{agent-local-id}]/acap

where {domain} is the fully qualified domain name of the agent operator and {agent-local-id} is a domain-local identifier for the agent, which MUST be URL-safe and MUST NOT contain path separator characters. {agent-local-id} MUST be present when multiple agents are deployed within the same domain.¶

A domain-level index of all agents available within a domain MUST be accessible at:¶

https://{domain}/.well-known/agents

The domain index resource SHOULD return a JSON array of ACDs available within that domain.¶

A domain-level capability query endpoint MUST be accessible at:¶

https://{domain}/.well-known/agents/_query

ACAP endpoints MUST be served over HTTPS with a valid TLS certificate. Servers MUST support HTTP/3 [RFC9114].¶

NOTE : Support for HTTP/2 as a fallback MAY need to be considered.¶

https://{access-network-domain}/.well-known/agents

7. Agent Capability Document (ACD) Format

ACDs are JSON objects. In Model 2 (Section 5), ACDs MUST be carried as the payload of a JWT [RFC7519], signed using JWS Compact Serialization [RFC7515] as described in Section 9. In Model 1, ACDs MAY be signed.¶

The JWT payload for a signed ACD contains the following fields. The JWT registered claims [RFC7519] MUST be present:¶

iss:

The agent operator's domain URI (e.g., "https://example.com").¶

iat:

The time at which the ACD was signed, as a NumericDate value (seconds since the Unix epoch) per [RFC7519].¶

exp:

The expiration time of the ACD, as a NumericDate value per [RFC7519]. Recipients MUST NOT use an ACD whose exp time has passed.¶

The JWT registered claims iss, iat, and exp are defined by [RFC7519] and are included here to clarify their specific semantics and requirements within the ACAP context. Implementations MUST follow [RFC7519] for encoding and processing these claims.¶

The following ACD-specific fields MUST also be present in the JWT payload:¶

{
  "iss"          : string,       ; Agent operator domain URI (JWT)
  "iat"          : integer,      ; Signing time NumericDate (JWT)
  "exp"          : integer,      ; Expiration time NumericDate (JWT)
  "id"           : string,       ; Agent Identifier URN
  "version"      : string,       ; Framework version (e.g., "1.0")
  "domain"       : string,       ; Agent operator domain name
  "name"         : string,       ; Human-readable agent name (UTF-8)
  "description"  : string,       ; Short description (UTF-8)
  "endpoint"     : string,       ; Primary QUIC/WebTransport endpoint URI
  "alt_endpoints": [string],     ; Alternate endpoints
  "capabilities" : {             ; Capability taxonomy map
    string => CapabilityDescriptor
  },
  "auth"         : AuthConfig,       ; Authentication and authorization config
  "transport"    : TransportConfig,  ; Transport configuration
  "context"      : ContextConfig,    ; Context and session parameters
  "jwks_uri"     : string,           ; URI of the agent operator's JWK Set
}

Field definitions:¶

id:

A URN uniquely identifying the agent.¶

version:

The IETF protocol suite version to which this ACD conforms (e.g., "1.0").¶

domain:

The fully qualified domain name of the agent operator (e.g., "example.com"). MUST match the domain portion of the well-known URI from which this ACD was served.¶

name:

A human-readable display name for the agent. MUST be encoded as UTF-8.¶

description:

A short, human-readable description of the agent's capabilities and intended use. MUST be encoded as UTF-8.¶

endpoint:

The URI of the agent's primary QUIC or WebTransport endpoint to which connections SHOULD be established after discovery.¶

alt_endpoints:

An array of alternative endpoint URIs for load balancing or failover. MAY be empty.¶

capabilities:

A map from capability name strings to CapabilityDescriptor objects (see Section 7.1).¶

auth:

An AuthConfig object describing supported authentication and authorization schemes (see Section 7.2).¶

transport:

A TransportConfig object describing the agent endpoint's transport configuration (see Section 7.3).¶

context:

A ContextConfig object describing session and context parameters. The structure of ContextConfig is left to the IETF agentic protocol suite profile specification.¶

jwks_uri:

A URI at which the agent operator's JSON Web Key Set [RFC7517] MAY be retrieved. Used by recipients to obtain the public key for JWS signature verification. MUST be present in Model 2 (Section 5).¶

CapabilityDescriptor = {
  "id"         : string,   ; Capability URN
  "version"    : string,   ; Capability version
  "input_type" : [string], ; Accepted input modalities/formats
  "output_type": [string], ; Produced output modalities/formats
  "latency_ms" : integer,  ; Expected p50 latency in milliseconds
  ? "rate_limit": integer, ; Requests per second limit (optional)
  ? "cost_unit" : string,  ; Pricing unit, informational (optional)
}

AuthConfig = {
  "schemes"               : [string], ; e.g., ["spiffe", "oauth2", "mtls"]
  "authorization_servers" : [string], ; OAuth 2.0 AS URIs (per RFC9728)
  "scopes_supported"      : [string], ; OAuth 2.0 scopes (per RFC9728)
}

TransportConfig = {
  "modalities"   : [string],     ; Supported modalities
  "protocols"    : [string],     ; Supported transport protocols
  "pref_add"     : [string],     ; reachable IP addresses
}

8. ACAP Operations

ACAP defines three operations over HTTP/3. Requests and responses carrying signed ACDs MUST use Content-Type: application/jwt. Requests and responses carrying unsigned ACDs MUST use Content-Type: application/json.¶

GET https://{domain}/.well-known/agents[/{agent-local-id}]/acap  HTTP/3
Accept: application/jwt, application/json

200 OK
Content-Type: application/jwt  (Model 2) or application/json (Model 1)
Cache-Control: max-age=300

<JWT or JSON>

PUT https://{domain}/.well-known/agents[/{agent-local-id}]/acap  HTTP/3
Content-Type: application/jwt  (Model 2) or application/json (Model 1)

<JWT or JSON>

204 No Content

POST https://{domain}/.well-known/agents/_query  HTTP/3
Content-Type: application/json

{
  "capability"    : "urn:ietf:cap:translate",
  "modalities"    : ["text"],
  "domain_hint"   : "*.example.com",
  "max_latency_ms": 500
}

200 OK
Content-Type: application/json

{
  "results"    : [ <JWT or JSON ACD>, ... ],
  "next_cursor": "string"
}

9. ACD Signing and Verification

ACDs are signed using JWS Compact Serialization [RFC7515]. The signed ACD is represented as:¶

Base64url(JWS Protected Header)
  || '.'
  || Base64url(JWT Payload)
  || '.'
  || Base64url(Signature)

10. Security Considerations

ACAP endpoints are served over HTTPS, which protects the confidentiality and integrity of ACDs in transit and authenticates the server hosting the ACAP endpoint. However, TLS alone is not sufficient to establish trust in the content of an ACD.¶

As discussed in Section 5, in the multi-tenant deployment model the TLS certificate belongs to the infrastructure provider, not the agent operator. The ACD signature addresses this gap. By signing the ACD with a private key under the agent operator's control, separate from the hosting platform's TLS key, the agent operator binds their identity directly to the content of the ACD, including the endpoint URI. Without signature verification, a compromised or malicious hosting platform could redirect connecting agents to a fraudulent endpoint. A recipient that verifies the signature can confirm that the agent operator, not just the hosting infrastructure, authorized that specific ACD.¶

Recipients MUST verify ACD signatures before acting on any signed ACD content, regardless of whether the ACD was retrieved directly from the ACAP endpoint or obtained through a registry or other intermediary.¶

11. IANA Considerations

12. References

Appendix A. Appendix A — Example ACD (JWT)

The following is a non-normative example of a signed ACD.¶

The JWS Protected Header is:¶

{
  "alg": "ES256",
  "kid": "operator-key-1"
}

The JWT Payload is:¶

{
  "iss":         "https://example.com",
  "iat":         1744887600,
  "exp":         1744891200,
  "id":          "urn:ietf:agent:example.com:translator-v1",
  "version":     "1.0",
  "domain":      "example.com",
  "name":        "Example Translation Agent",
  "description": "Translates text between supported language pairs",
  "endpoint":    "https://agent.example.com:4433/translator",
  "alt_endpoints": ["https://agent2.example.com:4433/translator"],
  "capabilities": {
    "translate": {
      "id":          "urn:ietf:cap:translate",
      "version":     "1.0",
      "input_type":  ["text/plain"],
      "output_type": ["text/plain"],
      "latency_ms":  350,
      "rate_limit":  100,
      "cost_unit":   "USD per 1M characters"
    }
  },
  "auth": {
    "schemes":               ["oauth2", "mtls"],
    "authorization_servers": ["https://auth.example.com"],
    "scopes_supported":      ["agent:invoke"],
  },
 "transport": {
   "modalities":  ["text"],
   "protocols":   ["quic"],
   "pref_add":    ["192.0.2.10"]
 },
  "jwks_uri": "https://agent.example.com/.well-known/jwks.json"
}

The complete signed ACD is the JWT:¶

<Base64url(Header)>.<Base64url(Payload)>.<Base64url(Signature)>

Appendix B. Appendix B — Relationship to Existing Protocols

ACAP is designed to complement, rather than replace, existing discovery and identity protocols:¶

• WebFinger (RFC 7033): WebFinger provides lightweight identity lookup tied to email-like identifiers. ACAP provides richer, capability- oriented discovery tied to HTTPS well-known URIs.¶

• DNS-SD / mDNS: Suitable for local network discovery; does not scale to Internet-wide agent discovery or carry semantic capability metadata.¶

• OAuth 2.0 (RFC 6749): ACAP references OAuth 2.0 for access token issuance but does not specify authorisation flows; those are left to IETF agentic protocol suite profile specifications.¶

• A2A Agent Cards: The Agent2Agent Protocol uses a similar well-known URI pattern for agent discovery. ACAP differs in its richer ACD schema, its three-operation model including capability search, and its HTTP/3 transport mandate.¶

• SD-Card ([SD-CARD]): SD-Card applies SD-JWT [RFC9901] to A2A Agent Cards to enable selective disclosure of agent capabilities in privacy-sensitive contexts. ACAP differs in that ACDs are publicly accessible capability advertisements served from well-known URIs; selective disclosure is not applicable to ACAP's design. Access control to specific capabilities is enforced at invocation time through the auth and scopes_supported fields in the ACD, not at discovery time.¶

• DAWN ([I-D.farrel-dawn-terminology]): The Discovery of Agents, Workloads, and Named Entities (DAWN) effort treats discovery as locating an entity to communicate with, and explicitly places capability exposure and capability exchange out of scope while noting they are essential to agent selection and operation. ACAP provides that function: an ACD is a capability card in DAWN's terms, and ACAP's retrieval, registration, and query operations are how an agent's capabilities are exposed and exchanged.¶

Appendix C. Appendix C — Example Discovery Flow

This example walks through a complete discovery of the translation agent from Appendix A, hosted at example.com.¶

1. Obtain the domain. The discovering party knows the domain example.com, for example from configuration (see the methods in Section 6)¶

2. Find the agent. The party queries the domain for agents offering the translation capability:¶

POST https://example.com/.well-known/agents/_query
Content-Type: application/json

{ "capability": "urn:ietf:cap:translate" }

200 OK
Content-Type: application/json

{
  "results": [ "<signed ACD for translator-v1; see Appendix A>" ]
}

1. Verify the ACD. The party fetches the JWK Set from the jwks_uri in the ACD, verifies the JWS signature using the key matching kid, and checks that the exp time has not passed.¶

2. Connect. Having confirmed the agent operator signed the ACD, the party connects to the endpoint (https://agent.example.com:4433/translator) and uses the agent's translation capability.¶

Acknowledgements

Thanks to Mohamed Boucadair for the review and suggestions.¶

Authors' Addresses