AIエージェントのための1つのURL：HTML、JSON、Markdown、そしてA2Aカード

Dev.to / 2026/4/15

💬 オピニオンDeveloper Stack & InfrastructureIdeas & Deep AnalysisTools & Practical Usage

原文を読む →

共有:

要点

この記事では、多くのAIエージェントのプロジェクトが単一で安定した公開アイデンティティを持っておらず、そのため他のエージェントがそれらを確実に発見し、統合することが難しいと主張しています。
その解決策として、複数の表現に対応する「1つの共有URL」を公開することを提案します。すなわち、人が閲覧するためのHTMLプロファイル、機械が読み取れるJSONインターフェース、そしてLLM（大規模言語モデル）に適したMarkdown版です。
「A2Aエージェントカード」（標準化されたJSONドキュメント）を用いることで、エージェントの名前、説明、バージョン、対応インターフェース、発見（ディスカバリ）に関する情報を明確に記述できることを強調しています。
他のエージェントが必要とする主要情報――スキル、プロトコル、エンドポイントの場所、認証――を説明した上で、それらをREADMEやドキュメントに分散させると、利用者がスクレイピングや推測によって情報を取得しなければならなくなる点を指摘しています。
結論として、エージェントがサービスとどのようにやり取りすべきかを見つけるための、予測可能で構造化された方法を提供することで、共有、インデックス（登録）、および自動統合が改善されると述べています。

あなたはエージェントを作りました。

たぶんGitHubリポジトリがあります。たぶんMCPサーバーがあります。あるいは、ドキュメントのどこかにRESTエンドポイントが隠れているかもしれません。

それが存在することを知るには、それで十分です。

別のエージェントがそれを発見するには、それでは足りません。

今の多くのエージェントプロジェクトで私がずっと気づいているギャップがあります。エージェントは動くのに、その公開上のアイデンティティがまだ曖昧だということです。人間に「何をするのか」を伝え、機械に「どうやってやりとりするのか」を教える単一で安定したURLがありません。

本当に欲しいのは、次を提供できる公開アドレスを1つにまとめることです：

人間向けのHTMLプロフィール
ツールやスクリプト向けのJSON
LLMが取り込みやすいためのmarkdown
構造化された発見のためのA2Aエージェントカード

それが揃えば、あなたのエージェントは共有・インデックス・統合がはるかに簡単になります。

発見の問題

別のエージェントがあなたのものと連携したいなら、いくつかの基本的な情報が必要です：

エージェントの名前と説明
公開しているスキル
話すプロトコル
実際のエンドポイントの場所
それらのエンドポイントが必要とする認証の種類

それをREADME、ドキュメントサイト、APIリファレンスに散らしてしまうことはできますが、すると各利用者がスクレイピングして推測することを強いられます。

よりきれいなパターンはエージェントカードを公開することです。つまり、エージェントを標準化された形で説明する、機械が読み取れる1つのJSONドキュメントです。

大まかには、次のような形になります：

{
  "name": "Code Reviewer",
  "description": "Reviews PRs and catches bugs before your team does",
  "version": "1.0.0",
  "supportedInterfaces": [
    {
      "url": "https://example.com/your-agent",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "provider": {
    "organization": "Your Name",
    "url": "https://example.com/your-agent",
  },
  "skills": [
    {
      "id": "review",
      "name": "Code Review",
      "description": "Reviews pull requests and catches regressions",
      "tags": [ "coding"]
    }
  ],
  "documentationUrl": "https://example.com/your-agent"
}

これにより、別のエージェントは明確な出発点を得られます。1つのドキュメントを取得し、対応できる機能を確認し、次に何と呼べばいいかを判断できます。

私が考える、エージェントに必要なパターン

重要なのは、正確なホストやフレームワークではありません。重要なのは、エージェントが複数の有用な表現を持つ安定した公開URLを持つべきだということです。

たとえば：

https://example.com/my-agent 人間向けのページ用
https://example.com/my-agent?format=json 公開JSON用
GET /my-agent Accept: text/markdown を使ってmarkdown用
https://example.com/my-agent/agent-card.json 構造化されたエージェントカード用

これで、1つのアイデンティティと、同じメタデータの複数のビューが手に入ります。

人間は普通のページを見ます。スクリプトはJSONを受け取ります。LLMベースのシステムはmarkdownを取り込めます。A2Aに対応したクライアントは、期待しているエージェントカードを取得できます。

私は、すべてのエージェントプロジェクトにそれぞれ独自の発見ストーリーを発明させるより、この方がはるかに良いパターンだと思います。

agents.mlでこれを行うシンプルな方法

agents.ml は、このまさにそのアイデアを軸に作られたAIエージェントの公開ディレクトリです。

あなたはエージェントを一度登録するだけで、次が得られます：

agents.ml/your-agent に永続的なURL
agents.ml/your-agent/agent-card.json にライブなA2Aエージェントカード
agents.ml/your-agent?format=json に公開JSON表現
同じURLからのmarkdown
READMEバッジ

メールで登録し、リンクを確認すると、ページが公開されます。

エージェントの登録

やり方は2つあります：

agents.ml/claim のWebフォーム
スクリプトでやりたい場合のJSON API

ステップ1：スラッグを確認する

curl https://agents.ml/api/check/my-agent

{"slug":"my-agent","available":true}

スラッグは、小文字の英数字にハイフンを組み合わせたものです。

ステップ2：ページを請求（claim）する

curl -X POST https://agents.ml/api/claim \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "slug": "my-agent",
    "tagline": "Does something useful",
    "author": "Your Name",
    "email": "you@example.com",
    "category": "coding",
    "githubRepo": "https://github.com/you/my-agent",
    "website": "https://my-agent.dev"
  }'

{
  "ok": true,
  "slug": "my-agent",
  "message": "確認メールを送信しました。リンクをクリックして公開してください。",
  "pendingTtlSeconds": 14400
}

必須の項目は次のとおりです:

name
slug
tagline
author
email

それ以外はすべて任意です。

公開URLが提供してくれるもの

1. 人が読めるプロフィールページ

https://agents.ml/my-agent をブラウザで開くと、次のような見やすい公開ページが表示されます:

名前とタグライン
リンク
エンドポイント
スキル
エージェントファイル

これだけでも十分に役に立ちます。というのも、ユーザーに対して指し示すための1つの正規の場所を提供できるからです。

2. 公開JSON

curl https://agents.ml/my-agent?format=json

{
  "name": "My Agent",
  "slug": "my-agent",
  "tagline": "Does something useful",
  "author": "Your Name",
  "category": "coding",
  "endpoints": [],
  "links": [
    {"label": "GitHub", "url": "https://github.com/you/my-agent"},
    {"label": "Website", "url": "https://my-agent.dev"}
  ],
  "url": "https://agents.ml/my-agent"
}

スクリプト、レジストリ、そしてその他の「機械が解釈しやすいプロフィール」をストレートに欲しいものに便利です。

3. A2Aエージェントカード

curl https://agents.ml/my-agent/agent-card.json

これは、プロフィールデータに基づいて生成されたA2Aカードを返します。あとでエンドポイント、認証メタデータ、スキル、リンクを追加すれば、それらがカードにも反映されます。

4. コンテンツネゴシエーションによるMarkdown

curl -H "Accept: text/markdown" https://agents.ml/my-agent

---
name: My Agent
author: Your Name
category: coding
slug: my-agent
url: https://agents.ml/my-agent
---

# My Agent
Your Name による - コーディング

> Does something useful

## Links

- [GitHub](https://github.com/you/my-agent)
- [Website](https://my-agent.dev)

これにより、公開URLは同じままにしつつ、LLMベースのシステムにとっては生のHTMLよりもきれいな表現を提供できます。

5. READMEバッジ

[![Listed on agents.ml](https://agents.ml/badge/my-agent)](https://agents.ml/my-agent)

些細な点ですが、リポジトリと公開エージェントページを互いに指し示したい場合に役に立ちます。

それに加えてJSON-RPCにも対応しています

すべてのプロフィールURLは、ライブなA2AのJSON-RPCエンドポイントでもあります。

例えば:

curl -X POST https://agents.ml/my-agent \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"agent/getCard"}'

これはエージェントカードをJSON-RPCレスポンスで包んで返すため、同じ公開アイデンティティが、プロトコルに形を合わせたディスカバリー要求にも直接応答できます。

後からプロフィールを更新する

ページが公開された後、メールで編集リンクをリクエストして、よりリッチなメタデータを追加できます:

endpoints
認証要件
skills
tags
links
SKILL.md のようなエージェントファイル

公開エージェントURLの価値は、それが存在することだけでなく、エージェントが進化しても使い続けられることにもあります。

なぜこれが重要だと思うのか

多くのエージェントプロジェクトは、いまだにデモのように振る舞っています。動くことはありますが、外部から見つけたり、問い合わせたり、理解したりしにくいのです。

エージェントにとっての最小限の公開アイデンティティは、単にリポジトリへのリンクだけではありません。構造化されたメタデータを備えた、安定したURLです。

これは、大規模なレジストリや複雑なプラットフォームを意味する必要はありません。単に、きれいなパターンを選んでそれに固執する、ということです:

1つの正規URL
複数のマシンが扱いやすい表現
構造化されたエージェントカード
次に何をするかを別のシステムが判断できるだけのメタデータ

それは、より多くのエージェントビルダーが早い段階で標準化すべきだと思う部分です。

素早くそれを行いたい場合は、agents.ml/claimで試すか、APIを直接使うことができます。

curl -X POST https://agents.ml/api/claim \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Agent",
    "slug": "your-agent",
    "tagline": "What it does in one line",
    "author": "You",
    "email": "you@example.com",
    "category": "coding"
  }'

およそ1分かかり、その後、あなたのエージェントはドキュメントの羅列だけではなくパブリックなホームを持つようになります。

💡 この記事が使われたインサイト

AIの最新ニュースをまとめた「今日の要点」で、この記事が取り上げられています。

📅 4/15Dailyインサイトを見る →

Black Hat USA

AI Business

Black Hat Asia

AI Business

CloudflareがAIエージェントへの最適化を目指し、全サービスに対応するCLIの開発を表明

Publickey

日本三大秘境の現場で最先端技術の活用、建機の遠隔・自律操作

日経XTECH

ソフトバンクなど3社、フィジカルAIへの通信ロボとMECの連係が鍵

日経XTECH

AIエージェントのための1つのURL：HTML、JSON、Markdown、そしてA2Aカード

要点

発見の問題

私が考える、エージェントに必要なパターン

agents.mlでこれを行うシンプルな方法

エージェントの登録

ステップ1：スラッグを確認する

ステップ2：ページを請求（claim）する

公開URLが提供してくれるもの

1. 人が読めるプロフィールページ

2. 公開JSON

3. A2Aエージェントカード

4. コンテンツネゴシエーションによるMarkdown

5. READMEバッジ

それに加えてJSON-RPCにも対応しています

後からプロフィールを更新する

なぜこれが重要だと思うのか

💡 この記事が使われたインサイト

関連記事

Black Hat USA

Black Hat Asia

CloudflareがAIエージェントへの最適化を目指し、全サービスに対応するCLIの開発を表明

日本三大秘境の現場で最先端技術の活用、建機の遠隔・自律操作

ソフトバンクなど3社、フィジカルAIへの通信ロボとMECの連係が鍵

関連おすすめサービス

Notta搭載AI議事録イヤホン ZENCHORD1

AI搭載ボイスレコーダー Plaud

画像高画質化AIツール Aiarty Image Enhancer

要点

発見の問題

私が考える、エージェントに必要なパターン

agents.mlでこれを行うシンプルな方法

エージェントの登録

ステップ1：スラッグを確認する

ステップ2：ページを請求（claim）する

公開URLが提供してくれるもの

1. 人が読めるプロフィールページ

2. 公開JSON

3. A2Aエージェントカード

4. コンテンツネゴシエーションによるMarkdown

5. READMEバッジ

それに加えてJSON-RPCにも対応しています

後からプロフィールを更新する

なぜこれが重要だと思うのか

💡 この記事が使われたインサイト

関連記事

Black Hat USA

Black Hat Asia

CloudflareがAIエージェントへの最適化を目指し、全サービスに対応するCLIの開発を表明

日本三大秘境の現場で最先端技術の活用、建機の遠隔・自律操作

ソフトバンクなど3社、フィジカルAIへの通信 ロボとMECの連係が鍵

関連おすすめサービス

Notta搭載AI議事録イヤホン ZENCHORD1

AI搭載ボイスレコーダー Plaud

画像高画質化AIツール Aiarty Image Enhancer

ソフトバンクなど3社、フィジカルAIへの通信ロボとMECの連係が鍵