【ITニュース解説】Why We Chose `input()` Over `run()`

システムエンジニアを目指す皆さんにとって、ソフトウェア開発の現場では多くの技術的な選択に直面することになります。その中でも特に、利用者が直接触れる部分、つまり「ユーザーインターフェース」や「API（アプリケーションプログラミングインターフェース）」の設計は非常に重要です。今回のニュース記事は、まさにそのAPI設計におけるたった一つのメソッド名の選択が、いかに大きな影響を与えるかを示した興味深い事例です。

ある企業が開発した「ConnectOnion」というフレームワークでは、AIエージェントとやり取りするための主要なメソッド名を決める必要がありました。彼らは最初、多くの業界で一般的な慣習に従い、「agent.run(prompt)」という名前を採用しました。ここで「prompt」とは、エージェントに指示や質問を与えるためのテキストを指します。「エージェントがタスクを『実行する（run）』のだから、この名前は論理的だ」と彼らは考えたのです。

しかし、実際にユーザーがこのAPIを使い始めると、予期せぬ問題が明らかになりました。多くのユーザーから、「エージェントをどう使えばいいのかわからない」という声が寄せられたのです。詳しく調査すると、「run」という言葉がユーザーの心の中で「認知的な摩擦」を生み出していることがわかりました。ユーザーはエージェントに対して「何か質問したい」と考えているのに、APIを使う際には「エージェントを『実行する（run）』必要がある」と、自分の意図を技術的な用語に頭の中で変換しなければならなかったのです。この小さな手間が、何千ものユーザーに毎日発生することで、全体の使いづらさとして積み重なっていきました。

この問題に対処するため、ConnectOnionの開発チームは、ドキュメントを全く読まない新しいユーザーが、APIをどう使おうとするかを徹底的に調査しました。その結果は驚くべきものでした。最も多くのユーザーが最初に試したのは「agent.input()」で、全体の40%にも上りました。次に多かったのが「agent.ask()」の18%、そして「agent.chat()」が15%でした。当初採用していた「agent.run()」を試したのは、わずか12%に過ぎませんでした。このデータは明確な事実を物語っていました。ユーザーは、エージェントが「何をするか（run/process）」という視点ではなく、「自分がエージェントに『何をするか（input/ask/chat）』」という視点で考えていたのです。

この調査結果を受け、チームはいくつかの代替案を真剣に検討しました。例えば、「agent.chat(prompt)」は会話的で親しみやすいように見えますが、常に会話を続ける「ステートフル（状態を持つ）」な状態を暗示してしまうため、実際のユースケースに合わない場合があります。また、「agent.ask(prompt)」は質問には適していますが、「ファイルを削除しろ」といったコマンドには不自然です。「agent.prompt(prompt)」は技術的には正確であるものの、名詞と動詞が混同されやすく、初心者には直感的ではありません。「agent.process(prompt)」はエージェントの内部的な動作を表しますが、技術的な専門用語であり、ユーザーの思考とはかけ離れています。「agent.invoke(prompt)」はより専門的な印象を与えますが、初心者には威圧的に感じられる可能性があります。

最終的に、彼らは「agent.input(prompt)」という選択肢に注目しました。この言葉はユーザーのメンタルモデルに完全に合致し、あらゆる種類のインタラクションに対応でき、それ自体が何をすべきかを示唆する「自己説明的」な特性も持っていました。さらに、開発チームは「モムテスト（Mom Test）」と呼ばれるシンプルな評価基準を用いました。これは、技術的知識のない人、例えばお母さんでも、そのメソッドが何をするかを推測できるか、というテストです。「agent.input("Translate this to Spanish: Hello")」は、誰にとっても「何かを入力する」という意図が明確に伝わりましたが、「agent.run(...)」や「agent.invoke(...)」は非開発者には混乱を招きました。「input」がこのテストに合格したのです。

この選択の背後には、より深い設計原則がありました。それは「APIはシステムの視点ではなく、ユーザーの視点から設計すべきである」というものです。システムの視点では、エージェントはプロンプトを受け取り、それを処理し、推論を行い、ツールを実行し、最終的に応答を返します。しかし、ユーザーの視点では、単に「私が入力を与え、私が出力を受け取る」という、はるかにシンプルで直感的な流れです。ユーザーはエージェントの内部的な複雑な処理について考える必要はありません。

メソッド名を「run」から「input」へ変更する作業自体は、コードで言えばたった1行の修正でした。しかし、その影響は計り知れませんでした。変更後、ユーザーがConnectOnionのサポートチャンネルで「エージェントの使い方は？」と質問する頻度が60%も減少しました。さらに、新しいユーザーが初めてエージェントを成功裏に呼び出す割合が、以前の67%から89%へと大幅に向上しました。最初の成功までにかかる時間も40%短縮され、基本的な使い方についてドキュメントを探すユーザーも55%減少したのです。たった一つの言葉の変更が、これほど劇的な効果をもたらしました。

この経験から、彼らはいくつかの重要な教訓を得ました。第一に、業界の慣習であっても、それが本当に最善なのか常に疑問を持つことの重要性です。「皆が使っているから」という理由だけで採用するのではなく、その妥当性を問うべきです。第二に、個人の意見や推測よりも、実際のユーザー行動を示す「データ」が最終的な判断を下す上で最も強力な証拠となることです。そして第三に、たった三文字の言葉（runからinputへ）のような小さな変更でも、ユーザー体験全体に大きな影響を与え得るということです。第四に、システムがどう動くかではなく、ユーザーがどう考えるか、つまり「メンタルモデル」に合わせて設計することの価値です。最後に、最も優れたAPIは、ユーザーが使い方を推測できるため、ほとんどドキュメントを必要としない、という教訓です。ユーザーが正しく推測できたとき、それは適切な名前を見つけた証拠なのです。

この「input()」の選択は、ConnectOnionのAPI設計における全体的な哲学を形成するきっかけとなりました。彼らは、技術的な正確さよりもユーザー体験を優先するという強いコミットメントを示しました。ユーザーが「agent.input("2+2は何ですか？")」と入力する時、彼らは内部の実行モデルや処理パイプラインについて考えているわけではありません。単にエージェントに何かを「入力している」とだけ考えているのです。このシンプルさが、最も重要なポイントでした。

ConnectOnionが実践した哲学は、「シンプルなことはシンプルに感じられるべきである」「APIはユーザーのメンタルモデルに合致すべきである」「ユーザー体験は技術的な正確さに勝る」「データは意見に勝る」「慣習を含め、すべてに疑問を持つべきである」というものです。開発者がAPIを使っていることすら忘れてしまうような、自然で直感的なAPIこそが、最高のデザインであると彼らは結論付けました。

これからシステムエンジニアを目指す皆さんも、将来APIやシステムを設計する際には、ぜひ自問してみてください。「この名前は、システムの動作原理から来ているのか、それともユーザーがどのように感じるか、どのように考えるかという視点から来ているのか？」この問いへの答えが、皆さんが作り出すソフトウェアのユーザー体験を大きく変えることになるかもしれません。