| Internet-Draft | Agent Discovery Profile | November 2026 |
| Xu, et al. | Expires 19 May 2027 | [Page] |
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.¶
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 19 May 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.¶
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.¶
Discovery implementations trade retrieval cost against expressiveness. Tag filtering, semantic description matching, and example-level matching provide complementary signals without requiring a shared ranking engine.¶
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.¶
The profile standardizes published metadata and query results, not their internal indices or ranking implementation.¶
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.¶
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.¶
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;¶
allow discovery results to include matching evidence and confidence signals;¶
support incremental metadata updates; and¶
provide security and privacy guidance for discovery services.¶
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.¶
An autonomous or semi-autonomous software system that exposes one or more capabilities and can be selected for invocation.¶
A structured object that describes an agent's identity, capabilities, examples, protocol bindings, and operational constraints.¶
A short normalized label that identifies a capability, domain, industry, task type, or other discovery-relevant property.¶
A natural-language description of an agent's purpose, scope, and supported tasks.¶
A request sent by a client or agent to a discovery service to obtain candidate agents.¶
A response containing ranked candidate agents and matching evidence.¶
A short natural-language example of a user request, agent-to-agent request, or task pattern that the agent is intended to handle.¶
Data returned by a discovery service to explain why a candidate was selected, such as matched tags, matched examples, score components, or policy filters.¶
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 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 base profile defines the objects and processing semantics below, not an HTTP endpoint or publication transport. A binding supplies transport framing, profile identification, authentication, and applicable limits. Peers select it by configuration or negotiation; unsupported required bindings fail explicitly. Extensions add fields or constraints with defined semantics; local policy can restrict disclosure or use, but cannot relax hard filters. JSON examples are illustrative objects, not cryptographic test vectors.¶
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
¶
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.¶
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 Discovery | Support Discovery Requests with tag and protocol filters and return ranked candidates. |
| D2 | Evidence-Based Discovery | Support D1 and return matching evidence and freshness data when requested; include score components when computed and disclosable. |
Implementations SHOULD state the highest level they support. A D2 discovery service MUST accept D0 metadata and support D1 queries; it need not operate a publisher. Clients MAY use lower levels when local policy permits, but MUST NOT assume that a D0 publisher supports query processing. These levels are functional contracts, not security or ranking-quality certifications.¶
For a D2 service, include_evidence=true MUST produce at least one applicable
matching-evidence item and source freshness information for each returned
candidate. If access policy prevents disclosure, the service MUST omit that
candidate with a coverage warning or return an error, rather than claim that
the requested D2 evidence was supplied.¶
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.¶
| 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 string | SHOULD | Normalized capability tags |
| examples | array of object | SHOULD | Example tasks or request patterns |
| bindings | array of object | MUST | Protocol and endpoint 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 | Expiry time; later results must be identified as stale |
| version | string | SHOULD | Metadata version or capability version |
| updated_at | string | SHOULD | Timestamp for freshness checks |
| signature | object | MAY | Signature or credential binding metadata |
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.¶
This forward-compatibility rule applies to non-critical fields. The critical
extension rules below take precedence for decisions depending on an extension.
Required fields MUST NOT be null or of a different type. Optional null values
are invalid unless an extension explicitly defines their meaning. Missing
optional arrays mean no additional entries; an empty bindings array does not
satisfy D0. Absence of assurance data does not mean that a claim was verified.¶
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.¶
Identifiers MUST be compared as exact strings unless a shared identifier binding specifies another rule; arbitrary case folding or URL rewriting is not permitted. Scoped identifiers require an agreed namespace and issuance scope. An optional external-identifier association extension can retain a native value, namespace or issuance scope, relationship type, and evidence reference. A resolver location is not by itself proof of either namespace authority or ownership. Locally scoped values need their original scope to avoid collisions.¶
An association declaration is not necessarily an identity-equivalence claim. Matching external identifiers MUST NOT alone merge ownership or authorization records. Extensions using DID-specific equivalence terms MUST follow those terms' applicable specifications rather than infer equivalence from an alias.¶
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".¶
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 string | MAY | Tags associated with the example |
| input_schema | object | MAY | Expected input shape |
| output_schema | object | MAY | Expected output shape |
| language | string | MAY | Language tag |
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.¶
The bindings field tells a client how the agent can be contacted or invoked
after discovery.¶
| Field | Type | Requirement | Description |
|---|---|---|---|
| protocol | string | MUST | Case-sensitive protocol token; https denotes an HTTPS endpoint |
| endpoint | string | MUST | Endpoint reference or URI |
| media_types | array of string | MAY | Supported request or response media types |
| interaction_model | string | MAY |
request-response, streaming, batch, or profile-defined value |
| priority | integer | MAY | Non-negative preference value; lower values preferred, ties unordered |
An https binding uses an absolute HTTPS URI as its endpoint; application
operations and authentication still require the endpoint's native contract.
Other tokens require a shared binding defining their meaning. An unknown token
can be retained as metadata, but MUST NOT be invoked without that contract.
Missing priority expresses no preference.¶
Discovery clients MUST verify that a binding is acceptable under local policy before invocation.¶
Binding extensions MAY advertise protocol versions, supported operations, and security profile identifiers. Transport support, mutual authentication, terminal stream integrity, and per-event authentication are separate claims. Clients MUST NOT infer one from another. A security claim's publisher and verification scope remain subject to the provenance rules below. This profile does not define the corresponding handshake or invocation protocol.¶
The auth object describes access requirements, not an access grant, and MUST
NOT contain reusable secrets. A binding locates an interaction with this
agent; an independently versioned Skill or descriptor is not automatically a
callable endpoint. Optional typed relations can reference such objects without
reducing their identity and version to an unqualified tag.¶
Metadata publishers SHOULD include a version field and SHOULD update it
whenever the meaning of capabilities, examples, or bindings changes.¶
The base profile has no in-object declaration of critical extensions. Its unknown fields are non-critical and follow the compatibility rule above. An extension profile needing mandatory processing MUST provide an explicit profile-selection or criticality mechanism understood before those objects are accepted. A receiver MUST reject an unsupported required profile rather than process its object as a base-profile object. An unknown constraint remains an unsupported hard filter, not a ranking preference.¶
A transparent relay MUST preserve the signed representation, including unknown signed fields. Redaction or transformation is permitted when required by policy, but the relay MUST NOT claim that an original signature covers the transformed object. It can instead provide a verifiable reference to the original object and separately identify its derived summary.¶
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.¶
Timestamp fields use RFC 3339 [RFC3339] date-time strings with a UTC offset. Receivers compare instants, not lexical spellings. The applicable binding defines acceptable clock tolerance.¶
The status field SHOULD use one of:¶
The version field identifies a source revision, but arbitrary version strings
are not necessarily ordered. Update bindings MUST define a source-scoped
revision comparison or conditional-update mechanism. updated_at alone MUST
NOT override that mechanism or order revisions across independent sources.
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.
Such historical or stale results MUST be identified as such and MUST NOT be
represented as satisfying a current-use freshness constraint. Source update,
local receipt, indexing, and response generation times are distinct; refreshing
the index or response MUST NOT renew source evidence validity. Stable identity,
registration lifetime, credential validity, and observed endpoint availability
are also distinct.
Publishers SHOULD refresh records before expiration and SHOULD use random
jitter for large fleets to avoid synchronized refresh bursts.¶
{
"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"
}
¶
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.¶
| Field | Type | Requirement | Description |
|---|---|---|---|
| query | string | MUST | Natural-language intent or task description |
| required_tags | array of string | MAY | Tags that candidates must satisfy |
| preferred_tags | array of string | MAY | Tags that increase ranking score |
| excluded_tags | array of string | MAY | Tags that candidates must not contain |
| protocols | array of string | MAY | Acceptable protocols |
| 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 |
The query value MUST contain non-whitespace text. Other supplied values
MUST match their declared types; null is invalid. Unknown top-level fields
are non-critical unless a selected extension defines otherwise. Duplicate
JSON member names MUST cause rejection of metadata, requests, or responses,
so parsing cannot select different meanings for the same object.¶
A discovery service MUST apply required_tags and excluded_tags as hard
filters under the applicable taxonomy. All required tags must match and no
excluded tag may match; preferred tags affect ranking only. A tag appearing
in both required and excluded sets MUST cause invalid_request. When
protocols is present, at least one returned binding MUST match one listed
protocol. An empty protocol list is invalid.¶
An unsupported hard filter MUST cause unsupported_filter; reporting the
limitation while returning apparently conforming candidates is insufficient.
Constraint extensions MUST define whether their fields are hard requirements
or preferences; an unknown constraint is treated as an unsupported hard filter.
A separately specified, explicitly requested best-effort extension MAY return
non-conforming alternatives, but MUST identify them as alternatives rather than
as satisfying the original requirements.¶
When omitted, tag sets and constraints impose no additional restrictions,
include_evidence is false, and detail is summary. A supplied limit MUST
be a positive integer; the service MUST NOT return more candidates than it.
An unrecognized detail value MUST cause invalid_request.
Bindings MUST document their default and maximum limits and input-size limits.
Requests exceeding a declared hard limit require a structured error rather
than silent reinterpretation. Supporting bindings SHOULD expose limits and
query capabilities without requiring clients to know the internal search engine.¶
Constraints such as region and max_results_age_seconds require a
constraint binding specifying respectively the region vocabulary and the age
basis. In particular, a freshness binding MUST distinguish source update age
from time since authoritative current-state observation. These names do not
by themselves define global geographical or freshness semantics; a service
without that binding rejects them as unsupported rather than guessing.¶
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.¶
This request uses only base-profile fields and exact tag matching.¶
{
"query": "Find an agent for onboarding validation and API setup.",
"required_tags": ["hr"],
"preferred_tags": ["onboarding", "api-automation"],
"protocols": ["https"],
"limit": 10,
"detail": "summary",
"include_evidence": true
}
¶
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.¶
| Field | Type | Requirement | Description |
|---|---|---|---|
| request_id | string | SHOULD | Identifier for tracing the request |
| candidates | array of object | MUST | Ranked candidate agents |
| applied_filters | object | SHOULD | Filters applied by the discovery service |
| unsupported_filters | array of string | MAY | Unapplied filters only in an explicitly selected best-effort extension, not a base-profile success |
| warnings | array of string | MAY | Limitations or policy warnings |
| generated_at | string | SHOULD | Response generation timestamp |
Every candidate MUST contain id; other fields follow the requirements below.
An empty candidates array is a successful query with no matching visible
candidates. Inability to execute the query is an error, not an empty success.
Returned fields MUST match their declared types; null is invalid unless a
selected extension defines its meaning. Unknown non-critical fields follow
the metadata compatibility rules. A redacted response still MUST satisfy the
request's hard filters; omission of a field does not waive its constraint.¶
| 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 object | SHOULD | Usable protocol bindings |
| score | number | SHOULD | Overall ranking score |
| score_components | object | MAY | Structured score details |
| matched_tags | array of string | MAY | Tags matched directly or by expansion |
| matched_examples | array of object | MAY | Examples that matched the query |
| credential_refs | array of string | MAY | References for verification |
| redacted | boolean | MAY | Whether fields were omitted by policy |
| status | string | SHOULD | Operational status |
| freshness | object | SHOULD | Index and metadata freshness |
Scores are local to the discovery service. Clients MUST NOT compare scores from different discovery services unless a common scoring profile is explicitly defined.¶
Scores are not success probabilities, identity assurances, or access grants. Missing evidence or an unavailable score component MUST NOT be fabricated as a measured zero. Authorization and hard filters MUST hold regardless of score.¶
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 |
Implementations MAY add deployment-specific components. Clients ignore unknown components for score interpretation; transparent relays still preserve signed data.¶
{
"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"
}
}
]
}
¶
This section describes a recommended indexing and ranking model; implementations can use other algorithms. The result, access-control, and fallback requirements below apply regardless of the algorithm selected.¶
A discovery service can build three complementary indices:¶
An inverted index from capability tag to agent identifiers. This supports fast filtering and high-recall candidate generation.¶
A semantic index over descriptions, generated summaries, or other broad context fields. This supports natural-language recall when user wording differs from tags.¶
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.¶
A discovery service following the recommended model processes a request as follows:¶
Validate the request and apply authentication or rate limits.¶
Normalize tags and constraints against supported taxonomies.¶
Derive query features, such as predicted tags, query embeddings, or symbolic constraints.¶
Retrieve candidates from the tag index and context index.¶
Merge and deduplicate candidates.¶
Re-rank candidates using example-level, policy, freshness, and operational signals.¶
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.¶
Fallback MUST retain hard filters, access control, and required freshness. Index acceptance, semantic-index readiness, and successful query execution are different states. An unavailable search function MUST NOT be reported simply as an authoritative empty match set. Partial federation, candidate truncation, or an updating index SHOULD be identified when they limit result coverage. This document does not require any particular internal filtering order.¶
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.¶
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.¶
Cached responses and pagination MUST preserve the caller's access scope.
Pagination bindings MUST define query and authorization-scope binding and
integrity protection for continuation tokens. Reusing a token or cached full
response MUST NOT expose another caller's private metadata. A minimal
result can provide an authorized-resolution reference rather than a public
endpoint; full never overrides access policy.¶
Three scopes remain separate: what a directory is authorized to publish, what the current caller may see, and what the target allows the caller to execute. Where applicable, discovery MUST enforce both publication scope and caller visibility independently of relevance scores. A valid signed candidate or a successful discovery request does not grant invocation permission.¶
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 applicable
items below; D2 services follow the stronger conformance requirement above:¶
matched tags;¶
matched examples;¶
matched description snippets;¶
score components;¶
applied filters;¶
limitations on result coverage; or¶
freshness indicators.¶
Evidence MUST NOT disclose private metadata or private user queries from other clients.¶
Matching evidence explains relevance. Trust evidence supports a particular claim about a subject, authority, control relationship, or signed object; the two MUST NOT be conflated. Optional assurance extensions expose typed evidence references and, where available, verification results under a stated policy.¶
Authenticated publisher, verified organization, endpoint control, and tested capability are distinct assertions. Crawler-provided descriptions MUST NOT be presented as provider-authorized merely because a directory signed its own response. Derived descriptions, translations, or snippets MUST be distinguished from original signed metadata. An original signature does not cover a modified summary; a directory can retain a verifiable original reference and separately describe its transformation.¶
Such an extension can reference provider attestations, endpoint-control checks, capability-inventory baselines, build provenance, or runtime appraisal results. It MUST identify the claim type, subject and revision or deployment scope, evidence source, and applicable validity or observation time. A returned verification result MUST additionally identify the verifier and verification policy and MUST distinguish passed, failed, unperformed, unavailable, and stale checks. A reference alone conveys no verification result. This profile defines neither those evidence formats nor a universal assurance hierarchy.¶
If a capability inventory is summarized for search, its baseline revision and covered scope MUST remain distinguishable from the live observation. Search tags are not a substitute for a complete tool inventory. An implementation change can require refreshed metadata or assurance without creating a new stable agent identity.¶
Freshness of a response, metadata, and authoritative resource status are distinct.
An extension returning current-status evidence MUST retain its authority,
state revision, covered package, observation time, and validity conditions.
It MUST NOT use generated_at or local indexing time to renew that evidence.
If a requested hard assurance or freshness constraint cannot be evaluated,
the service MUST return unsupported_filter when unsupported, or an explicit
processing error when the required check is unavailable. A relevance score
cannot substitute for the missing check.¶
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.¶
Registration bindings MUST define the authoritative source, stable update key, revision comparison, and conflict rules. Endpoint changes alone MUST NOT be treated as creation of a new identity. An identical revision and content SHOULD be idempotent; the same revision with different content MUST conflict. New ownership claims MUST NOT silently replace an existing control relationship. If partial updates are supported, the binding MUST define field deletion and conditional-update semantics; complete-object replacement is also permitted.¶
Incremental exchange MUST preserve withdrawal or inactive-state meaning and define duplicate, out-of-order, gap-recovery, and checkpoint behavior. A scan checkpoint that can pass rejected records MUST NOT imply that every preceding record was accepted. This profile does not mandate a registry topology or an identity-transfer protocol.¶
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:¶
| 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 |
Federation MUST NOT remove freshness, redaction, or credential information that a client needs to make a trust decision.¶
Origin publisher, source authority, and responding directory can differ. Federation MUST preserve these distinctions and applicable source revisions. Local reranking MUST NOT be presented as the origin's score. Conflicting bindings, control claims, or lifecycle states MUST NOT be silently combined solely because stable identifiers match. Revisions from independent authorities are not a global order, and local receipt time does not renew source validity.¶
Federation does not establish transitive trust among authorities. Acceptance of one source's claims remains scoped by local policy; a source's withdrawal is not automatically an authoritative revocation in every other domain. Requests SHOULD disclose only authorized context and MUST NOT forward reusable caller credentials to another domain without explicit authorization.¶
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:¶
| 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
|
The Skill-list mapping applies to capability labels within an agent. An independently identified or versioned Skill needs a typed relation or artifact reference if its identity must be preserved; it cannot be reduced to a tag without losing that information. Format mapping does not transfer credentials, ownership, or invocation permission. External identifiers remain in their native namespace, with explicit association evidence where required.¶
If this profile is carried over a request/response protocol, errors MUST be
returned as JSON objects with a string code and the optional fields below.
Error objects are distinct from successful Discovery Responses.¶
| Field | Requirement | Description |
|---|---|---|
| code | MUST | Stable machine-readable error code |
| message | SHOULD | String containing a human-readable explanation |
| correlation_id | SHOULD | String identifier for tracing and support |
| retry_after | MAY | Non-negative integer delay in seconds |
The following error codes are RECOMMENDED:¶
| 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 |
| unavailable | Required query processing or evidence service is unavailable |
Where a rule above requires invalid_request or unsupported_filter, that
code is mandatory. Other categories use these codes when applicable; bindings
define their transport mapping and any additional codes.¶
HTTP bindings, if used, SHOULD map these errors to conventional HTTP status
codes using the semantics in [RFC9110]; 429 (Too Many Requests) is defined
in [RFC6585]. A 401 response requires the applicable authentication
challenge. A binding MAY use 404 to conceal a forbidden resource's existence.
Stale metadata does not by itself imply 410 (Gone), which concerns likely
permanent unavailability of the target resource. The profile's retry_after
field is a delay in seconds; it does not redefine the HTTP Retry-After field,
which also permits an HTTP-date.¶
This section is non-normative.¶
The following examples can be used as minimal parser and interoperation tests.¶
{
"id": "https://example.net/agents/minimal",
"name": "Minimal Agent",
"description": "Answers short factual questions.",
"bindings": [
{
"protocol": "https",
"endpoint": "https://example.net/agent/invoke"
}
]
}
¶
This object satisfies the D0 structural requirements. Authorization to publish or use it remains subject to the selected binding and local policy.¶
{
"query": "answer a short factual question",
"protocols": ["https"],
"limit": 1
}
¶
The expected D1 outcome contains at most one candidate, possibly none;
include_evidence is not required.¶
{
"query": "find a translation agent",
"required_tags": ["translation"],
"constraints": {
"unsupported_private_filter": "example"
}
}
¶
Without a defined extension classifying this constraint as a preference, the
service MUST return unsupported_filter. A normal success response listing
it only in unsupported_filters is not conforming to the base profile.¶
The following cases have deterministic semantic outcomes, independent of ranking:¶
a tag required and excluded in one query produces invalid_request;¶
unknown required security capabilities produce unsupported_filter;¶
regenerated response timestamps do not make expired source metadata fresh;¶
a transformed summary cannot inherit the original object's signature coverage;¶
unavailable ranking components do not relax hard filters or fabricate scores;¶
equal local identifiers in different namespaces do not establish equivalence;¶
conflicting revisions from different authorities retain their provenance; and¶
continuation tokens cannot bypass the current caller's access scope.¶
Discovery is security-sensitive. A malicious discovery result can steer a client to an attacker-controlled agent.¶
Clients SHOULD verify signatures, credentials, or registry attestations before invoking an agent returned by discovery.¶
Agents can exaggerate descriptions, tags, or examples. Discovery services SHOULD distinguish self-asserted metadata from verified metadata.¶
Descriptions and examples are untrusted text. Discovery services using language models MUST treat them as data, not as instructions authorizing tool use, data disclosure, or changes to ranking policy. Implementations SHOULD isolate model processing from privileged tools and enforce disclosure and access constraints outside the model; prompt wording alone is not a security boundary or a guarantee of injection resistance.¶
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.¶
Discovery services SHOULD expose freshness data. Clients MUST check applicable credential and resource status before invocation and authenticate the selected endpoint using its native protocol. Record freshness is not evidence of endpoint liveness.¶
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.¶
A discovery service that silently ignores unsupported hard filters can return unsafe candidates. Services MUST reject unsupported hard filters unless an explicitly selected extension defines visibly non-conforming alternatives.¶
Discovery requests can reveal user goals. Discovery services MUST protect requests in transit and SHOULD minimize retention.¶
A discovery response is not an authorization decision. The target agent MUST still enforce its own access control policy.¶
Verification inputs and external references require bounded processing. Implementations SHOULD constrain object size, depth, reference recursion, redirects, retrieval time, and permitted destinations. An external descriptor MUST NOT implicitly authorize access to protected internal or cloud metadata services or disclosure of credentials across origins. Required verification that exceeds limits fails explicitly; it is not skipped to obtain a match.¶
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].¶
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.¶
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.¶
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.¶
The authors thank participants in discussions on agent discovery, metadata profiles, and efficient retrieval for large agent ecosystems.¶