Smart Endpoints and Dumb Pipes
自然言語フロントドアと API 契約の分離
原則:エージェントは自然言語フロントドアとして追加する
仮説:自然言語の入力を解釈してサービスの API に橋渡しできる。この変換を経由しても API の契約は変わらない。
ソースコードと観察記録を見る →Observations
設計仮説に対して実際のソースコードと動作ログを証拠として示します。各観察は独立したページとして記録されています。
検証範囲
このサイトの Observation は food-delivery-demo を対象に取得したコード断片・API 仕様・実行記録に限定されます。未掲載の環境・期間・運用条件へは一般化しません。
この証拠記録の読み方
各ページは「検証した仮説 → ソースコードの証拠 → 観察された振る舞い」の順で構成しています。 「なぜこの仮説を支持できるか」の説明は Conclusions にまとめています。 このページ群の目的は、まず証拠を示すことです。
Smart Endpoints and Dumb Pipes
原則:エージェントは自然言語フロントドアとして追加する
仮説:自然言語の入力を解釈してサービスの API に橋渡しできる。この変換を経由しても API の契約は変わらない。
ソースコードと観察記録を見る →Smart Endpoints and Dumb Pipes
原則:従来の API は機械間連携の正本契約として残す
仮説:REST API と OpenAPI 仕様は廃止されず、エージェントはその API をツールとして呼び出す。エージェント向けの契約情報も API の上に乗せることができる。
ソースコードと観察記録を見る →Smart Endpoints and Dumb Pipes
原則:金額計算・課金・認可は決定論的コードで処理する
仮説:payment-service はエージェントを持たず、支払い確定を決定論的コードで実行できる。エージェントを除くことでサービスの安定性が向上する。
ソースコードと観察記録を見る →Products not Projects
原則:system prompt はエンジニアが管理するシステム制約として書く
仮説:system prompt はソースコードとして管理され、変更はレビューとバージョン管理の対象になる。デプロイ環境によって動的に変わる部分もコードで制御できる。
ソースコードと観察記録を見る →Products not Projects / Decentralized Governance
原則:skill は業務知識の公開面として分離する
仮説:業務知識と発動条件を SKILL.md に分離することで、コード変更なしに内容と発動条件を更新できる。
ソースコードと観察記録を見る →Decentralized Governance
原則:サービス間の collaborator 解決は capability ベースで動的に行う
仮説:呼び出し先を能力の記述で解決することで、サービスが互いを直接知らなくても協調できる。アダプターの可用性が変わっても呼び出し元のコードは変わらない。
ソースコードと観察記録を見る →Smart Endpoints and Dumb Pipes / Decentralized Governance
原則:複数サービスで同一モデル設定を共有しても LLM はパイプにならない
仮説:order-service と menu-service が同じ LLM バックエンド設定を共有していても、サービス間の境界は REST 契約で維持され、LLM 呼び出しは各サービス内部の endpoint 処理として独立して実行される。
ソースコードと観察記録を見る →Products not Projects / Smart Endpoints and Dumb Pipes
原則:設計境界は実装時だけでなく運用時にも観測可能であるべき
仮説:エージェント導入後も、workflow・agent・downstream の挙動が execution-history と Micrometer で追跡できれば、サービス境界の責務分担を運用中に再検証できる。
ソースコードと観察記録を見る →各観察が仮説をどう裏づけるかは Conclusions で説明しています。