Agent Description Protocol (ADP)

1.1. Problem Statement

Agents in a decentralized network need a standard way to describe what they can do, so that other agents can discover and invoke them. Without a common description format, every agent application protocol must independently define how capabilities are advertised, how methods are enumerated, and how operational constraints are communicated.¶

Existing agent description approaches address parts of this problem. Google A2A defines an AgentCard for HTTP-based agents. MCP defines a tool list for client-server tool providers. OASF defines a Kubernetes-style AgentDescriptor for orchestrators. Each assumes a specific network model and transport binding. None is designed for agent://- addressed peers communicating over AIP and AITP.¶

ADP bridges this gap. It describes a single document format — the Agent Card — that can be exchanged natively over AITP, while remaining convertible to and from external description formats.¶

1.2. Scope

This document is one of four core Internet-Drafts in the Agent Network Protocol (ANP) suite: AIP [I-D.song-anp-aip] (datagram delivery), AITP [I-D.song-anp-aitp] (invocation transport), ANS [I-D.song-anp-ans] (name system), and ADP (this document, description and discovery). The four drafts are designed to co-evolve as a self- contained protocol suite; no additional specification is required for baseline interoperability. AIP's local-resolver semantic extension MAY be backed by an implementation that consults ADP discovery services for ranked capability matching; ANS core provides name-to-peer binding but does not itself perform ranked semantic discovery.¶

ADP is an application-layer convention carried over AITP [I-D.song-anp-aitp].¶

This document is organized in three layers of decreasing normative weight:¶

ADP Core (Sections 3-4)

The Agent Card JSON document format — schema, field semantics, tool and endpoint descriptors, skill tags, constraints, and the extension mechanism. This is the primary contribution of the document.¶

ADP Exchange Conventions (Section 5)

Three AITP method names (adp.describe, adp.advertise, adp.discover) through which agents retrieve, publish, and query Agent Cards. These conventions bind the format to AITP but do not preclude other transports.¶

ADP Baseline Discovery Profile (Section 6)

A recommended multi-factor scoring algorithm providing one interoperable starting point for ranking agents. This is guidance, not the only valid ranking strategy.¶

This document does not cover:¶

1. Agent identity, key management, or authentication — these belong to AIP and deployment-context mechanisms.¶
2. Reputation scoring or trust computation — these belong to a companion reputation protocol.¶
3. Economic settlement, pricing, or credit systems.¶
4. Verifiable credentials or attestation chains.¶
5. Transport-specific dissemination (DHT key spaces, GossipSub topics, HTTP well-known paths) — these are implementation profiles, not protocol requirements.¶
6. Task orchestration, workflow, or business logic.¶

Accordingly, this document does not specify a complete agent runtime or deployment system; it describes only the description format and exchange conventions shared by agents above AITP.¶

1.3. Positioning Among Existing Approaches

ADP is not a replacement for any existing agent description standard. Its role is to describe a common description and exchange convention above AIP/AITP, in the same way that AITP defines a common invocation substrate above AIP.¶

Google A2A's AgentCard is an HTTP-oriented description served at a well-known URL, tightly coupled to HTTP transport and A2A task semantics. ADP's Agent Card is transport-independent at the protocol level; an AITP method retrieves it, and conversion to A2A format is a straightforward mapping (see Appendix A.1).¶

MCP's tool list describes capabilities of a client-server tool provider. ADP's tool descriptors use the same field names (name, description, inputSchema) for direct compatibility, but extend them with output schema, streaming, and idempotency annotations relevant to agent-to-agent invocation.¶

OASF's AgentDescriptor uses a Kubernetes-style manifest (kind/apiVersion/metadata/spec) designed for orchestration platforms. ADP uses a flat JSON document optimized for network exchange and progressive disclosure, but fields map bidirectionally to OASF (see Appendix A.3).¶

1.4. Design Rationale

ADP is justified when the following conditions hold:¶

1. Multiple agent applications need capability discovery.¶

   If task orchestration, knowledge replication, swarm coordination, and direct messaging each need to discover agents by skill, factoring description and discovery into a shared protocol eliminates redundant definitions.¶

2. A single document simplifies the ecosystem.¶

   If an agent's identity, capabilities, endpoints, and constraints are scattered across multiple data structures (profile records, resume broadcasts, name table entries), unifying them into one document reduces inconsistency.¶

3. Cross-ecosystem interoperability is valued.¶

   If agents from different ecosystems (A2A, MCP, OASF) need to interoperate, a superset document that can be losslessly projected onto each ecosystem's format enables bridging without information loss.¶

1.5. Assumptions

ADP assumes:¶

1. An AITP module capable of sending and receiving invocations with the methods defined in this document.¶
2. Agent:// URIs are stable identifiers for the duration of an Agent Card's validity period.¶
3. Agent Card documents are UTF-8 encoded JSON ([RFC8259]). Implementations MAY additionally support CBOR ([RFC8949]) for constrained environments.¶
4. Companion protocols (reputation, credentials, economics) extend the Agent Card through the extension mechanism defined in Section 3.8, not by modifying core fields.¶

1.6. Requirements Language

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 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.7. Document Status

This document is Informational. ADP describes a JSON document format and a set of AITP exchange conventions derived from running code in the ClawNet implementation. Unlike AIP and AITP, which define wire-level protocol encodings and state machines, ADP is a data-format and naming convention — closer in nature to RFC 7946 (GeoJSON) than to a transport protocol specification.¶

The BCP 14 keywords in this document express interoperability requirements: an implementation that conforms to the Agent Card schema and method conventions described here will interoperate with other conforming implementations. The keywords do not imply Standards Track status.¶

3.1. Document Structure

The top-level JSON object contains the following fields. Field names use snake_case for consistency with the existing implementation base and MCP field conventions.¶

Implementations MUST ignore unrecognized top-level fields to enable forward compatibility. Implementations MUST NOT reject an Agent Card solely because it contains fields not defined in this specification.¶

3.2. Agent Card Signature

The optional "seq" and "signature" fields allow an Agent Card to be verified independently of its delivery channel. This is important when cards are cached by directory agents, relayed through gossip, or stored in the DHT — contexts where the original AITP association is no longer available for authentication.¶

To sign an Agent Card, the agent:¶

1. Constructs the complete Agent Card JSON object with all desired fields, including "seq", but excluding "signature".¶
2. Serializes the object using JCS (JSON Canonicalization Scheme, [RFC8785]) to produce a deterministic byte sequence.¶
3. Signs the byte sequence with the agent's Ed25519 private key.¶
4. Encodes the 64-byte signature as Base64url (no padding) and inserts it as the "signature" field.¶

A consumer verifies an Agent Card by removing the "signature" field, re-canonicalizing via JCS, and verifying the Ed25519 signature against the public key derived from the "id" URI. If verification fails, the consumer MUST discard the card.¶

When both "seq" and "signature" are present, consumers MUST prefer the card with the higher "seq" value for a given "id". A card without "signature" MUST NOT supersede a signed card with the same or higher "seq".¶

These fields mirror the same pattern used by ANS Name Records ([I-D.song-anp-ans], Section 5.1), providing a uniform authentication mechanism across both discovery layers.¶

3.3. Identity Model

Within the ANP protocol suite, agent:// is the native identifier for network-facing capability endpoints. The agent:// URI serves as the canonical primary key across all four protocol layers:¶

• AIP: source and destination URI in datagrams¶
• ANS: registration, resolution, and discovery key¶
• AITP: association endpoint identifier¶
• ADP: capability description subject¶

Other identifiers such as Decentralized Identifiers (DIDs) may be attached to an Agent Card via the optional "did" field for external ecosystem interoperability — credential issuance, cross-domain identity federation, or legal identity binding. These external identifiers do not replace the native agent:// identifier and are not used for routing, name resolution, or transport association within ANP.¶

3.4. Tool Descriptors

Each element of the "tools" array describes a single invocable method. The field names align with MCP's tool definition for direct compatibility.¶

Implementations MUST ignore unrecognized fields within tool descriptors.¶

3.5. Endpoint Descriptors

Each element of the "endpoints" array binds a set of methods to a reachable network address.¶

The "aitp" protocol identifier is the native binding for ANP agents. Other identifiers enable bridging to non-ANP ecosystems. These identifiers are recognized by conforming ADP implementations for interoperability; they do not constitute a global protocol registry. The list is not exhaustive; implementations MAY recognize additional protocol identifiers and MUST ignore endpoint entries with identifiers they do not understand.¶

3.6. Skill Tags

The "skills" array contains UTF-8 strings that classify the agent's capabilities for discovery. Two syntactic forms are defined:¶

3.7. Operational Constraints

The "constraints" object communicates operational limits to potential callers.¶

All constraint fields are advisory. Callers SHOULD respect advertised constraints but MUST be prepared for the agent to enforce them via AITP status codes (BUSY, INVALID_REQUEST) at invocation time.¶

3.8. Extension Mechanism

The "extensions" object carries protocol-specific or deployment-specific data that is not part of the ADP core. Each key in the extensions object is a namespace string; each value is an arbitrary JSON object.¶

Namespaces SHOULD use reverse-domain notation or a well-known short name to avoid collisions (e.g., "clawnet.reputation", "oasf.labels").¶

Implementations MUST preserve unrecognized extension namespaces during round-trip serialization. Implementations MUST NOT reject an Agent Card because it contains unrecognized extensions.¶

Example extensions for a ClawNet deployment:¶

{
  "extensions": {
    "clawnet.reputation": {
      "score": 78.5,
      "tier": 16,
      "tasks_completed": 342,
      "avg_rating": 4.7
    },
    "clawnet.economics": {
      "cost_shells_per_call": 1,
      "requires_deposit": false
    }
  }
}

3.9. Complete Example

{
  "id": "agent://translator-zh-en",
  "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  "name": "translator-zh-en",
  "description": "Chinese-English bidirectional translation",
  "version": "1.2.0",
  "skills": ["nlp/translation", "nlp/text-analysis", "python"],
  "tools": [
    {
      "name": "translate",
      "description": "Translate text between languages",
      "input_schema": {
        "type": "object",
        "properties": {
          "text": {"type": "string"},
          "source_lang": {"type": "string", "default": "auto"},
          "target_lang": {"type": "string"}
        },
        "required": ["text", "target_lang"]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "translated": {"type": "string"},
          "confidence": {"type": "number"}
        }
      },
      "streaming": false,
      "idempotent": true
    }
  ],
  "endpoints": [
    {
      "protocol": "aitp",
      "uri": "agent://translator-zh-en",
      "methods": ["translate", "detect_language", "glossary"]
    },
    {
      "protocol": "http+json",
      "uri": "https://api.example.com/translate/v1",
      "auth": "bearer",
      "priority": 10
    }
  ],
  "constraints": {
    "max_concurrent_tasks": 3,
    "max_input_tokens": 100000,
    "supported_languages": ["zh", "en", "ja"],
    "rate_limit": "60/min"
  },
  "metadata": {
    "created_at": "2026-01-15T00:00:00Z",
    "updated_at": "2026-03-24T12:00:00Z",
    "ttl": 3600
  }
}

4.1. adp.describe — Retrieve an Agent Card

A caller sends a REQUEST with Method = "adp.describe" to retrieve the remote agent's Agent Card.¶

Request body

Empty, or a JSON object with an optional "fields" array listing the top-level field names the caller is interested in. If "fields" is present, the responder MAY return only the requested fields plus the two required fields (id, name).¶

Response body (Status = OK)

The agent's Agent Card as a JSON object conforming to Section 3.¶

Error responses

UNAUTHORIZED (5) if the caller lacks permission to view the description.¶

Agents implementing ADP MUST register a handler for the "adp.describe" method and respond with at least a minimal Agent Card (id and name). Deployments that expose peer-visible capability metadata SHOULD implement adp.describe, as it is the primary mechanism through which peers learn an agent's capabilities.¶

4.2. adp.advertise — Publish an Agent Card

An agent sends a REQUEST with Method = "adp.advertise" to push its Agent Card to a peer, directory service, or name server.¶

Request body

The sender's Agent Card as a JSON object. The "id" field MUST equal the AITP association's source agent:// URI.¶

Response body (Status = OK)

A JSON object with a "stored" boolean field indicating whether the receiver has stored the Agent Card.¶

Error responses

INVALID_REQUEST (6) if the Agent Card fails validation. UNAUTHORIZED (5) if the sender is not permitted to advertise.¶

Receivers SHOULD validate that the Agent Card's "id" matches the AITP association's remote agent:// URI. Receivers MAY refuse to store Agent Cards that exceed a deployment-specific size limit.¶

4.3. adp.discover — Query for Agents

A caller sends a REQUEST with Method = "adp.discover" to query a peer or directory service for agents matching specified criteria.¶

Request body

A JSON object with the fields in Table 8.¶

Response body (Status = OK)

A JSON object with a "results" array. Each element contains the fields in Table 9.¶

Error responses

INVALID_REQUEST (6) if the query is malformed.¶

Any agent MAY respond to adp.discover queries by searching its local knowledge of peer Agent Cards. A dedicated directory agent MAY aggregate Agent Cards from adp.advertise calls and serve richer discovery results.¶

4.4. Method Summary

5.1. Recommended Scoring Algorithm

The baseline composite score for a candidate agent is:¶

score = W_tag * tagScore
      + W_sem * semanticScore
      + W_rep * reputationScore
      + W_avl * availabilityScore
      + W_rat * ratingScore

The recommended default weights are:¶

Implementations MAY adjust weights based on deployment requirements. The five factors and their semantics are the normative core of this baseline profile; the default numeric weights are RECOMMENDED starting values. Note that reputation, rating, and availability are inherently deployment-specific signals normalized into interoperable [0.0, 1.0] score fields; this specification does not prescribe how those signals are computed. Implementations that diverge from these factors SHOULD document their scoring approach to enable cross-implementation comparison.¶

5.2. Cold Start (Recommended Practice)

New agents with fewer than 5 completed tasks lack sufficient reputation and rating signals. Implementations SHOULD apply a cold-start boost (e.g., adding a fixed reputation bonus) to avoid penalizing new entrants. The boost amount and task threshold are deployment-specific.¶

5.3. Load Filtering (Recommended Practice)

Implementations SHOULD exclude agents whose active task count meets or exceeds their max_concurrent_tasks constraint from discovery results. This prevents routing work to overloaded agents.¶

6.1. Creation

An agent creates its Agent Card by populating at least the "id" and "name" fields. The "metadata.created_at" field SHOULD be set to the current UTC timestamp.¶

6.2. Publication

An agent publishes its Agent Card by:¶

1. Responding to incoming adp.describe requests.¶
2. Proactively sending adp.advertise to known directory agents or peers.¶
3. Using deployment-specific dissemination mechanisms (DHT, GossipSub, HTTP well-known endpoints) as defined by implementation profiles.¶

The minimal publication requirement is (1): agents implementing ADP MUST respond to adp.describe. Proactive advertisement is OPTIONAL and depends on deployment needs.¶

6.3. Freshness and TTL

The "metadata.ttl" field indicates the number of seconds the Agent Card is considered fresh after retrieval. Consumers SHOULD re-fetch the Agent Card after the TTL expires. If no TTL is present, implementations SHOULD apply a deployment-specific default.¶

Each update to the Agent Card SHOULD increment "metadata.updated_at". When the "seq" field (Section 3.2) is present, consumers MUST use "seq" as the authoritative ordering key; "metadata.updated_at" serves as a supplementary human-readable freshness hint. Consumers SHOULD prefer the Agent Card with the higher "seq" (or, if "seq" is absent, the most recent updated_at timestamp) when multiple copies are obtained from different sources.¶

6.4. Revocation

An agent that is no longer available SHOULD publish an Agent Card with an empty "tools" array and an empty "endpoints" array, signaling that it has no callable methods. Consumers SHOULD treat such an Agent Card as a revocation.¶

Deployment-specific mechanisms (e.g., DHT record expiration, GossipSub tombstone messages) provide additional revocation signals but are outside the scope of this document.¶

7.1. Agent Card Authentication

An Agent Card can be spoofed if not authenticated. Implementations SHOULD deliver Agent Cards over AITP associations where the remote agent's identity has been verified (via AIP signature or lower-layer peer authentication).¶

When Agent Cards are disseminated through intermediaries (directory agents, DHT, gossip), the intermediary MUST verify the Agent Card's authorship before storing and serving it. Verification methods include checking that the "id" field matches the AITP source URI of the adp.advertise call, or — preferably — verifying the Ed25519 "signature" field defined in Section 3.2. Implementations SHOULD include "seq" and "signature" in Agent Cards that will be disseminated beyond direct AITP associations.¶

7.2. Capability Enumeration

The tools array and skill tags reveal the methods an agent supports. An adversary can invoke adp.describe to enumerate capabilities and then probe for vulnerabilities in specific methods.¶

Agents concerned with capability enumeration MAY return a partial Agent Card in response to adp.describe from unrecognized or unauthenticated callers, omitting sensitive tools while preserving the required fields (id, name).¶

7.3. Stale Description Attacks

An adversary who has obtained an old Agent Card can replay it to make consumers believe the agent still offers capabilities it has since revoked. The "seq" field (Section 3.2), "metadata.updated_at" timestamp, and "metadata.ttl" fields provide freshness signals. When "seq" and "signature" are present, consumers can cryptographically reject stale cards: a card with a lower "seq" MUST NOT supersede one with a higher "seq" carrying a valid signature. Consumers SHOULD prefer the most recently retrieved Agent Card and SHOULD re-fetch after TTL expiration.¶

7.4. Overcommitment

An agent may advertise capabilities it cannot deliver (false advertising). ADP does not prevent this; companion reputation protocols provide post-hoc accountability. Callers SHOULD verify critical capabilities at invocation time rather than relying solely on the Agent Card.¶

7.5. Privacy

Agent Cards may reveal information about an agent's operational capacity, supported languages, and method inventory. Agents that require privacy SHOULD limit the fields they include in their Agent Card and MAY return different Agent Card subsets to different callers based on authorization level.¶

7.6. Document Size

Agent Cards are carried as AITP request/response bodies, constrained by AIP's maximum message size (65535 octets). Implementations MUST NOT generate Agent Cards larger than 65535 octets. Implementations SHOULD keep Agent Cards compact by omitting unused optional fields rather than including them with empty values.¶

If an Agent Card with all optional fields populated exceeds the AIP maximum message size, implementations SHOULD use one of the mitigation strategies defined in AITP [I-D.song-anp-aitp]: (1) deliver the Agent Card via an AITP STREAM exchange, or (2) use the adp.describe "fields" parameter to request a subset of the Agent Card across multiple REQUEST/RESPONSE round trips. For adp.discover, implementations SHOULD use the "limit" parameter to bound result set size per response.¶

9.1. ClawNet

Organization

ChatChatTech¶

URL

https://github.com/ChatChatTech/ClawNet¶

Description

Go implementation of the full ANP suite. Agent descriptions are currently stored as two structures (config.Profile and store.AgentResume) that map to the Agent Card fields defined in this document. Dissemination uses DHT (clawnet-profile namespace) with Ed25519-signed records and GossipSub (/clawnet/resumes topic) with periodic re-broadcast. Discovery uses a five-factor weighted scoring algorithm (tag match, semantic overlap, reputation, availability, rating) matching Section 5.1. The reference implementation is being updated to unify Profile and Resume into a single Agent Card structure and to register the three ADP methods on AITP.¶

Maturity

Alpha¶

Coverage

Implemented:¶

• Profile and Resume data structures covering all core Agent Card fields¶
• DHT publication with Ed25519 signature verification¶
• GossipSub resume broadcast (5-minute interval)¶
• REST API for profile CRUD (GET/PUT /api/profile)¶
• Five-factor discovery scoring algorithm¶
• 60+ standard skill tags with alias normalization¶
• MCP tool exposure (17 tools)¶

Under integration:¶

• Unified Agent Card struct (merge Profile + Resume)¶
• adp.describe, adp.advertise, adp.discover AITP method handlers¶
• Agent Card signing via metadata proof¶
• HTTP well-known endpoint (/.well-known/agent-card.json)¶

Language

Go¶

License

Open source¶

Contact

ink@chatchat.space¶

A.1. Google A2A AgentCard

A.2. MCP Server Description

MCP defines no output_schema, streaming, or idempotent fields; these are omitted in the MCP projection.¶

A.3. OASF AgentDescriptor

OASF has no reputation, credentials, or streaming fields; these are omitted in the OASF projection. Reverse import from OASF loses only ClawNet-specific extension fields.¶