Agent Discovery Protocol Specification

ANP Agent Discovery Protocol Specification (Draft)

Abstract

This specification defines the Agent Discovery Service Protocol (ADSP), a standardized protocol for discovering agents. Based on the JSON-LD format, the protocol provides two discovery mechanisms: active discovery and passive discovery, designed to enable agents to be effectively discovered and accessed by other agents or search engines in the network.

The core content of the protocol includes:

  1. Using JSON-LD as the foundational data format, supporting linked data and semantic web features
  2. Defining an active discovery mechanism, using the .well-known URI path as the entry point for agent discovery
  3. Providing a passive discovery mechanism, allowing agents to submit their own descriptions to search services
  4. Supporting pagination and linking of agent descriptions, facilitating the management of large amounts of agent information

This specification aims to improve the discoverability of agents in the network, providing foundational support for building an agent network ecosystem.

Introduction

As the number of agents continues to increase, how to effectively discover and access these agents has become a key issue. The Agent Discovery Service Protocol (ADSP) aims to address this problem by enabling agents to be discovered by other agents or search engines in a standardized way.

This specification defines two agent discovery mechanisms: active discovery and passive discovery. Active discovery allows search engines or other agents to discover all public agents under a known domain; passive discovery allows agents to actively register their descriptions with search services. These two mechanisms complement each other, jointly improving the discoverability of agents.

Simplified Agent Discovery Flow

Overview

We use JSON-LD (JavaScript Object Notation for Linked Data) as the format for agent discovery documents, consistent with the Agent Description Protocol. By using JSON-LD, we can achieve rich semantic expression and link relationships while maintaining simplicity and ease of use.

The agent description document is a detailed information expression of the agent, as referenced in the ANP Agent Description Protocol Specification. The agent discovery document, on the other hand, serves as a collection page, containing URLs of all public agent description documents under the domain, facilitating indexing and access by search engines or other agents.

Protocol Details

Active Discovery

Active discovery refers to the ability of search engines or agents to discover all public agent description documents under a domain by knowing only the domain name. We have adopted the Web standard .well-known URI path as the entry point for agent discovery.

Active Discovery Flow of Agent Discovery Protocol

.well-known URI

According to RFC 8615, .well-known URI provides a standardized way to discover services and resources. For agent discovery, we define the following path:

https://{domain}/.well-known/agent-descriptions

This path should return a JSON-LD document containing URLs of all public agent description documents under the domain.

Discovery Document Format

The active discovery document adopts the JSON-LD format, using the CollectionPage type, and contains the following core properties:

  • @context: Defines the JSON-LD context used in the document
  • @type: Document type, value is “CollectionPage”
  • url: URL of the current page
  • items: Array of agent description items
  • next: (Optional) URL of the next page, used for pagination scenarios

Each agent description item contains:

  • @type: Type, value is “ad:AgentDescription”
  • name: Agent name
  • @id: URL of the agent description document (unique identifier of the resource)

Example:

{
  "@context": {
    "@vocab": "https://schema.org/",
    "did": "https://w3id.org/did#",
    "ad": "https://agent-network-protocol.com/ad#"
  },
  "@type": "CollectionPage",
  "url": "https://agent-network-protocol.com/agent-descriptions",
  "items": [
    {
      "@type": "ad:AgentDescription",
      "name": "Smart Assistant",
      "@id": "https://agent-network-protocol.com/agents/smartassistant/ad.json"
    },
    {
      "@type": "ad:AgentDescription",
      "name": "Customer Support Agent",
      "@id": "https://agent-network-protocol.com/agents/customersupport/ad.json"
    }
  ],
  "next": "https://agent-network-protocol.com/agent-descriptions/page2.json"
}

Pagination Mechanism

When there are a large number of agents under a domain, a pagination mechanism should be adopted. Pagination is implemented through the next property, pointing to the URL of the next page. Clients should recursively retrieve all pages until there is no next property.

Passive Discovery

Passive discovery refers to agents actively submitting their agent description URLs to other agents (usually search service agents), enabling them to index and crawl their information.

Registration API

Passive discovery typically requires the use of registration APIs provided by search service agents. These APIs are defined by the search service agents themselves and should be clearly specified in their agent description documents. Agents can register their description URLs with search services by calling these APIs.

Registration Process

  1. The agent obtains the description document of the search service agent
  2. Finds the registration API endpoint and parameter requirements from the description document
  3. Constructs a registration request, including its own agent description URL and other necessary information
  4. Sends the registration request to the search service
  5. The search service verifies the request and indexes the agent
sequenceDiagram
    participant Agent as Agent
    participant Search as Search Service Agent
    
    Agent->>Search: Get agent description document
    Search-->>Agent: Return description document (including registration API information)
    Note over Agent: Parse registration API from description document
    Agent->>Search: Send registration request (including own description URL)
    Note over Search: Verify request
    Search-->>Agent: Confirm registration
    Note over Search: Crawl agent description document and index

Security Considerations

To ensure the security of agent discovery, the following measures are recommended:

  1. Content Validation: Search services should validate the validity and integrity of agent description documents
  2. DID Authentication: Use the did:wba method for identity authentication to ensure the authenticity of agent identities
  3. Rate Limiting: Implement appropriate rate limiting measures to prevent malicious requests and DoS attacks
  4. Permission Control: Distinguish between public and private agents, including only public agents in discovery documents

Relationship with Other Protocols

The Agent Discovery Protocol is closely related to the following protocols:

  1. Agent Description Protocol: The discovery protocol provides an indexing and access mechanism for description documents
  2. DID:WBA Method: Provides identity authentication and security guarantees
  3. Meta-Protocol: Protocol negotiation in agent communication can be based on discovery results

Copyright Notice

Copyright (c) 2024 GaoWei Chang
This file is published under the MIT License, you are free to use and modify it, but you must retain this copyright notice.