Agent Description Protocol Specification

ANP Agent Description Protocol Specification (Draft)

Abstract

This specification defines the Agent Description Protocol (ADP), a standardized protocol for describing agents. The protocol is based on the JSON-LD format, combining schema.org vocabulary and custom vocabulary to provide a unified description method for agents.

The core content of the protocol includes:

Using JSON-LD as the foundational data format, supporting linked data and semantic web features
Defining core vocabulary for agent basic information, products, services, interfaces, etc.
Adopting the did:wba method as a unified security mechanism to implement cross-platform identity authentication
Supporting interoperability with other protocols (such as OpenAPI, JSON-RPC)

This specification aims to improve interoperability and communication efficiency between agents, providing foundational support for building agent networks.

Introduction

Agent Description (AD) is the entry point for an agent. Based on the AD, other agents can obtain information about this agent’s name, owning entity, functions, products, services, interaction APIs or protocols, etc. With this information, data communication and collaboration between agents can be realized.

As AI capabilities continue to improve, AI’s ability to understand natural language is also improving. Theoretically, pure natural language without fixed specification requirements can also be used to describe agent information, but this would increase the communication cost between agents and reduce the consistency of information understanding between two agents. Therefore, to improve communication efficiency between agents, a specification for describing agents is needed to ensure consistency in information exchange between agents.

Overview

We use JSON-LD (JavaScript Object Notation for Linked Data) as the format for agent description. JSON-LD is a standard format for representing linked data and semantic web data. It is based on JSON (JavaScript Object Notation) syntax and allows embedding links in JSON objects to represent relationships and structures between data.

This way, we can store all information about an agent as multiple files, and then use the agent description document to link these files together. The agent description document can serve as the entry point for the agent, and other agents can obtain all information about the agent based on this description document.

To improve the consistency of agents’ understanding of description documents, we have defined a series of standard vocabularies. At the same time, when describing resources such as products and services, we recommend using schema.org vocabulary to improve the consistency of document understanding. If schema.org vocabulary cannot meet the requirements, users can also define custom vocabulary. Another benefit of using schema.org vocabulary is that data can be processed directly by code, not just by AI.

JSON-LD also needs to be used in conjunction with other protocols. For example, interface description protocols can use OpenAPI described in YAML format, or RPC protocols described in JSON-RPC format.

Below is an example of an agent description document:

{
  "@context": {
    "@vocab": "https://schema.org/",
    "did": "https://w3id.org/did#",
    "ad": "https://agent-network-protocol.com/ad#"
  },
  "@type": "ad:AgentDescription",
  "@id": "https://agent-network-protocol.com/agents/smartassistant",
  "name": "SmartAssistant",
  "did": "did:wba:example.com:user:alice",
  "owner": {
    "@type": "Organization",
    "name": "Hangzhou Bit Intelligence Technology Co., Ltd.",
    "@id": "https://agent-network-protocol.com"
  },
  "description": "SmartAssistant is an intelligent agent solution for individuals and enterprises, providing various natural language processing and cross-platform connectivity capabilities.",
  "version": "1.0.0",
  "created": "2024-12-31T12:00:00Z",
  "securityDefinitions": {
    "didwba_sc": {
      "scheme": "didwba",
      "in": "header",
      "name": "Authorization"
    }
  },
  "security": "didwba_sc",
  "products": [
    {
      "@type": "Product",
      "name": "AI Assistant Pro",
      "description": "A high-end AI assistant offering advanced customization services.",
      "@id": "https://agent-network-protocol.com/products/ai-assistant-pro"
    },
    {
      "@type": "Product",
      "name": "Agent Connector",
      "description": "A cross-platform connectivity solution for intelligent agents.",
      "@id": "https://agent-network-protocol.com/products/agent-connector"
    }
  ],
  "interfaces": [
    {
      "@type": "ad:NaturalLanguageInterface",
      "protocol": "YAML",
      "url": "https://agent-network-protocol.com/api/nl-interface.yaml",
      "description": "A YAML file for interacting with the intelligent agent through natural language."
    },
    {
      "@type": "ad:StructuredInterface",
      "protocol": "YAML",
      "humanAuthorization": true,
      "url": "https://agent-network-protocol.com/api/purchase-interface.yaml",
      "description": "A YAML file for interacting with the intelligent agent through purchase."
    },
    {
      "@type": "ad:StructuredInterface",
      "protocol": "JSON-RPC 2.0",
      "url": "https://agent-network-protocol.com/api/api-interface.json",
      "description": "A JSON-RPC 2.0 file for interacting with the intelligent agent through APIs."
    }
  ],
  "proof": {
    "type": "EcdsaSecp256r1Signature2019",
    "created": "2024-12-31T15:00:00Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:wba:example.com:user:alice#keys-1",
    "challenge": "1235abcd6789",
    "proofValue": "z58DAdFfa9SkqZMVPxAQpic7ndSayn1PzZs6ZjWp1CktyGesjuTSwRdoWhAfGFCF5bppETSTojQCrfFPP2oumHKtz"
  }
}

Below is an example of a product description:

{
  "@context": {
    "@vocab": "https://schema.org/",
    "ad": "https://agent-network-protocol.com/ad#"
  },
  "@type": "Product",
  "@id": "https://agent-network-protocol.com/agents/lkcoffe/roasted-coconut-latte/roasted-coconut-latte.json",
  "identifier": "rl-29ab8cf9",
  "name": "Roasted Coconut Latte",
  "description": "Roasted at approximately 135°C for a unique coconut sugar flavor, suitable for winter consumption. This drink combines coconut pulp juice and roasted coconut granules, offering five 'zero' light enjoyment health options, using master-customized Espresso from IIAC gold award coffee beans.",
  "brand": {
    "@type": "Brand",
    "name": "Luckin Coffee"
  },
  "additionalProperty": [
    {
      "@type": "PropertyValue",
      "name": "Feature",
      "value": "Coconut pulp juice & roasted coconut granules blend, five 'zero' light enjoyment (0 lactose, 0 creamer, 0 sucrose solids, 0 trans fats, 0 added flavors), master-customized Espresso from IIAC gold award coffee beans"
    },
    {
      "@type": "PropertyValue",
      "name": "Slogan",
      "value": "Winter Special Drink Warm Return"
    },
    {
      "@type": "PropertyValue",
      "name": "Additional Info",
      "value": "Coconut flavor from memory"
    }
  ],
  "offers": {
    "@type": "Offer",
    "price": "13",
    "priceCurrency": "CNY",
    "availability": "https://schema.org/InStock"
  },
  "nutrition": {
    "@type": "NutritionInformation",
    "calories": "150",
    "fatContent": "0g",
    "sugarContent": "0g",
    "proteinContent": "0g",
    "cholesterolContent": "0mg",
    "carbohydrateContent": "0g"
  },
  "ingredients": "Coconut milk, espresso, roasted coconut syrup",
  "category": "Beverage",
  "sku": "LK-COCONUT-LATTE",
  "image": [
    {
      "@type": "ImageObject",
      "url": "https://agent-network-protocol.com/agents/lkcoffe/roasted-coconut-latte/instruction.jpg",
      "caption": "Roasted Coconut Latte - Winter Special Drink Warm Return",
      "description": "Using 135°C high-temperature roasting process, perfectly blending coconut pulp juice and roasted coconut granules, paired with Espresso made from IIAC gold award coffee beans, bringing a unique blend of roasted coconut aroma and coffee aroma"
    },
    {
      "@type": "ImageObject",
      "url": "https://agent-network-protocol.com/agents/lkcoffe/roasted-coconut-latte/feature.jpg",
      "caption": "Roasted Coconut Latte - Coconut flavor from memory",
      "description": "Coconut flavor from memory"
    }
  ],
  "audience": {
    "@type": "Audience",
    "audienceType": "Coffee Enthusiasts",
    "geographicArea": "China"
  },
  "manufacturer": {
    "@type": "Organization",
    "name": "Luckin Coffee",
    "url": "https://luckincoffee.com"
  },
  "customizationOptions": {
    "@type": "ad:CustomizationOptions",
    "options": [
      {
        "@type": "PropertyValue",
        "name": "Temperature",
        "isRequired": true,
        "value": ["Iced", "Hot"]
      },
      {
        "@type": "PropertyValue",
        "name": "Sugar Level",
        "isRequired": true,
        "value": ["Standard Sweet", "Less Sweet", "Slightly Sweet", "No Additional Sugar"]
      }
    ]
  }
}

Note: In the product description, properties in the image can be placed in an array to represent multiple values, which also conforms to the schema.org specification.

Namespace

In this specification, vocabulary terms related to agent description are always presented in their compact form. Their expanded form can be accessed through the namespace IRI https://agent-network-protocol.com/ad#.

AD Information Model

Overview

The AD information model is built on the vocabulary https://agent-network-protocol.com/ad# and schema.org vocabulary.

The namespace “ad” defines key vocabulary for agent description, while schema.org defines some common vocabulary for agent description. These vocabularies can be customized by users or automatically recognized by AI.

Vocabulary Definition

Core Vocabulary Definition

Agent

An agent is an abstraction of a physical or virtual entity, whose metadata and interfaces are described through an Agent Description (AD) document. A virtual entity can be a combination of one or more agents.

Table 1: Agent-level vocabulary terms. The following terms can be used in sub-documents.

Vocabulary Term	Description	Required	Type
@context	JSON-LD keyword used to define shorthand names (terms) used in the AD document.	Required	anyURI or Array
@type	JSON-LD keyword used to add semantic labels (or types) to objects.	Optional	string or Array of string
@id	Identifier for the agent, in URI [RFC3986] format (such as stable URIs, temporary and variable URIs, URIs with local IP addresses, URNs, etc.).	Optional	anyURI
did	Decentralized identifier (DID) for the agent, used to uniquely identify the agent’s identity.	Optional	string
name	Provides a human-readable name based on the default language (such as text for UI display).	Required	string
description	Provides additional (human-readable) information based on the default language.	Optional	string
version	Provides version information.	Optional	VersionInfo
created	Provides information about the creation time of the AD instance.	Optional	dateTime
modified	Provides information about the last modification time of the AD instance.	Optional	dateTime
owner	Provides information about the agent’s owner. Can be a person or organization.	Optional	Person or Organization
products	List of all products provided by the agent.	Optional	Array of Product
interfaces	Interfaces provided by the agent, which can be natural language interfaces or structured interfaces.	Optional	Array of Interface
securityDefinitions	Security definitions for the agent, used to define security schemes.	Optional	Object
security	Security schemes used by the agent.	Optional	string or Array of string
proof	Proof information for the agent, used to verify the authenticity of the agent description document.	Optional	Object

Interface

An interface is a method for interacting with an agent, which can be a natural language interface or a structured interface.

Table 2: Interface-level vocabulary terms.

Vocabulary Term	Description	Required	Type
@type	Type of interface, can be “ad:NaturalLanguageInterface” or “ad:StructuredInterface”.	Required	string
protocol	Protocol used by the interface, such as “YAML”, “JSON-RPC 2.0”, etc.	Required	string
url	URL of the interface description document.	Required	anyURI
description	Description of the interface.	Optional	string
humanAuthorization	Whether human authorization is required for the interface.	Optional	boolean

Digital Signature

To ensure the authenticity and integrity of the agent description document, a digital signature is used. The digital signature is placed in the “proof” field of the agent description document.

The “proof” field contains the following information:

type: Signature algorithm type
created: Creation time of the signature
proofPurpose: Purpose of the signature, typically “assertionMethod”
verificationMethod: Method used for verification, typically the DID of the agent owner plus the key ID
challenge: Random string to prevent replay attacks
proofValue: Digital signature value

The generation rules for proofValue are as follows:

Generate the AD document of the site without the proofValue field
Use JCS (JSON Canonicalization Scheme) to canonicalize the above AD document, generating a canonicalized string
Use the SHA-256 algorithm to hash the canonicalized string, generating a hash value
Use the client’s private key to sign the hash value, generating a signature value, and perform URL-safe Base64 encoding
The signature verification process is the reverse of the above process

Standardization of Common Definitions

For a specific product or service, such as a cup of coffee or a toy, a subset of schema.org’s Product properties can be used to define a specific type, clarifying how to describe the product. This way, all agents can use unified definitions when constructing product data, facilitating interoperability between different agents.

Interfaces can be handled in a similar way. For example, for a product purchase interface, we can define a unified purchase interface specification that all agents can use, facilitating interoperability between different agents.

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.