Metadata and Query Profile for Efficient Agent Discovery

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

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

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

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

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

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

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

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

["translation", "finance", "invoice-processing", "json-output"]

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

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

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

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

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

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

12. Error Model

If this profile is carried over a request/response protocol, errors SHOULD be returned as structured objects containing:¶

The following error codes are RECOMMENDED:¶

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

{
  "id": "https://example.net/agents/minimal",
  "name": "Minimal Agent",
  "description": "Answers short factual questions.",
  "bindings": [
    {
      "protocol": "https",
      "endpoint": "https://example.net/agent/invoke"
    }
  ]
}

{
  "query": "answer a short factual question",
  "protocols": ["https"],
  "limit": 1
}

{
  "query": "find a translation agent",
  "required_tags": ["translation"],
  "constraints": {
    "unsupported_private_filter": "example"
  }
}

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

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

19. References

Appendix A. Acknowledgements

The authors thank participants in discussions on agent discovery, metadata profiles, and efficient retrieval for large agent ecosystems.¶

Authors' Addresses