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

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

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

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

しかし、別のエージェントがそれを発見するには、それだけでは不十分です。

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

本当に欲しいのは、次の用途に使える1つの公開アドレスです：

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

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

発見の問題

別のエージェントがあなたのエージェントで作業したいなら、いくつかの基本が必要です：

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

それをREADME、ドキュメントサイト、APIリファレンスに散らすこともできますが、それでは利用者ごとにスクレイピングと推測が必要になります。

よりきれいなパターンはエージェントカードを公開することです。標準的な形でエージェントを記述する、機械で読み取れるJSONドキュメントを1つ提供するだけです。

概観すると、こうなります：

{
  "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：ページを申請する

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": "有用なことを実行します",
  "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
by Your Name - coding

> 有用なことを実行します

## Links

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

これにより、公開URLをそのまま維持しつつ、LLMベースのシステムにとって raw 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分で完了し、その後あなたのエージェントには、ドキュメントの羅列だけではなく公開されたホームが作成されます。