メインコンテンツまでスキップ

アシスタントで設計する

仕様モードは API を設計する場所です。AI チャットをライブの文書とプレビューと組み合わせ、自然言語で意図を説明しながら、実際に起きる変更を完全にコントロールできます。

承認ループ​

モデルは文書を直接編集しません。このループは意図的に明示的に作られています。

you describe an intent
        |
the model reads current state and proposes operations
        |
the host validates the proposal
        |
you review a patch card and Apply or Reject
        |
the change is merged into the document

この分離は重要な設計判断です。モデルは意図を理解し構造を提案するのが得意で、ホストは確定的で各操作を検証し、あなたがすべての変更を承認します。あなたが確認するまで、提案が適用されたとみなされることはありません。

パッチカード​

パッチカードは変更を要約し、パスを追加する場合のように正確な操作を列挙します。

{
  "type": "patch",
  "summary": "Add GET /products endpoint",
  "ops": [
    { "op": "add", "path": ["paths", "/products"], "value": { "get": {} } }
  ],
  "affects": { "paths": ["/paths/~1products"], "resources": ["Product"] }
}

パスセグメントは JSON Pointer 文字列ではなく配列要素です。全新のパスを追加するときのターゲットは ["paths", "/products"] で、親コンテナは自動的に作られます。

既存操作へのきめ細かい編集​

既存の操作を編集するとき、アシスタントは操作全体を再送しません。それでは再表示しなかったすべてのフィールドが消えてしまいます。代わりに、変更した部分だけに触れる小さな操作を生成し、操作の内部に入ります。

  • クエリパラメータを追加する:
{ "op": "add", "path": ["paths", "/products", "get", "parameters", "-"], "value": {} }
  • レスポンススキーマを拡張する:
{ "op": "replace", "path": ["paths", "/products", "get", "responses", "200", "content", "application/json", "schema", "properties", "total"], "value": { "type": "integer" } }
  • 単一フィールドを変更する:
{ "op": "replace", "path": ["paths", "/products", "get", "summary"], "value": "..." }

配列は全体を再送するのではなく "-" で追記します。パラメータは (in, name) をキーとするため、既存パラメータが重複することはありません。ホストは提案値を現在の操作にマージし、省略したすべてを保持します。

これこそ、反復的な refine を信頼できるものにする理由です。「ここに limit パラメータを足して」「name を必須にして」と言うと、そのフィールドだけが変わり、操作の残りは不変です。

読み取りツールが各提案に根拠を与える​

回答前に、モデルは推測ではなく正確な現在状態を得るため、読み取り専用ツールを呼べます。

  • spec.overview——タイトル、バージョン、プロトコル、数、タグ、servers、セキュリティ。
  • spec.listOperations——各操作を METHOD /path で、要約とタグ付きで。
  • spec.presentOperations——全操作の読み取り専用リストカードを描画。
  • spec.getOperation——単一操作の完全な定義と参照するスキーマ。
  • spec.getSchema——単一コンポーネントスキーマ。必須フィールドと説明を含む。

操作の完全な形が見えないときはいつでも、モデルは編集前にその操作を読むべきです。

広い要求は段階的に進む​

「e コマース API を構築して」のような大きな要求では、アシスタントは一度にすべてを投げ出しません。

  1. まず主要な判断について明確化の質問を出す。
  2. 回答後、一度に 1 つのフォーカスされたパッチを提案する。各カードは 2〜5 操作。
  3. 直近の要求がまだその目標の範囲内にある間だけ継続する。

範囲が明確になると、アシスタントは構築予定の操作の plan も生成するため、パッチが届く前に作業の形を確認できます。

ブレを避ける​

ホストは作業の整合を保つため、いくつかのルールを強制します。

  • 現在の文書が権威状態。文書がそうでないと示すなら、モデルはより早いパッチが存在すると仮定しない。
  • フォーカスモードでは、アクティブな目標（と明示的に参照されるコンポーネントスキーマ）だけを変更する。兄弟操作への場当たり的な変更はしない。
  • 別の METHOD /path を明示すると、意図的なタスク切り替えとして扱われる。
  • 適用済み・拒否済みの提案は履歴から追跡され、既存パッチを繰り返さない。

必要な詳細が見えない場合、アシスタントは捏造するのではなく、フォーカスされた質問を出します。

その他のカード​

すべての応答がパッチではありません。

  • 質問カードは選択肢から選ぶよう求める。
  • 検証カードは品質チェックを報告。通過、警告、エラー状態を含む。
  • アクションカードは、シナリオの実行やワークスペースを開くなどの具体的な次のステップを提供する。
  • データテーブルカードは、操作やスキーマの具体的なサンプルやテストデータを提示する。

関連: リクエストワークスペース、シナリオテスト、AI とモデル。

A2A​

x-protocol: a2a と x-a2a でエージェントのメッセージとタスクを設計、デバッグ、文書化できます。1.0 は JSON-RPC、REST、デスクトップ gRPC、0.3 は JSON-RPC に対応します。A2A エージェントで拡張フィールド、署名検証、サーバー生成、実行可能なデモを確認してください。