Skip to content

Commit 018233d

Browse files
ognis1205ognis1205
committed
docs: update specification.md
Signed-off-by: Shingo OKAWA <shingo.okawa.g.h.c@gmail.com> fix(docs): replace typographic apostrophe Signed-off-by: Shingo OKAWA <shingo.okawa.g.h.c@gmail.com>
1 parent 33bb5de commit 018233d

File tree

1 file changed

+8
-42
lines changed

1 file changed

+8
-42
lines changed

‎docs/specification.md‎

Lines changed: 8 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -2188,9 +2188,9 @@ Clients verifying Agent Card signatures **MUST**:
21882188

21892189
The Agent Catalog extends the agent discovery mechanism to support **open discovery of multiple agents served under a shared origin**.
21902190

2191-
In the core specification ([Section 5](#5-agent-discovery-the-agent-card)), open discovery is typically performed using a well-known location—`/.well-known/agent.json`—which is the recommended way to expose an individual agent's Agent Card. This approach implicitly assumes a **one-agent-per-host** or **per-base-path** model, where each agent has its own dedicated and discoverable entry point.
2191+
In the core specification ([Section 8](#5-agent-discovery-the-agent-card)), open discovery is typically performed using a well-known location—`/.well-known/agent-card.json`—which is the recommended way to expose an individual agent's Agent Card. This approach implicitly assumes a **one-agent-per-host** model, where each agent has its own dedicated and discoverable entry point.
21922192

2193-
However, in real-world deployments, it is common for a single host or gateway to serve **multiple agents**, each accessible via distinct subpaths (e.g., `/a2a/agent1`, `/a2a/agent2`). The `/.well-known/agent.json` mechanism does not support enumerating such multi-agent deployments.
2193+
However, in real-world deployments, it is common for a single host or gateway to serve **multiple agents**, each accessible via distinct subpaths (e.g., `/a2a/v1/agent1`, `/a2a/v1/agent2`). The `/.well-known/agent-card.json` mechanism does not support enumerating such multi-agent deployments.
21942194

21952195
To address this limitation, the Agent Catalog adopts the [API Catalog format (RFC 9727)](https://datatracker.ietf.org/doc/rfc9727/) as standardized by the IETF.
21962196

@@ -2200,10 +2200,10 @@ Clients can discover Agent endpoints and Agent Cards through the following mecha
22002200

22012201
- **Well-Known URI:** The Agent Catalog is exposed at a standard location such as `/.well-known/api-catalog` on the shared origin. This location is defined as a well-known URI in [RFC 9727](https://datatracker.ietf.org/doc/rfc9727/), enabling clients to locate catalogs in a consistent and interoperable manner.
22022202

2203-
The Agent Catalog follows the [API Catalog format](https://datatracker.ietf.org/doc/rfc9727/), which is based on the [Linkset](https://datatracker.ietf.org/doc/rfc9264/) specification. This format allows a server to expose a collection of agent endpoints in a standardized structure, where each entry consists of:
2203+
The Agent Catalog follows the [API Catalog format](https://datatracker.ietf.org/doc/rfc9727/), which is based on the [Linkset](https://datatracker.ietf.org/doc/rfc9264/) specification. This format allows a server to expose a collection of agent endpoints in a standardized structure, where each entry may include:
22042204

2205-
- **An `anchor`:** The base URI for an individual agent (e.g., `https://example.org/a2a/agent1`)
2206-
- **A `describedby` link:** Pointing to the agent's own Agent Card, which describes its capabilities and interface (e.g., `https://example.org/a2a/agent1/agent.json`)
2205+
- **An `anchor` (optional):** The base URI for an individual agent (e.g., `https://example.org/a2a/v1/agent1`), if applicable.
2206+
- **Link relations to the agent's description:** Typical examples include `describedby`, `service-desc`, or `service-meta`. Implementations may also use a URI pointing to the relevant section of the Agent Card specification (e.g., `https://a2a-protocol.org/latest/specification/#5-agent-discovery-the-agent-card`) as the link relation.
22072207

22082208
This mechanism enables clients to enumerate all available agents under a shared origin and fetch their respective Agent Cards dynamically. It makes agent discovery interoperable, extensible, and well-suited for federated or platform-hosted environments.
22092209

@@ -2213,41 +2213,7 @@ Agent Catalogs may expose sensitive metadata depending on deployment context.
22132213

22142214
For further considerations and best practices regarding the publication and protection of API Catalogs, refer to the [Security Considerations](https://datatracker.ietf.org/doc/rfc9727/) section of the RFC.
22152215

2216-
### 8A.4. `AgentCatalog` Object Structure
2217-
2218-
```ts { .no-copy }
2219-
--8<-- "types/src/types.ts:AgentCatalog"
2220-
```
2221-
2222-
| Field Name | Type | Required | Description |
2223-
| :------------ | :---------------------------------------------------- | :------- | :----------------------------------------------- |
2224-
| `linkset` | [`AgentLinkContext[]`](#8a41-agentlinkcontext-object) | Yes | An array of agent-specific link context objects. |
2225-
2226-
### 8A.4.1. `AgentLinkContext` Object
2227-
2228-
Represents a [Link Context (RFC 9264 §4.2.2.)](https://datatracker.ietf.org/doc/rfc9264/) object specifically for agents. Extends the general Link Context structure by requiring an `anchor` field and including a `describedby` relation to link to the agent's card endpoint.
2229-
2230-
```ts { .no-copy }
2231-
--8<-- "types/src/types.ts:AgentLinkContext"
2232-
```
2233-
2234-
| Field Name | Type | Required | Description |
2235-
| :---------------------- | :-------------------------------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------- |
2236-
| `anchor` | `string` | Yes | A URI identifying the agent's primary endpoint. MUST be an absolute URI. |
2237-
| `describedby` | [`AgentLinkTarget[]`](#8a42-agentlinktarget-object) | Yes | A list of links to the agent's metadata (Agent Card). |
2238-
| *Additional properties* | `unknown` | No | Additional [link relation types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) MAY be included as needed. |
2239-
2240-
### 8A.4.2. `AgentLinkTarget` Object
2241-
2242-
Represents a [Link Target (RFC 9264 §4.2.3.)](https://datatracker.ietf.org/doc/rfc9264/) object that specifically points to an agent card in JSON format. This is a specialization of the generic Link Target with a fixed media type of `application/json` as required for agent metadata.
2243-
2244-
| Field Name | Type | Required | Description |
2245-
| :---------------------- | :------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------- |
2246-
| `href` | `string` | Yes | A URI pointing to the agent's metadata (Agent Card). MUST be absolute. |
2247-
| `type` | `"application/json"` | Yes | The media type of the Agent Card. MUST be `"application/json"` to conform to A2A expectations. |
2248-
| *Additional properties* | `unknown` | No | Extension attributes may be included, as defined in [RFC 9264 §4.2.4.](https://www.rfc-editor.org/rfc/rfc9264#section-4.2.4). |
2249-
2250-
### 8A.5. Sample Agent Catalog
2216+
### 8A.4. Sample Agent Catalog
22512217

22522218
```json
22532219
{
@@ -2256,15 +2222,15 @@ Represents a [Link Target (RFC 9264 §4.2.3.)](https://datatracker.ietf.org/doc/
22562222
"anchor": "https://georoute-agent.example.com/a2a/v1/route_planner",
22572223
"describedby": [
22582224
{
2259-
"href": "https://georoute-agent.example.com/a2a/v1/route_planner/agent.json",
2225+
"href": "https://georoute-agent.example.com/a2a/v1/route_planner/agent-card.json",
22602226
"type": "application/json",
22612227
"title": "GeoSpatial Route Planner Agent Card"
22622228
}
22632229
]
22642230
},
22652231
{
22662232
"anchor": "https://georoute-agent.example.com/a2a/v1/poi_finder",
2267-
"describedby": [
2233+
"https://a2a-protocol.org/latest/specification/#5-agent-discovery-the-agent-card": [
22682234
{
22692235
"href": "https://georoute-agent.example.com/a2a/v1/poi_finder/agent.json",
22702236
"type": "application/json",

0 commit comments

Comments
 (0)