AIエージェントの普及により、SaaSのように人間が使うソフトウェアは衰退し、SDKや開発ツールのようにAIエージェントが、直接使うソフトウェアが拡大するという話を聞きました。 AIエージェントにとって使い易いソフトウェアとは、どんなソフトウェアなのでしょうか。 AIエージェントに選ばれるソフトウェアを開発提供するには、どのような努力をすれば良いのでしょうか。
「APIファーストで設計する際の具体的なドキュメントの書き方」をお願いします。
AIエージェントに向けたAPIドキュメント（仕様書）を書く際、最も重要な視点の転換は、**「ドキュメントそのものが、AIへのプロンプト（指示書）になる」**ということです。
人間は行間を読みますが、AIは記述された文字情報を文字通りに、確率的に解釈します。そのため、これまで以上に「言語的な明確さ」と「文脈の補足」が求められます。
具体的に、OpenAPI Specification (Swagger) をベースにした、AIに「伝わる」ドキュメントの書き方のポイントを4つに絞って解説します。
1. description（説明文）は「いつ、なぜ使うか」まで書く
従来のドキュメントでは「機能を説明」していましたが、AI向けには**「目的と文脈」**を含める必要があります。
悪い例（人間ならわかる）:
getUser: ユーザー情報を取得します。良い例（AIが迷わない）:
getUser: 特定のユーザーIDに基づいて、氏名、メールアドレス、契約プランの詳細を取得します。ユーザーの契約ステータスを確認し、機能制限をかけるべきか判断する際にこのAPIを使用してください。
ポイント:
- 単なる機能定義ではなく、「どのようなタスクの時にこのツール（API）を呼び出すべきか」という判断基準を記述します。
2. パラメータ名は「推論しやすい」名前で、制約を明記する
AIは変数名から意味を推測します。曖昧な名前はハルシネーション（誤動作）の原因になります。
悪い例:
q(何のクエリかわからない)type(数値なのか文字列なのか、何の種類かわからない)
良い例:
search_keyword(検索ワードだと明確)report_format_type(レポートの形式だと明確)
制約条件（Validation）の記述: パラメータのルールも自然言語とスキーマの両方で明示します。
「日付は
YYYY-MM-DD形式の文字列で指定してください。未来の日付は指定できません。」
3. operationId をユニークで意味のあるものにする
OpenAPIにおける operationId は、多くのAIエージェントが**「関数の名前」**として認識する重要な識別子です。
- 避けるべき:
get_1,api_v1_data - 推奨:
find_products_by_category,update_customer_shipping_address
これが適切に設定されていると、AIはユーザーから「住所を変更したい」と言われた時に、即座に update_customer_shipping_address を実行すべきだと結びつけることができます。
4. 具体的な Example（使用例）を豊富に用意する
これが**最も効果的な「AIへの努力」**です。LLMにおける「Few-shot Prompting（例示による学習）」の効果をAPI利用に応用します。
リクエストとレスポンスの完全なペアを例示することで、AIは「こういうデータを送れば、こういうデータが返ってくる」という確信を持って実行できます。
【比較】人間用 vs AIエージェント用
商品検索APIを例に、書き方の違いを比較します。
❌ 従来の人間向け（最小限）
paths:
/items:
get:
summary: 商品検索
parameters:
- name: k
in: query
description: キーワード
responses:
200:
description: OK
AIの反応: 「
kって何？ キーワード？ カテゴリ？ 何が返ってくるの？ 試すのが怖いな……」
⭕️ AIエージェント向け（リッチな記述）
paths:
/products/search:
get:
operationId: searchProductsByName
summary: 商品名によるカタログ検索
description: |
ユーザーが特定の商品を探している場合に実行します。
商品名、ブランド名、または型番から在庫商品を検索し、価格と在庫状況を返します。
ユーザーが漠然としたカテゴリ（例：「靴」）を求めている場合は、このAPIではなく `browseCategories` を使用してください。
parameters:
- name: query_string
in: query
required: true
description: 検索したい商品名の一部（例：「ワイヤレスイヤホン」）。最低2文字以上。
schema:
type: string
minLength: 2
responses:
200:
description: 検索結果のリスト
content:
application/json:
schema:
$ref: '#/components/schemas/ProductList'
examples:
success_response:
value:
count: 1
items:
- id: "p-12345"
name: "ノイズキャンセリングヘッドホン Pro"
price: 25000
in_stock: true
AIの反応: 「ユーザーが商品を探しているから、この
searchProductsByNameを使えばいいんだな。query_stringにユーザーが言った単語を入れて、2文字以上であることを確認して送信しよう」
まとめ
AIエージェントに選ばれるAPIドキュメントとは、**「コードとしての正確さ」と「自然言語としての分かりやすさ」**が融合したものです。
開発者にとっては「コメントを詳しく書く」ことに似ていますが、その読み手が「同僚のエンジニア」から「超高速で動くが、たまに勘違いをするAI」に変わったと意識して記述することが、成功の鍵です。
次のアクション
このようにAPIドキュメントを整備した後、実際にAIエージェントが正しくAPIを使えるかどうかを確認する必要があります。
**「AIエージェントに自社のAPIをテストさせる（評価させる）具体的な手法」について提案しましょうか？ それとも、先ほど少し触れた「Model Context Protocol (MCP) を使って、これをさらに簡単に実装する方法」**に進みますか？
「Model Context Protocol (MCP)」の仕組みや、導入のメリット
「Model Context Protocol (MCP) を使って、これをさらに簡単に実装する方法」
をお願いします。
Model Context Protocol (MCP) は、まさに先ほど議論した「AIエージェントに選ばれるソフトウェア」を最も効率的に実現するための**「USB規格（ユニバーサルな接続口）」**のようなものです。
Anthropic（Claudeの開発元）がオープンソースとして公開しましたが、特定のAIモデルに依存しない汎用的な規格です。
MCPの「仕組み」「メリット」、そして先ほどのAPIドキュメントの話を踏まえた「簡単な実装方法」について解説します。
1. MCPの仕組み：AIにとっての「USB Type-C」
これまで、AIエージェントに自社のソフトを使わせるには、個別の連携コード（Integration）を書く必要がありました。
- これまで: Claude用、ChatGPT用、IDE用…と、個別に接続コードを書く必要があった（変換アダプタが大量に必要な状態）。
- MCPの世界: 自社ソフトを「MCPサーバー」として一度作れば、Claude DesktopやCursor、その他MCP対応のあらゆるAIツールが即座に認識して使えるようになる（USB Type-Cポートを一つ作れば、どこにでも刺さる）。
構成要素
MCPは以下の3つの要素で構成されます。
- MCP Host (Client): AIアプリケーション側（例: Claude Desktopアプリ, Cursor, IDE）。
- MCP Server: あなたが開発する部分。自社のデータやAPIをMCPの形式に翻訳して提供する「アダプタ」。
- Local/Remote Connection: これらを繋ぐ通信（標準入出力やHTTPなど）。
AI（Host）が「現在の在庫を知りたい」とリクエストすると、MCP Serverが自社のDBを検索し、AIが理解しやすい形式で結果を返します。
2. 導入のメリット：なぜMCPが「選ばれる」近道なのか
① 「接続」が標準化される（One-to-Many）
一度MCPサーバーを作ってしまえば、今後登場する新しいAIエージェントやツールがMCPに対応している限り、追加の開発なしで自動的にサポート対象になります。
② コンテキスト（文脈）の管理を委譲できる
先ほど「コンテキストは軽量であるべき」と述べましたが、MCPには**「リソース（Resources）」**という概念があります。 AIはファイルの中身を全部読み込むのではなく、「このファイルの要約だけ欲しい」「この行だけ読みたい」といったリクエストを投げることができます。これにより、AI側のメモリ（トークン）を節約しつつ、必要な情報だけを効率的に渡せます。
③ 安全なサンドボックス
MCPは、AIが勝手に全てを操作できないように設計されています。ユーザーは「このMCPサーバーを有効にするか？」「このコマンドを実行して良いか？」を承認するプロセスが組み込まれているため、セキュリティ面でも信頼されやすくなります。
3. MCPを使って「簡単に」実装する方法
先ほど「APIドキュメント（Swagger）を頑張って書く」という話をしましたが、MCPを使うと、コードを書くだけで、最強のドキュメントが自動的に生成されるイメージに近いです。
MCP SDK（TypeScriptやPython用が提供されています）を使うと、プログラムの関数を定義する感覚で、AIへのインターフェースを作れます。
具体的な実装イメージ（Pythonの例）
「商品在庫を検索する」機能をMCPで実装する場合、以下のように書くだけです。
from mcp.server.fastmcp import FastMCP
# MCPサーバーの定義
mcp = FastMCP("Inventory System")
# ツール（AIが使う機能）の定義
# デコレータ(@mcp.tool)をつけるだけで、関数がAI用ツールになる
@mcp.tool()
def search_product_stock(product_name: str) -> str:
"""
商品名から在庫状況を検索します。
ユーザーが商品の有無や価格を知りたい時に使用してください。
"""
# ここに実際のDB検索ロジックを書く
# 例: result = db.query("SELECT * FROM products WHERE name = ...")
# AIへの返答（文字列で返す）
return f"{product_name}の在庫は残り5個です。価格は12,000円です。"
# サーバー起動
if __name__ == "__main__":
mcp.run()
なぜこれが「簡単」なのか？
- ドキュメント記述の手間が減る:
上記のコードの
"""..."""(docstring) や引数の型ヒント(product_name: str)を、MCP SDKが自動的に読み取り、AIに最適なJSON形式の定義書（プロンプト）に変換してAIへ渡してくれます。 → 「Swaggerファイルを細かく書く」という苦行から解放されます。 - 型安全: PythonやTypeScriptの型システムを使うため、パラメータの受け渡しミス（文字列なのに数字が来た、など）をコードレベルで防げます。
- 開発体験が良い: 既存のビジネスロジック（社内APIなど）がある場合、それをこのラッパー関数で包むだけで、すぐに「AI対応ソフトウェア」が出来上がります。
結論：AIエージェント時代の開発戦略
AIエージェントに選ばれるソフトウェアを作るための最短ルートは以下の通りです。
- コア機能はAPI化する: そもそもAPIがないと始まりません。
- MCPサーバーを実装する: 既存のAPIをラップする形で、MCP SDKを使って「AI用アダプタ」を提供します。
- ドキュメントはコード内に書く: MCPのツール定義にある説明文（docstring）を、AIへの「指示書」だと思って丁寧に書きます。
これにより、人間用のGUI開発にかけるリソースを温存しつつ、AIエージェントのエコシステムに自社製品を滑り込ませることが可能になります。
ご指摘の通り、AIエージェントの台頭により、ソフトウェアのあり方は「人間が見て操作するもの（GUI）」から「AIが読んで実行するもの（API/インターフェース）」へと急速にシフトしつつあります。
これを「Agentic Interface（エージェンティック・インターフェース）」や「Headless（ヘッドレス）」化と呼びます。
AIエージェントにとって「使いやすい」、そして「選ばれる」ソフトウェアになるための要件と、開発者が注力すべき努力について体系的に解説します。
1. AIエージェントにとって「使いやすい」ソフトウェアとは？
人間は「視覚的なわかりやすさ（直感的なUI）」を求めますが、AIエージェントは「論理的な明確さと予測可能性」を求めます。具体的には以下の3つの要素が重要です。
① 機械可読性が高い（Machine-Readable）
AIは画面を見ているわけではなく、コードやテキストデータを読み解いています。
② 予測可能で、失敗に強い（Deterministic & Robust）
AIは試行錯誤を行いますが、結果がランダムだと混乱します。
③ コンテキスト（文脈）が軽量である
現在のAIモデルには処理できる情報量（コンテキストウィンドウ）に限りがあり、かつ課金対象になります。
2. AIエージェントに「選ばれる」ための開発・提供の努力
AIエージェント（およびその背後にいるLLM）に自社のソフトウェアを「ツール」として認識させ、選択してもらうためには、以下の努力が必要です。
A. インターフェースの標準化対応
現在、AIエージェントが外部ツールを使うための「規格」が生まれつつあります。これらに準拠することが、選ばれるための最短ルートです。
B. 「AI向けのSEO」を意識する
検索エンジン最適化（SEO）と同様に、AIがドキュメントを読み込みやすくする工夫が必要です。これをLMO (Large Model Optimization) と呼ぶこともあります。
var1ではなくcustomer_email_addressとする）C. 認証・セキュリティの簡素化と強化
AIエージェントがログイン画面で「私はロボットではありません」という画像認証を突破するのは困難です。
D. ビジネスモデルの転換
従来の「1ユーザーあたり月額〇〇円」というSaaSの課金モデルは、超高速で大量処理を行うAIエージェントにはそぐわない場合があります。
まとめ：人間用とAI用の共存
当面の間は、ソフトウェア開発において「二重のアプローチ」が必要になります。
今後は、「APIの出来が良いソフトウェアほど、AIエージェントのエコシステムに組み込まれ、結果として人間にも選ばれる」という時代になります。StripeやTwilioのような「開発者（＝今はAI）体験」に優れたツールが勝者となるでしょう。
次のアクション
AIエージェントとの接続標準として急速に注目されている「Model Context Protocol (MCP)」の仕組みや、導入のメリットについて詳しく掘り下げましょうか？ それとも、APIファーストで設計する際の具体的なドキュメントの書き方について知りたいですか？