Independent Submission J. Xu Internet-Draft B. Li Intended status: Informational R. Zhu Expires: 9 November 2026 CAICT 8 May 2026 Metadata and Query Profile for Efficient Agent Discovery draft-xu-efficient-agent-discovery-profile-00 Abstract This document defines a metadata and query profile for efficient discovery of autonomous software agents. The profile describes how agents publish capability metadata using explicit tags, natural- language descriptions, example tasks, protocol bindings, and operational constraints. It also defines JSON metadata, discovery request, and discovery response objects that enable discovery services to combine structured filtering, semantic retrieval, and fine-grained matching while preserving an interoperable protocol surface. The profile does not mandate a specific machine-learning model, embedding model, database, or ranking algorithm. Instead, it standardizes the metadata and result evidence needed by clients and discovery services so that different implementations can interoperate while optimizing their own latency, scalability, and ranking quality. 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 9 November 2026. Xu, et al. Expires 9 November 2026 [Page 1] Internet-Draft Agent Discovery Profile May 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Problem Statement . . . . . . . . . . . . . . . . . . . . 4 1.2. Applicability . . . . . . . . . . . . . . . . . . . . . . 4 1.3. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.4. Non-Goals . . . . . . . . . . . . . . . . . . . . . . . . 5 1.5. Requirements Language . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Profile Overview . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Conformance Levels . . . . . . . . . . . . . . . . . . . 7 4. Agent Metadata . . . . . . . . . . . . . . . . . . . . . . . 7 4.1. Top-Level Fields . . . . . . . . . . . . . . . . . . . . 8 4.2. Identifier and Name . . . . . . . . . . . . . . . . . . . 9 4.3. Description . . . . . . . . . . . . . . . . . . . . . . . 9 4.4. Capability Tags . . . . . . . . . . . . . . . . . . . . . 9 4.5. Example Tasks . . . . . . . . . . . . . . . . . . . . . . 10 4.6. Protocol Bindings . . . . . . . . . . . . . . . . . . . . 10 4.7. Versioning and Extensions . . . . . . . . . . . . . . . . 11 4.8. Status and Freshness . . . . . . . . . . . . . . . . . . 12 4.9. Metadata Example . . . . . . . . . . . . . . . . . . . . 12 5. Discovery Request . . . . . . . . . . . . . . . . . . . . . . 13 5.1. Request Fields . . . . . . . . . . . . . . . . . . . . . 13 5.2. Request Example . . . . . . . . . . . . . . . . . . . . . 14 6. Discovery Response . . . . . . . . . . . . . . . . . . . . . 15 6.1. Response Fields . . . . . . . . . . . . . . . . . . . . . 15 6.2. Score Components . . . . . . . . . . . . . . . . . . . . 17 6.3. Response Example . . . . . . . . . . . . . . . . . . . . 17 7. Discovery Processing Model . . . . . . . . . . . . . . . . . 18 7.1. Index Construction . . . . . . . . . . . . . . . . . . . 19 7.2. Query Processing . . . . . . . . . . . . . . . . . . . . 19 7.3. Example-Level Matching . . . . . . . . . . . . . . . . . 20 7.4. Privacy Defaults and Redaction . . . . . . . . . . . . . 20 8. Matching Evidence . . . . . . . . . . . . . . . . . . . . . . 20 9. Registration and Update Behavior . . . . . . . . . . . . . . 21 10. Federation . . . . . . . . . . . . . . . . . . . . . . . . . 21 11. Interoperability Considerations . . . . . . . . . . . . . . . 22 Xu, et al. Expires 9 November 2026 [Page 2] Internet-Draft Agent Discovery Profile May 2026 12. Error Model . . . . . . . . . . . . . . . . . . . . . . . . . 23 13. Test Vectors . . . . . . . . . . . . . . . . . . . . . . . . 24 13.1. Minimal D0 Metadata . . . . . . . . . . . . . . . . . . 24 13.2. Minimal D1 Query . . . . . . . . . . . . . . . . . . . . 25 13.3. Unsupported Hard Filter . . . . . . . . . . . . . . . . 25 14. Security Considerations . . . . . . . . . . . . . . . . . . . 25 15. Privacy Considerations . . . . . . . . . . . . . . . . . . . 26 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 17. Implementation Status . . . . . . . . . . . . . . . . . . . . 27 18. Implementation Checklist . . . . . . . . . . . . . . . . . . 27 19. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 19.1. Normative References . . . . . . . . . . . . . . . . . . 28 19.2. Informative References . . . . . . . . . . . . . . . . . 28 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 28 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 1. Introduction Agent ecosystems require a way to find suitable agents from large and dynamic candidate sets. Exact lookup by identifier is not sufficient: users and agents often express intent in natural language, while available agents expose capabilities using heterogeneous names, descriptions, tags, examples, protocols, and endpoint metadata. Naive discovery approaches have undesirable trade-offs. Heavy language-model parsing can provide good intent understanding but may add unacceptable latency for interactive or agent-to-agent negotiation. Simple vector search over a single concatenated description can be fast but may dilute important capability details in multi-purpose agents. Keyword search over tags can be efficient but may miss semantically related agents. This document defines an efficient agent discovery profile that separates agent metadata into complementary signals: * explicit capability tags for fast structured filtering; * natural-language descriptions for broad semantic matching; * example tasks for fine-grained intent matching; * protocol and endpoint bindings for reachability; and * operational constraints for safe candidate selection. Xu, et al. Expires 9 November 2026 [Page 3] Internet-Draft Agent Discovery Profile May 2026 The profile standardizes what agents publish and what discovery services return. Discovery services remain free to implement tag indices, dense vector indices, example-level matching, neural routers, symbolic rules, or hybrid approaches. 1.1. Problem Statement Agent discovery has two competing requirements. It must be expressive enough to match natural-language task intent against heterogeneous agents, and it must be concrete enough that independent implementations can exchange metadata and queries without sharing the same ranking engine. Existing mechanisms can publish web resources, service descriptors, or tool manifests, but they do not by themselves define the discovery-specific combination of capability tags, broad descriptions, example tasks, freshness, matching evidence, and ranked responses used by this profile. Without a common profile, discovery services either expose platform-specific metadata or return opaque rankings that clients cannot validate, debug, or compare. This document therefore standardizes the metadata and query surface, not the internal retrieval implementation. 1.2. Applicability This profile is applicable to registries, directories, marketplaces, gateways, or local discovery services that need to return candidate agents for a task intent. It is not intended to replace exact identifier resolution, endpoint security, or post-discovery invocation protocols. 1.3. Goals This profile has the following goals: * define an agent metadata object suitable for high-performance discovery; * support both structured filtering and natural-language intent search; * preserve fine-grained capability signals for multi-purpose agents; * define discovery request and response fields that are independent of any particular ranking algorithm; Xu, et al. Expires 9 November 2026 [Page 4] Internet-Draft Agent Discovery Profile May 2026 * allow discovery results to include matching evidence and confidence signals; * support incremental metadata updates; and * provide security and privacy guidance for discovery services. 1.4. Non-Goals This profile does not define: * a new transport protocol; * a new URI scheme; * a mandatory registry topology; * a mandatory ranking formula; * a mandatory embedding model, language model, or vector database; * a reputation system; or * an invocation protocol for executing tasks after discovery. 1.5. 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. 2. Terminology Agent: An autonomous or semi-autonomous software system that exposes one or more capabilities and can be selected for invocation. Agent Metadata: A structured object that describes an agent's identity, capabilities, examples, protocol bindings, and operational constraints. Capability Tag: A short normalized label that identifies a capability, domain, industry, task type, or other discovery- relevant property. Context Description: A natural-language description of an agent's purpose, scope, and supported tasks. Xu, et al. Expires 9 November 2026 [Page 5] Internet-Draft Agent Discovery Profile May 2026 Discovery Request: A request sent by a client or agent to a discovery service to obtain candidate agents. Discovery Response: A response containing ranked candidate agents and matching evidence. Example Task: A short natural-language example of a user request, agent-to-agent request, or task pattern that the agent is intended to handle. Matching Evidence: Data returned by a discovery service to explain why a candidate was selected, such as matched tags, matched examples, score components, or policy filters. 3. Profile Overview The profile has two interoperable surfaces: * the Agent Metadata object, published by agents or registries; and * the Discovery Request and Discovery Response objects, exchanged between clients and discovery services. The canonical field names and examples in this profile use JSON [RFC8259]. Other serializations MAY be used by a transport or registry binding only when the binding defines an unambiguous mapping for field names, value types, arrays, objects, and unknown-field behavior. The following figure shows a typical implementation. It is illustrative, not normative. metadata publication Agent ----------------------------> Discovery Service \ | \ | builds indices \ v \ +-------------+ \ | tag index | \ | context idx | \ | example idx | \ +-------------+ \ \ discovery request v Client ---------------------------> Discovery Service Client <--------------------------- ranked candidates response with matching evidence Xu, et al. Expires 9 November 2026 [Page 6] Internet-Draft Agent Discovery Profile May 2026 The discovery service MAY build separate internal indices from the same metadata. For example, it might build an inverted index for tags, an embedding index for descriptions, and an example-level index for task examples. These internal structures are not part of the wire profile. 3.1. Conformance Levels This profile defines three conformance levels for incremental adoption. +=======+================+===============================+ | Level | Name | Requirements | +=======+================+===============================+ | D0 | Metadata | Publish Agent Metadata with | | | | id, name, description, and at | | | | least one bindings entry. | +-------+----------------+-------------------------------+ | D1 | Structured | Support Discovery Requests | | | Discovery | with tag and protocol filters | | | | and return ranked candidates. | +-------+----------------+-------------------------------+ | D2 | Evidence-Based | Return matching evidence, | | | Discovery | freshness data, and score | | | | components when requested. | +-------+----------------+-------------------------------+ Table 1 Implementations SHOULD state the highest level they support. A D2 discovery service MUST also satisfy D0 and D1. Clients SHOULD tolerate lower levels but MUST NOT assume that a D0 publisher supports query processing. 4. Agent Metadata An Agent Metadata object describes an agent for discovery. It MUST be a single JSON object unless another serialization is explicitly selected by a binding profile that preserves the data model defined in this document. Xu, et al. Expires 9 November 2026 [Page 7] Internet-Draft Agent Discovery Profile May 2026 4.1. Top-Level Fields +=============+==========+=============+============================+ | Field | Type | Requirement | Description | +=============+==========+=============+============================+ | id | string | MUST | Stable identifier of the | | | | | agent | +-------------+----------+-------------+----------------------------+ | name | string | MUST | Human-readable name | +-------------+----------+-------------+----------------------------+ | description | string | MUST | Natural-language context | | | | | description | +-------------+----------+-------------+----------------------------+ | tags | array of | SHOULD | Normalized capability | | | string | | tags | +-------------+----------+-------------+----------------------------+ | examples | array of | SHOULD | Example tasks or request | | | object | | patterns | +-------------+----------+-------------+----------------------------+ | bindings | array of | MUST | Protocol and endpoint | | | object | | bindings | +-------------+----------+-------------+----------------------------+ | auth | object | SHOULD | Authentication | | | | | requirements | +-------------+----------+-------------+----------------------------+ | constraints | object | MAY | Region, policy, cost, | | | | | rate, or data constraints | +-------------+----------+-------------+----------------------------+ | status | string | SHOULD | Operational status | +-------------+----------+-------------+----------------------------+ | expires_at | string | MAY | Time after which the | | | | | record should be | | | | | refreshed | +-------------+----------+-------------+----------------------------+ | version | string | SHOULD | Metadata version or | | | | | capability version | +-------------+----------+-------------+----------------------------+ | updated_at | string | SHOULD | Timestamp for freshness | | | | | checks | +-------------+----------+-------------+----------------------------+ | signature | object | MAY | Signature or credential | | | | | binding metadata | +-------------+----------+-------------+----------------------------+ Table 2 Xu, et al. Expires 9 November 2026 [Page 8] Internet-Draft Agent Discovery Profile May 2026 Field names are case-sensitive. Implementations SHOULD ignore unknown fields for forward compatibility, but MUST preserve unknown fields when acting as a transparent metadata relay. 4.2. Identifier and Name The id field MUST be stable for the lifecycle of the agent registration. It MAY be a URI, DNS-based name, registry-local identifier, or another profile-defined identifier. This profile does not define or reserve a new URI scheme; when URIs are used, their schemes are defined outside this document. Discovery services MUST NOT assume that the human-readable name field is globally unique. 4.3. Description The description field provides broad semantic context. It SHOULD describe: * the agent's primary purpose; * supported domains; * important input and output types; * operational limitations; and * safety or policy-relevant boundaries. Descriptions SHOULD be written for discovery and interoperability, not marketing. They SHOULD avoid unsupported superlatives such as "best", "perfect", or "guaranteed". 4.4. Capability Tags The tags field contains normalized labels. Tags SHOULD be selected from one or more declared taxonomies when possible. Tags SHOULD be concise, lowercase, and stable. A tag SHOULD represent a capability, domain, task family, data type, industry, protocol, or language. Examples: ["translation", "finance", "invoice-processing", "json-output"] Discovery services MAY expand tags using taxonomy relationships or synonym maps. If expansion is used, the response SHOULD distinguish directly matched tags from expanded or inferred tags. Xu, et al. Expires 9 November 2026 [Page 9] Internet-Draft Agent Discovery Profile May 2026 4.5. Example Tasks The examples field preserves fine-grained capability signals. Each example SHOULD describe a concrete task the agent can handle. +===============+==========+=============+==================+ | Field | Type | Requirement | Description | +===============+==========+=============+==================+ | id | string | SHOULD | Stable example | | | | | identifier | +---------------+----------+-------------+------------------+ | text | string | MUST | Example task or | | | | | request | +---------------+----------+-------------+------------------+ | tags | array of | MAY | Tags associated | | | string | | with the example | +---------------+----------+-------------+------------------+ | input_schema | object | MAY | Expected input | | | | | shape | +---------------+----------+-------------+------------------+ | output_schema | object | MAY | Expected output | | | | | shape | +---------------+----------+-------------+------------------+ | language | string | MAY | Language tag | +---------------+----------+-------------+------------------+ Table 3 Example tasks SHOULD be specific. For a multi-purpose agent, publishers SHOULD include examples for distinct capability modes rather than averaging all capabilities into one broad description. 4.6. Protocol Bindings The bindings field tells a client how the agent can be contacted or invoked after discovery. Xu, et al. Expires 9 November 2026 [Page 10] Internet-Draft Agent Discovery Profile May 2026 +===================+=========+=============+====================+ | Field | Type | Requirement | Description | +===================+=========+=============+====================+ | protocol | string | MUST | Protocol | | | | | identifier defined | | | | | by the selected | | | | | binding profile, | | | | | such as https | +-------------------+---------+-------------+--------------------+ | endpoint | string | MUST | Endpoint reference | | | | | or URI | +-------------------+---------+-------------+--------------------+ | media_types | array | MAY | Supported request | | | of | | or response media | | | string | | types | +-------------------+---------+-------------+--------------------+ | interaction_model | string | MAY | request-response, | | | | | streaming, batch, | | | | | or profile-defined | | | | | value | +-------------------+---------+-------------+--------------------+ | priority | integer | MAY | Preference order | | | | | among bindings | +-------------------+---------+-------------+--------------------+ Table 4 Discovery clients MUST verify that a binding is acceptable under local policy before invocation. 4.7. Versioning and Extensions Metadata publishers SHOULD include a version field and SHOULD update it whenever the meaning of capabilities, examples, or bindings changes. Unknown top-level fields MUST be ignored by discovery services unless local policy requires strict validation. Unknown fields in nested objects SHOULD also be ignored. Implementations that relay metadata SHOULD preserve unknown fields unless doing so conflicts with privacy or policy requirements. Private extension fields SHOULD use collision-resistant names, such as reverse-DNS names or URIs. Extensions that affect ranking, authorization, or wire compatibility SHOULD be documented in a stable specification. Xu, et al. Expires 9 November 2026 [Page 11] Internet-Draft Agent Discovery Profile May 2026 4.8. Status and Freshness The status field SHOULD use one of: * active * inactive * suspended * deprecated * testing The updated_at or version field SHOULD be used to reject stale metadata. Discovery services SHOULD expose when a result was indexed and whether the source metadata is older than a client-supplied freshness constraint. If expires_at is present, discovery services SHOULD stop returning the record after that time unless local policy explicitly allows stale results. Publishers SHOULD refresh records before expiration and SHOULD use random jitter for large fleets to avoid synchronized refresh bursts. 4.9. Metadata Example Xu, et al. Expires 9 November 2026 [Page 12] Internet-Draft Agent Discovery Profile May 2026 { "id": "https://agents.example.net/id/hr-core-automator", "name": "HR Core Automator", "description": "Optimizes HR workflows and onboarding checks.", "tags": ["hr", "workflow", "onboarding", "hcm", "api-automation"], "examples": [ { "id": "ex-1", "text": "Prepare a new-employee onboarding workflow.", "tags": ["onboarding", "workflow"] }, { "id": "ex-2", "text": "Check an employee record for missing payroll fields.", "tags": ["employee-record", "validation"] } ], "bindings": [ { "protocol": "https", "endpoint": "https://agents.example.net/hr-core/invoke", "media_types": ["application/json"], "interaction_model": "request-response" } ], "status": "active", "version": "1.0.0", "updated_at": "2026-05-08T00:00:00Z" } 5. Discovery Request A Discovery Request asks a discovery service to return candidate agents. It MUST be a single JSON object unless another serialization is explicitly selected by a binding profile that preserves the data model defined in this document. 5.1. Request Fields +==================+=========+=============+=======================+ | Field | Type | Requirement | Description | +==================+=========+=============+=======================+ | query | string | MUST | Natural-language | | | | | intent or task | | | | | description | +------------------+---------+-------------+-----------------------+ | required_tags | array | MAY | Tags that candidates | | | of | | must satisfy | Xu, et al. Expires 9 November 2026 [Page 13] Internet-Draft Agent Discovery Profile May 2026 | | string | | | +------------------+---------+-------------+-----------------------+ | preferred_tags | array | MAY | Tags that increase | | | of | | ranking score | | | string | | | +------------------+---------+-------------+-----------------------+ | excluded_tags | array | MAY | Tags that candidates | | | of | | must not contain | | | string | | | +------------------+---------+-------------+-----------------------+ | protocols | array | MAY | Acceptable protocols | | | of | | | | | string | | | +------------------+---------+-------------+-----------------------+ | constraints | object | MAY | Policy, region, cost, | | | | | latency, or freshness | | | | | constraints | +------------------+---------+-------------+-----------------------+ | limit | integer | MAY | Maximum number of | | | | | candidates | +------------------+---------+-------------+-----------------------+ | include_evidence | boolean | MAY | Whether matching | | | | | evidence is requested | +------------------+---------+-------------+-----------------------+ | detail | string | MAY | minimal, summary, or | | | | | full response detail | +------------------+---------+-------------+-----------------------+ | client_context | object | MAY | Client-side hints | | | | | such as locale or | | | | | domain | +------------------+---------+-------------+-----------------------+ Table 5 A discovery service MUST apply required_tags and excluded_tags as hard filters when it supports the corresponding taxonomy. If it cannot apply a hard filter, it MUST report that limitation in the response. The detail field controls metadata minimization. A value of minimal requests only identifiers, status, and enough endpoint data to continue resolution. A value of summary requests the normal candidate summary. A value of full requests complete metadata where policy permits. Discovery services MAY redact fields even when full is requested. 5.2. Request Example Xu, et al. Expires 9 November 2026 [Page 14] Internet-Draft Agent Discovery Profile May 2026 { "query": "Find an agent for onboarding validation and API setup.", "required_tags": ["hr"], "preferred_tags": ["onboarding", "api-automation"], "protocols": ["https"], "constraints": { "max_results_age_seconds": 300, "region": "apac" }, "limit": 10, "detail": "summary", "include_evidence": true } 6. Discovery Response A Discovery Response contains ranked candidates. It MUST be a single JSON object unless another serialization is explicitly selected by a binding profile that preserves the data model defined in this document. 6.1. Response Fields +=====================+========+=============+=====================+ | Field | Type | Requirement | Description | +=====================+========+=============+=====================+ | request_id | string | SHOULD | Identifier for | | | | | tracing the request | +---------------------+--------+-------------+---------------------+ | candidates | array | MUST | Ranked candidate | | | of | | agents | | | object | | | +---------------------+--------+-------------+---------------------+ | applied_filters | object | SHOULD | Filters applied by | | | | | the discovery | | | | | service | +---------------------+--------+-------------+---------------------+ | unsupported_filters | array | MAY | Filters the service | | | of | | could not apply | | | string | | | +---------------------+--------+-------------+---------------------+ | warnings | array | MAY | Limitations or | | | of | | policy warnings | | | string | | | +---------------------+--------+-------------+---------------------+ | generated_at | string | SHOULD | Response generation | | | | | timestamp | +---------------------+--------+-------------+---------------------+ Xu, et al. Expires 9 November 2026 [Page 15] Internet-Draft Agent Discovery Profile May 2026 Table 6 Each candidate object SHOULD include: +==================+==========+=============+=======================+ | Field | Type | Requirement | Description | +==================+==========+=============+=======================+ | id | string | MUST | Agent identifier | +------------------+----------+-------------+-----------------------+ | name | string | SHOULD | Human-readable | | | | | name | +------------------+----------+-------------+-----------------------+ | description | string | SHOULD | Short description | | | | | or summary | +------------------+----------+-------------+-----------------------+ | bindings | array of | SHOULD | Usable protocol | | | object | | bindings | +------------------+----------+-------------+-----------------------+ | score | number | SHOULD | Overall ranking | | | | | score | +------------------+----------+-------------+-----------------------+ | score_components | object | MAY | Structured score | | | | | details | +------------------+----------+-------------+-----------------------+ | matched_tags | array of | MAY | Tags matched | | | string | | directly or by | | | | | expansion | +------------------+----------+-------------+-----------------------+ | matched_examples | array of | MAY | Examples that | | | object | | matched the query | +------------------+----------+-------------+-----------------------+ | credential_refs | array of | MAY | References for | | | string | | verification | +------------------+----------+-------------+-----------------------+ | redacted | boolean | MAY | Whether fields | | | | | were omitted by | | | | | policy | +------------------+----------+-------------+-----------------------+ | status | string | SHOULD | Operational | | | | | status | +------------------+----------+-------------+-----------------------+ | freshness | object | SHOULD | Index and | | | | | metadata | | | | | freshness | +------------------+----------+-------------+-----------------------+ Table 7 Xu, et al. Expires 9 November 2026 [Page 16] Internet-Draft Agent Discovery Profile May 2026 Scores are local to the discovery service. Clients MUST NOT compare scores from different discovery services unless a common scoring profile is explicitly defined. 6.2. Score Components When score_components is returned, the following component names are RECOMMENDED: +===========+=================================================+ | Component | Meaning | +===========+=================================================+ | tag | Match between query-derived tags and agent tags | +-----------+-------------------------------------------------+ | context | Semantic match against descriptions or broad | | | context text | +-----------+-------------------------------------------------+ | example | Match against one or more example tasks | +-----------+-------------------------------------------------+ | protocol | Compatibility with requested protocol bindings | +-----------+-------------------------------------------------+ | freshness | Penalty or bonus based on metadata age | +-----------+-------------------------------------------------+ | policy | Local policy, trust, region, or entitlement | | | signal | +-----------+-------------------------------------------------+ Table 8 Implementations MAY add deployment-specific components. Unknown components MUST be ignored by clients that do not understand them. 6.3. Response Example Xu, et al. Expires 9 November 2026 [Page 17] Internet-Draft Agent Discovery Profile May 2026 { "request_id": "req-123", "generated_at": "2026-05-08T00:00:01Z", "applied_filters": { "required_tags": ["hr"], "protocols": ["https"] }, "candidates": [ { "id": "https://agents.example.net/id/hr-core-automator", "name": "HR Core Automator", "description": "Optimizes onboarding workflows.", "bindings": [ { "protocol": "https", "endpoint": "https://agents.example.net/hr-core/invoke" } ], "score": 0.91, "score_components": { "tag": 0.95, "context": 0.83, "example": 0.96 }, "matched_tags": ["hr", "onboarding", "api-automation"], "matched_examples": [ { "id": "ex-1", "score": 0.96, "text": "Prepare a new-employee onboarding workflow." } ], "status": "active", "freshness": { "metadata_updated_at": "2026-05-08T00:00:00Z", "indexed_at": "2026-05-08T00:00:00Z" } } ] } 7. Discovery Processing Model This section describes a recommended processing model. It is not mandatory, but it explains how the metadata fields in this profile support efficient discovery. Xu, et al. Expires 9 November 2026 [Page 18] Internet-Draft Agent Discovery Profile May 2026 7.1. Index Construction A discovery service can build three complementary indices: Tag index: An inverted index from capability tag to agent identifiers. This supports fast filtering and high-recall candidate generation. Context index: A semantic index over descriptions, generated summaries, or other broad context fields. This supports natural- language recall when user wording differs from tags. Example index: A fine-grained index over individual example tasks. This preserves distinct capability modes for multi-purpose agents. Discovery services MAY augment descriptions with synthetic queries or other derived text. If derived text materially affects ranking, implementations SHOULD retain provenance so that debugging and abuse review are possible. 7.2. Query Processing A discovery service following the recommended model processes a request as follows: 1. Validate the request and apply authentication or rate limits. 2. Normalize tags and constraints against supported taxonomies. 3. Derive query features, such as predicted tags, query embeddings, or symbolic constraints. 4. Retrieve candidates from the tag index and context index. 5. Merge and deduplicate candidates. 6. Re-rank candidates using example-level, policy, freshness, and operational signals. 7. Return candidates with matching evidence and warnings. The service SHOULD bound the number of candidates entering expensive re-ranking stages. The service SHOULD return partial results with warnings when a non-critical ranking component is unavailable. Xu, et al. Expires 9 November 2026 [Page 19] Internet-Draft Agent Discovery Profile May 2026 7.3. Example-Level Matching For multi-purpose agents, example-level matching is RECOMMENDED. The service SHOULD preserve separate example vectors or features rather than representing all examples only as one averaged vector. This allows a query to match one specific capability even when the agent has other unrelated capabilities. A discovery service MAY compute the final score using a weighted combination of tag, context, example, freshness, and policy components. This document does not define the weights. 7.4. Privacy Defaults and Redaction Discovery services SHOULD minimize results by default. Unless detail=full is requested and authorized, responses SHOULD omit sensitive endpoint details, private examples, internal system names, billing hints, and non-public credential references. If fields are omitted due to policy, the candidate SHOULD include "redacted": true and the response SHOULD include a warning or policy reason when doing so does not reveal sensitive information. 8. Matching Evidence Matching evidence helps clients decide whether a result is useful and helps operators debug search behavior. When include_evidence is true, a discovery response SHOULD include at least one of: * matched tags; * matched examples; * matched description snippets; * score components; * applied filters; * rejected hard constraints; or * freshness indicators. Evidence MUST NOT disclose private metadata or private user queries from other clients. Xu, et al. Expires 9 November 2026 [Page 20] Internet-Draft Agent Discovery Profile May 2026 9. Registration and Update Behavior Discovery quality depends on fresh metadata. Registries or agents SHOULD submit incremental updates when: * endpoints change; * protocol bindings change; * capability tags change; * examples are added or removed; * operational status changes; or * credentials are revoked or renewed. Discovery services SHOULD support sequence numbers, timestamps, entity tags, or equivalent freshness mechanisms. A stale update MUST NOT replace a newer record. Registrations SHOULD be idempotent on (id, binding endpoint) or another profile-defined stable key. Re-sending the same key with newer freshness data SHOULD be treated as a refresh. Re-sending the same id with conflicting ownership or incompatible bindings SHOULD produce a conflict error. 10. Federation Discovery services MAY federate results from other discovery services or registries. Federated results MUST include provenance sufficient for a client or local policy engine to determine the origin of the data. Federated candidate metadata SHOULD include: Xu, et al. Expires 9 November 2026 [Page 21] Internet-Draft Agent Discovery Profile May 2026 +==================+=================================+ | Field | Description | +==================+=================================+ | origin_service | Discovery or registry service | | | that supplied the record | +------------------+---------------------------------+ | origin_authority | Authority or domain responsible | | | for the record | +------------------+---------------------------------+ | origin_signature | Signature or reference covering | | | the transferred metadata | +------------------+---------------------------------+ | received_at | Time the local discovery | | | service received the record | +------------------+---------------------------------+ Table 9 Federation MUST NOT remove freshness, redaction, or credential information that a client needs to make a trust decision. 11. Interoperability Considerations This profile is intended to map cleanly to existing agent metadata formats. Where another format already defines fields such as agent cards, tool lists, OpenAPI descriptions, or protocol-specific manifests, implementers SHOULD map those fields into description, tags, examples, bindings, and constraints rather than duplicating incompatible metadata. The following mapping is typical: Xu, et al. Expires 9 November 2026 [Page 22] Internet-Draft Agent Discovery Profile May 2026 +===============================+===============+ | Source Concept | Profile Field | +===============================+===============+ | Agent card name | name | +-------------------------------+---------------+ | Agent card description | description | +-------------------------------+---------------+ | Skill or capability list | tags | +-------------------------------+---------------+ | Tool examples or prompts | examples | +-------------------------------+---------------+ | Endpoint or transport binding | bindings | +-------------------------------+---------------+ | Authentication metadata | auth | +-------------------------------+---------------+ | Rate or region limits | constraints | +-------------------------------+---------------+ Table 10 12. Error Model If this profile is carried over a request/response protocol, errors SHOULD be returned as structured objects containing: +================+=============+====================================+ | Field | Requirement | Description | +================+=============+====================================+ | code | MUST | Stable machine- | | | | readable error code | +----------------+-------------+------------------------------------+ | message | SHOULD | Human-readable | | | | explanation | +----------------+-------------+------------------------------------+ | correlation_id | SHOULD | Identifier for | | | | tracing and support | +----------------+-------------+------------------------------------+ | retry_after | MAY | Suggested retry | | | | delay | +----------------+-------------+------------------------------------+ Table 11 The following error codes are RECOMMENDED: Xu, et al. Expires 9 November 2026 [Page 23] Internet-Draft Agent Discovery Profile May 2026 +====================+=====================================+ | Code | Meaning | +====================+=====================================+ | invalid_request | Required field missing or malformed | +--------------------+-------------------------------------+ | unsupported_filter | The service cannot apply a | | | requested hard filter | +--------------------+-------------------------------------+ | unauthorized | Authentication is required or | | | failed | +--------------------+-------------------------------------+ | forbidden | Authenticated client lacks | | | permission | +--------------------+-------------------------------------+ | conflict | Registration conflicts with an | | | existing record | +--------------------+-------------------------------------+ | not_found | Requested agent or record was not | | | found | +--------------------+-------------------------------------+ | stale_metadata | Candidate or registration failed | | | freshness checks | +--------------------+-------------------------------------+ | rate_limited | Client exceeded rate or quota | | | limits | +--------------------+-------------------------------------+ Table 12 HTTP bindings, if used, SHOULD map these errors to conventional HTTP status codes such as 400, 401, 403, 404, 409, 410, 429, and 503, using the semantics defined for HTTP status codes in [RFC9110]. 13. Test Vectors This section is non-normative. The following examples can be used as minimal parser and interoperation tests. 13.1. Minimal D0 Metadata Xu, et al. Expires 9 November 2026 [Page 24] Internet-Draft Agent Discovery Profile May 2026 { "id": "https://example.net/agents/minimal", "name": "Minimal Agent", "description": "Answers short factual questions.", "bindings": [ { "protocol": "https", "endpoint": "https://example.net/agent/invoke" } ] } An implementation claiming D0 support MUST accept this object as valid metadata, assuming the identifier and endpoint scheme are allowed by local policy. 13.2. Minimal D1 Query { "query": "answer a short factual question", "protocols": ["https"], "limit": 1 } A D1 discovery service receiving this query SHOULD return zero or more candidates and MUST NOT require include_evidence. 13.3. Unsupported Hard Filter { "query": "find a translation agent", "required_tags": ["translation"], "constraints": { "unsupported_private_filter": "example" } } If the service treats unsupported_private_filter as a hard filter and cannot apply it, the service MUST either fail the request or include the filter name in unsupported_filters. 14. Security Considerations Discovery is security-sensitive. A malicious discovery result can steer a client to an attacker-controlled agent. Metadata authenticity: Clients SHOULD verify signatures, Xu, et al. Expires 9 November 2026 [Page 25] Internet-Draft Agent Discovery Profile May 2026 credentials, or registry attestations before invoking an agent returned by discovery. Capability fraud: Agents can exaggerate descriptions, tags, or examples. Discovery services SHOULD distinguish self-asserted metadata from verified metadata. Prompt injection in metadata: Descriptions and examples are untrusted text. Discovery services using language models MUST prevent metadata from overriding system instructions, leaking private data, or changing ranking policies outside the intended processing path. Ranking manipulation: Attackers may stuff tags, generate misleading examples, or create many similar agents. Discovery services SHOULD apply abuse detection, duplicate detection, rate limits, and provenance checks. Stale or revoked results: Discovery services SHOULD expose freshness data. Clients MUST check revocation and endpoint validity before invocation. Federation trust: Federated discovery can amplify false metadata. Discovery services MUST preserve origin and signature information and SHOULD apply local trust policy before merging remote candidates into local results. Filter bypass: A discovery service that silently ignores unsupported hard filters can return unsafe candidates. Services MUST report unsupported hard filters in unsupported_filters or fail the request. Sensitive intent leakage: Discovery requests can reveal user goals. Discovery services MUST protect requests in transit and SHOULD minimize retention. Result authorization: A discovery response is not an authorization decision. The target agent MUST still enforce its own access control policy. 15. Privacy Considerations Agent metadata may reveal private business capabilities. Publishers SHOULD avoid exposing internal system names, customer identifiers, private schemas, or secrets in descriptions and examples. Discovery services SHOULD evaluate these risks using the general privacy guidance for Internet protocols in [RFC6973]. Xu, et al. Expires 9 November 2026 [Page 26] Internet-Draft Agent Discovery Profile May 2026 Example tasks can reveal sensitive use cases. Publishers SHOULD provide representative but sanitized examples. Discovery services SHOULD minimize query logging, support deletion or retention policies, and avoid using private discovery requests to train models without explicit authorization. 16. IANA Considerations This document defines profile-local field names, string values, and error codes only. It does not create new registries, media types, URI schemes, HTTP fields, or protocol parameter values. It makes no IANA requests. 17. Implementation Status This section is to be removed before publication as an RFC. Prototype discovery systems can implement this profile using a tag inverted index, a dense context index over descriptions, and an example-level semantic index. Small specialized classifiers or other fast routing models may be used to predict tags, but such models are not required for interoperability. 18. Implementation Checklist An implementation can be reviewed against the following checklist: * supported conformance level; * accepted metadata serialization; * required and optional fields validated; * unknown-field behavior documented; * freshness and expiration checks implemented; * hard-filter failure behavior implemented; * score components documented; * redaction behavior documented; * federation provenance preserved; and * security controls for metadata injection and ranking abuse documented. Xu, et al. Expires 9 November 2026 [Page 27] Internet-Draft Agent Discovery Profile May 2026 19. References 19.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, . 19.2. Informative References [RFC6973] Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M., and R. Smith, "Privacy Considerations for Internet Protocols", RFC 6973, DOI 10.17487/RFC6973, July 2013, . [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, . Appendix A. Acknowledgements The authors thank participants in discussions on agent discovery, metadata profiles, and efficient retrieval for large agent ecosystems. Authors' Addresses Jinliang Xu CAICT No. 52, Huayuan North Road Beijing Haidian District, 100191 China Email: xujinliang@caict.ac.cn Xu, et al. Expires 9 November 2026 [Page 28] Internet-Draft Agent Discovery Profile May 2026 Bingqi Li CAICT No. 52, Huayuan North Road Beijing Haidian District, 100191 China Email: libingqi@caict.ac.cn Runkai Zhu CAICT No. 52, Huayuan North Road Beijing Haidian District, 100191 China Email: zhurunkai@caict.ac.cn Xu, et al. Expires 9 November 2026 [Page 29]