Skip to content

Commit eb98770

Browse files
chgaoweichgaowei
committed
add Agent Discovery Protocol Specification
1 parent 5766b4d commit eb98770

File tree

4 files changed

+285
-4
lines changed

4 files changed

+285
-4
lines changed

‎08-ANP-Agent-Discovery-Protocol-Specification.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# ANP-Agent Discovery Protocol Specification (Draft)
2+
3+
## Abstract
4+
5+
This specification defines the Agent Discovery Service Protocol (ADSP), a standardized protocol for discovering agents. Based on the JSON-LD format, it provides two discovery mechanisms: active discovery and passive discovery, aimed at enabling agents to be effectively discovered and accessed by other agents or search engines in the network.
6+
7+
The core elements of the protocol include:
8+
1. Using JSON-LD as the foundational data format, supporting linked data and semantic web features
9+
2. Defining an active discovery mechanism, using .well-known URI paths as agent discovery entry points
10+
3. Providing a passive discovery mechanism, allowing agents to submit their descriptions to search services
11+
4. Supporting pagination and linking of agent descriptions, facilitating the management of large numbers of agent information
12+
13+
This specification aims to enhance the discoverability of agents in the network, providing foundational support for building agent network ecosystems.
14+
15+
## Introduction
16+
17+
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 providing a standardized way for agents to be discovered by other agents or search engines.
18+
19+
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 enhancing the discoverability of agents.
20+
21+
## Overview
22+
23+
We use [JSON-LD](https://www.w3.org/TR/json-ld11/) (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 linking relationships while maintaining simplicity and ease of use.
24+
25+
Agent description documents are detailed expressions of agent information, as referenced in the [ANP-Agent Description Protocol Specification](07-ANP-Agent-Description-Protocol-Specification.md). The agent discovery document serves as a collection page, containing URLs of all public agent description documents under a domain, facilitating indexing and access by search engines or other agents.
26+
27+
## Protocol Details
28+
29+
### Active Discovery
30+
31+
Active discovery refers to search engines or agents only needing to know a domain to discover all public agent description documents under that domain. We adopt the Web standard `.well-known` URI path as the entry point for agent discovery.
32+
33+
#### .well-known URI
34+
35+
According to [RFC 8615](https://tools.ietf.org/html/rfc8615), `.well-known` URI provides a standardized way to discover services and resources. For agent discovery, we define the following path:
36+
37+
```
38+
https://{domain}/.well-known/agent-descriptions
39+
```
40+
41+
This path should return a JSON-LD document containing URLs of all public agent description documents under the domain.
42+
43+
#### Discovery Document Format
44+
45+
Active discovery documents adopt the JSON-LD format, using the `CollectionPage` type, containing the following core properties:
46+
47+
- `@context`: Defines the JSON-LD context used in the document
48+
- `@type`: Document type, value is "CollectionPage"
49+
- `url`: URL of the current page
50+
- `items`: Array of agent description items
51+
- `next`: (Optional) URL of the next page, used for pagination scenarios
52+
53+
Each agent description item contains:
54+
- `@type`: Type, value is "ad:AgentDescription"
55+
- `name`: Agent name
56+
- `@id`: URL of the agent description document (unique identifier of the resource)
57+
58+
Example:
59+
60+
```json
61+
{
62+
"@context": {
63+
"@vocab": "https://schema.org/",
64+
"did": "https://w3id.org/did#",
65+
"ad": "https://agent-network-protocol.com/ad#"
66+
},
67+
"@type": "CollectionPage",
68+
"url": "https://agent-network-protocol.com/agent-descriptions",
69+
"items": [
70+
{
71+
"@type": "ad:AgentDescription",
72+
"name": "Smart Assistant",
73+
"@id": "https://agent-network-protocol.com/agents/smartassistant/ad.json"
74+
},
75+
{
76+
"@type": "ad:AgentDescription",
77+
"name": "Customer Support Agent",
78+
"@id": "https://agent-network-protocol.com/agents/customersupport/ad.json"
79+
}
80+
],
81+
"next": "https://agent-network-protocol.com/agent-descriptions/page2.json"
82+
}
83+
```
84+
85+
#### Pagination Mechanism
86+
87+
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.
88+
89+
### Passive Discovery
90+
91+
Passive discovery refers to agents actively submitting their agent description URLs to other agents (typically search service agents), enabling them to index and crawl their information.
92+
93+
#### Registration API
94+
95+
Passive discovery typically requires using the registration API provided by search service agents. These APIs are defined by the search service agents themselves and should be clearly stated in their agent description documents. Agents can register their description URLs with search services by calling these APIs.
96+
97+
#### Registration Process
98+
99+
1. Agent obtains the description document of the search service agent
100+
2. Finds the registration API endpoint and parameter requirements from the description document
101+
3. Constructs a registration request, including its own agent description URL and other necessary information
102+
4. Sends the registration request to the search service
103+
5. Search service verifies the request and indexes the agent
104+
105+
```mermaid
106+
sequenceDiagram
107+
participant Agent as Agent
108+
participant Search as Search Service Agent
109+
110+
Agent->>Search: Get agent description document
111+
Search-->>Agent: Return description document (including registration API info)
112+
Note over Agent: Parse registration API from description document
113+
Agent->>Search: Send registration request (including own description URL)
114+
Note over Search: Verify request
115+
Search-->>Agent: Confirm registration
116+
Note over Search: Crawl agent description document and index
117+
```
118+
119+
### Security Considerations
120+
121+
To ensure the security of agent discovery, the following measures are recommended:
122+
123+
1. **Content Validation**: Search services should verify the validity and integrity of agent description documents
124+
2. **DID Authentication**: Use the did:wba method for identity authentication, ensuring the authenticity of agent identities
125+
3. **Rate Limiting**: Implement appropriate rate limiting measures to prevent malicious requests and DoS attacks
126+
4. **Permission Control**: Distinguish between public and private agents, only including public agents in discovery documents
127+
128+
## Relationship with Other Protocols
129+
130+
The Agent Discovery Protocol is closely related to the following protocols:
131+
132+
1. **Agent Description Protocol**: The discovery protocol provides indexing and access mechanisms for description documents
133+
2. **DID:WBA Method**: Provides identity authentication and security guarantees
134+
3. **Meta-Protocol**: In agent communication, protocol negotiation can be based on discovery results
135+
136+
## Copyright Notice
137+
Copyright (c) 2024 GaoWei Chang
138+
This document is released under the [MIT License](./LICENSE), you are free to use and modify it, but you must retain this copyright notice.

‎README.cn.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,8 @@ AgentNetworkProtocol(ANP)的目标是成为**智能体互联网时代的HTTP**
5656

5757
- 我们设计了一个用于描述智能体的协议，它能够让智能体之间进行数据交互：[智能体描述协议规范（Draft）](chinese/07-ANP-智能体描述协议规范.md)
5858

59+
- 我们设计了一个用于智能体发现的协议，帮助智能体之间相互发现和交互：[智能体发现协议规范（Draft）](chinese/08-ANP-智能体发现协议规范.md)
60+
5961
- 我们设计了一个智能体消息规范，可以用于智能体消息的代理服务，让智能体隐藏在代理服务后面，从而实现更高的安全性、降低智能体开发维护成本。[基于did的端到端加密通信](chinese/message/04-基于did的端到端加密通信技术协议.md)，[基于did的消息服务协议](chinese/message/05-基于did的消息服务协议.md)。（备注： 这两个规范基于废弃的did:all方法，后面会升级为基于did:wba方法的方案）
6062

6163
- 还有一些规范我们正在设计和完善中。
@@ -75,6 +77,10 @@ AgentNetworkProtocol(ANP)的目标是成为**智能体互联网时代的HTTP**
7577

7678
- 从OpenAI的Operator，谈AI与互联网交互的三种技术路线：[从OpenAI的Operator，看AI与互联网交互的三种技术路线](blogs/cn/从OpenAI的Operator，看AI与互联网交互的三种技术路线.md)
7779

80+
- 智能体身份的三个关键问题：[智能体身份的三个关键问题：互操作性、人类授权和隐私保护](blogs/Three-Key-Issues-of-Agent-Identity:%20Interoperability,%20Human-Authorization,%20and-Privacy-Protection.md)
81+
82+
- AI个人助手未来产品形态和主要玩家的分析与预测：[AI个人助手未来产品形态和主要玩家的分析与预测](blogs/cn/AI个人助手未来产品形态和主要玩家的分析与预测.md)
83+
7884
### 里程碑
7985

8086
无论是协议还是开源代码实现，我们整体式是按照以下的顺序逐步的推进：
@@ -83,7 +89,7 @@ AgentNetworkProtocol(ANP)的目标是成为**智能体互联网时代的HTTP**
8389
- [x] 元协议设计与元协议代码实现。当前协议设计和代码开发基本完成。
8490
- [x] 应用层协议设计与开发。
8591
- [x] 支持智能体描述。
86-
- [ ] 支持智能体发现。
92+
- [x] 支持智能体发现。
8793

8894
为了推动Agent Network Protocol(ANP)成为行业的标准，我们将会在合适的时间组建ANP标准化委员会，致力于推动ANP成为W3C等国际标准化组织认可的行业标准。
8995

‎README.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,8 @@ For further understanding, you can refer to these documents:
5656

5757
- We have designed a protocol for describing agents that enables data exchange between agents: [Agent Description Protocol Specification](07-ANP-Agent%20Description%20Protocol%20Specification.md)
5858

59+
- We have designed an agent discovery protocol that helps agents find and interact with each other: [Agent Discovery Protocol Specification](08-ANP-Agent-Discovery-Protocol-Specification.md)
60+
5961
- We have designed an agent message specification that can be used for agent message proxy services, allowing agents to hide behind proxy services to achieve higher security and reduce the cost of agent development and maintenance. [End-to-End Encrypted Communication Based on did](message/04-End-to-End%20Encrypted%20Communication%20Technology%20Protocol%20Based%20on%20did.md), [Message Service Protocol Based on did](message/05-Message%20Service%20Protocol%20Based%20on%20did.md). (Note: These two specifications are based on the deprecated did:all method and will be upgraded to the did:wba method in the future)
6062

6163
- Additional specifications are currently under development.
@@ -74,6 +76,10 @@ Here are some of our blogs:
7476

7577
- Three Technical Approaches to AI-Internet Interaction: [Three Technical Approaches to AI-Internet Interaction](blogs/Three_Technical_Approaches_to_AI_Internet_Interaction.md)
7678

79+
- Three Key Issues of Agent Identity: [Three Key Issues of Agent Identity: Interoperability, Human-Authorization, and Privacy Protection](blogs/Three-Key-Issues-of-Agent-Identity:%20Interoperability,%20Human-Authorization,%20and-Privacy-Protection.md)
80+
81+
- Analysis and Predictions of AI Personal Assistants: [Analysis and Predictions of AI Personal Assistants](blogs/cn/AI个人助手未来产品形态和主要玩家的分析与预测.md)
82+
7783
### Milestones
7884

7985
Both protocol development and open-source implementation are progressing in the following order:
@@ -82,7 +88,7 @@ Both protocol development and open-source implementation are progressing in the
8288
- [x] Meta-protocol design and implementation. Protocol design and code development are basically complete.
8389
- [x] Application layer protocol design and development.
8490
- [x] Support for agent description.
85-
- [ ] Support for agent discovery.
91+
- [x] Support for agent discovery.
8692

8793
To establish Agent Network Protocol(ANP) as an industry standard, we plan to form an ANP Standardization Committee at an appropriate time, working towards recognition by international standardization organizations like W3C.
8894

‎chinese/08-ANP-智能体发现协议规范.md‎

Lines changed: 133 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,138 @@
1+
# ANP-智能体发现协议规范（Draft）
12

3+
## 摘要
24

5+
本规范定义了智能体发现协议（Agent Discovery Service Protocol, ADSP），这是一个用于发现智能体的标准化协议。该协议基于JSON-LD格式，提供了两种发现机制：主动发现和被动发现，旨在使智能体能够在网络中被其他智能体或搜索引擎有效地发现和访问。
36

7+
协议的核心内容包括：
8+
1. 使用JSON-LD作为基础数据格式，支持链接数据和语义网特性
9+
2. 定义了主动发现机制，使用.well-known URI路径作为智能体发现入口点
10+
3. 提供了被动发现机制，允许智能体将自身描述提交给搜索服务
11+
4. 支持智能体描述的分页和链接，便于管理大量智能体信息
412

5-
## 版权声明
13+
本规范旨在提高智能体在网络中的可发现性，为构建智能体网络生态系统提供基础支持。
14+
15+
## 引言
16+
17+
随着智能体数量的不断增加，如何有效地发现和访问这些智能体成为了一个关键问题。智能体发现协议（Agent Discovery Service Protocol, ADSP）旨在解决这一问题，通过标准化的方式使得智能体能够被其他智能体或搜索引擎发现。
18+
19+
本规范定义了两种智能体发现机制：主动发现和被动发现。主动发现允许搜索引擎或其他智能体通过已知的域名发现该域名下的所有公开智能体；被动发现则允许智能体主动将自身描述注册到搜索服务中。这两种机制相互补充，共同提高了智能体的可发现性。
20+
21+
## 概述
22+
23+
我们使用[JSON-LD](https://www.w3.org/TR/json-ld11/)(JavaScript Object Notation for Linked Data)作为智能体发现文档的格式，与智能体描述协议保持一致。通过使用JSON-LD，我们可以在保持简单易用的同时，实现丰富的语义表达和链接关系。
24+
25+
智能体描述文档是智能体的详细信息表达，参考文档 [ANP-智能体描述协议规范](07-ANP-智能体描述协议规范.md)。而智能体发现文档则作为一个集合页面，包含了域名下所有公开智能体描述文档的URL，便于搜索引擎或其他智能体进行索引和访问。
26+
27+
## 协议详情
28+
29+
### 主动发现
30+
31+
主动发现是指搜索引擎或智能体只需知道一个域名，即可发现该域名下所有公开的智能体描述文档。我们采用了Web标准的`.well-known` URI路径作为智能体发现的入口点。
32+
33+
#### .well-known URI
34+
35+
根据[RFC 8615](https://tools.ietf.org/html/rfc8615)，`.well-known` URI提供了一种标准化的方式来发现服务和资源。对于智能体发现，我们定义了以下路径：
36+
37+
```
38+
https://{domain}/.well-known/agent-descriptions
39+
```
40+
41+
此路径应返回一个JSON-LD文档，包含该域名下所有公开的智能体描述文档的URL。
42+
43+
#### 发现文档格式
44+
45+
主动发现文档采用JSON-LD格式，使用`CollectionPage`类型，包含以下核心属性：
46+
47+
- `@context`: 定义文档使用的JSON-LD上下文
48+
- `@type`: 文档类型，值为"CollectionPage"
49+
- `url`: 当前页面的URL
50+
- `items`: 智能体描述项目的数组
51+
- `next`: （可选）下一页的URL，用于分页场景
52+
53+
每个智能体描述项目包含：
54+
- `@type`: 类型，值为"ad:AgentDescription"
55+
- `name`: 智能体名称
56+
- `@id`: 智能体描述文档的URL（资源的唯一标识符）
57+
58+
示例：
59+
60+
```json
61+
{
62+
"@context": {
63+
"@vocab": "https://schema.org/",
64+
"did": "https://w3id.org/did#",
65+
"ad": "https://agent-network-protocol.com/ad#"
66+
},
67+
"@type": "CollectionPage",
68+
"url": "https://agent-network-protocol.com/agent-descriptions",
69+
"items": [
70+
{
71+
"@type": "ad:AgentDescription",
72+
"name": "Smart Assistant",
73+
"@id": "https://agent-network-protocol.com/agents/smartassistant/ad.json"
74+
},
75+
{
76+
"@type": "ad:AgentDescription",
77+
"name": "Customer Support Agent",
78+
"@id": "https://agent-network-protocol.com/agents/customersupport/ad.json"
79+
}
80+
],
81+
"next": "https://agent-network-protocol.com/agent-descriptions/page2.json"
82+
}
83+
```
84+
85+
#### 分页机制
86+
87+
当域名下有大量智能体时，应采用分页机制。分页通过`next`属性实现，指向下一页的URL。客户端应递归获取所有页面，直到没有`next`属性为止。
88+
89+
### 被动发现
90+
91+
被动发现是指智能体主动将自身的智能体描述URL提交给其他智能体（通常是搜索服务智能体），使其能够索引和爬取自身信息。
92+
93+
#### 注册API
94+
95+
被动发现通常需要使用搜索服务智能体提供的注册API。这些API由搜索服务智能体自行定义，应在其智能体描述文档中明确说明。智能体可以通过调用这些API将自身描述URL注册到搜索服务中。
96+
97+
#### 注册流程
98+
99+
1. 智能体获取搜索服务智能体的描述文档
100+
2. 从描述文档中找到注册API的端点和参数要求
101+
3. 构造注册请求，包含自身的智能体描述URL和其他必要信息
102+
4. 发送注册请求到搜索服务
103+
5. 搜索服务验证请求并索引该智能体
104+
105+
```mermaid
106+
sequenceDiagram
107+
participant Agent as 智能体
108+
participant Search as 搜索服务智能体
109+
110+
Agent->>Search: 获取智能体描述文档
111+
Search-->>Agent: 返回描述文档（包含注册API信息）
112+
Note over Agent: 从描述文档中解析注册API
113+
Agent->>Search: 发送注册请求（包含自身描述URL）
114+
Note over Search: 验证请求
115+
Search-->>Agent: 确认注册
116+
Note over Search: 爬取智能体描述文档并索引
117+
```
118+
119+
### 安全考虑
120+
121+
为确保智能体发现的安全性，建议采取以下措施：
122+
123+
1. **内容验证**: 搜索服务应验证智能体描述文档的有效性和完整性
124+
2. **DID认证**: 使用did:wba方法进行身份认证，确保智能体身份的真实性
125+
3. **限流机制**: 实施适当的限流措施，防止恶意请求和DoS攻击
126+
4. **权限控制**: 区分公开和私有智能体，只在发现文档中包含公开智能体
127+
128+
## 与其他协议的关系
129+
130+
智能体发现协议与以下协议密切相关：
131+
132+
1. **智能体描述协议**: 发现协议提供了描述文档的索引和访问机制
133+
2. **DID:WBA方法**: 提供了身份验证和安全保障
134+
3. **元协议**: 在智能体通信中可基于发现结果进行协议协商
135+
136+
## 版权声明
6137
Copyright (c) 2024 GaoWei Chang
7-
本文件依据 [MIT 许可证](./LICENSE) 发布，您可以自由使用和修改，但必须保留本版权声明。
138+
本文件依据 [MIT 许可证](./LICENSE) 发布，您可以自由使用和修改，但必须保留本版权声明。

0 commit comments

Comments
 (0)