eve-agent-native-design

Eve Horizon 向けのエージェントネイティブ設計

エージェントを後付けではなく、第一級の存在として扱うアプリケーションを構築しましょう。

使用する場面

次のような場合に、このスキルを読み込んでください。

• Eve 上で新しいアプリケーションや API を設計するとき
• 既存のアプリがエージェントにとって使いやすいか評価するとき
• エージェントが利用できる機能を追加するとき
• ロジックをコードとプロンプトのどちらに配置するか決めるとき
• エージェント間通信の扱い方を選ぶとき

4 つの原則

1. 同等性 — エージェントはユーザーができることをすべて実行できます

すべてのユーザー操作に、エージェントが実行できる同等の方法が必要です。

Eve では：CLI が同等性を実現します。ユーザーが eve ... を通じて実行できることは、エージェントも実行できます。アプリを構築するときも、同じ原則を適用してください。

確認項目	方法
エージェントはすべてのエンティティを作成／読み取り／更新／削除できますか？	UI 操作を CLI／API の同等機能に対応付けます
UI でしか実行できないワークフローはありますか？	API エンドポイントまたは CLI コマンドとして公開します
エージェントは利用可能な機能を見つけられますか？	すべてのエンティティタイプに list 操作を用意します

CRUD の完全性：アプリ内のすべてのエンティティについて、エージェントが作成、読み取り、更新、削除を実行できることを確認してください。どれか 1 つでも欠けると、同等性が損なわれます。

2. 粒度 — まとめられたロジックではなく、アトミックなプリミティブ

機能は、巨大なツールではなくエージェントのループから生まれます。

誤り：deploy_and_monitor(app) — 判断をコードにまとめています
誤り：classify_and_organize_files(files) — 分類はエージェントが決めるべきです
正解：eve build create、eve build run、eve env deploy、eve job follow — エージェントが実行順序を決めます

Eve では：マニフェストが WHAT（サービス、パイプライン）を定義し、エージェントがそれらを HOW と WHEN で構成するかを決めます。

設計テスト：動作を変更するには、文章（プロンプト／スキル）を編集しますか、それともコードをリファクタリングしますか？コードを変更する必要があるなら、ツールの粒度が十分ではありません。

3. 合成可能性 — 新機能は新しいプロンプトで実現

ツールがアトミックで同等性が確保されていれば、コードではなくプロンプトを書くことで機能を追加できます。

Eve の例：eve-pipelines-workflows スキルは、パイプラインを構成する機能を追加します。新しい CLI コマンドは必要ありません。このスキルは、既存の eve pipeline コマンドと eve workflow コマンドを組み合わせる方法をエージェントに教えます。

アプリの場合：機能の追加に新しい API エンドポイントが必要なら、ロジックをまとめすぎている可能性があります。既存のプリミティブを別の方法で組み合わせられないか検討してください。

4. 創発的な能力 — エージェントは予想外の結果をもたらします

アトミックなツールを構築します。エージェントは予想外の解決策を組み合わせます。そのパターンを観察します。よく使われるパターンを最適化します。これを繰り返します。

Eve の例：エージェントは eve job create --parent と eve job dep add、深さの伝播を組み合わせて、任意の作業階層を構築します。プラットフォームがこの方法を指定したのではありません。エージェントがアトミックなプリミティブから発見しました。

エージェント型アプリ向けのプラットフォーム機能

4 つの原則に加えて、Eve はエージェント型アプリを大幅にシンプルにする具体的なプリミティブを提供している（または開発しています）。

ジョブの添付ファイル — 構造化されたコンテキストの受け渡し

ファイル操作をあれこれ行わずに、計画、レポート、洞察をエージェント間で受け渡せます。テキストドキュメント（Markdown、JSON、YAML）をジョブに添付できます。後続のエージェントは、親ジョブの添付ファイルを読み取ります。これにより、「エージェント間で構造化されたコンテキストを受け渡す」問題の 80％を解決できます。

サービスアカウント認証 — バックエンドから API への通信

アプリのバックエンドを認証するには、eve auth mint（現在）またはサービスアカウント（開発中）を使用します。バックエンドを持つすべてのアプリには、API 呼び出し用の非ユーザートークンが必要です。スコープ付き権限により、最小権限を徹底できます。

組織ドキュメントストア — 永続的なエージェントの知識

アーキテクチャレポート、リスク評価、規約など、個々のジョブを超えて存続する知識をエージェントが蓄積できます。全文検索に対応した DB ベースのストアで、PATCH 操作を使用したエージェントネイティブな検索／置換編集が可能です。

Web Chat — 2 つの方式

ニーズに応じて選択してください：

• ゲートウェイプロバイダー（方式 A）：Eve ゲートウェイへの WebSocket 接続です。バックエンドは不要です。シンプルなチャットウィジェットや管理コンソールに最適です。
• バックエンドプロキシ方式（方式 B）：アプリのバックエンドから POST /internal/orgs/:id/chat/route を呼び出します。エンリッチメント、ストレージ、ルーティングを完全に制御できます。本番環境の SaaS に最適です。

判断基準：アプリで会話をインターセプト、エンリッチ、または保存する場合は B を使用してください。それ以外の場合は A を使用してください。

プロジェクト横断クエリ — 組織レベルのインテリジェンス

ポートフォリオビュー、ダッシュボード、および複数のプロジェクトにまたがるあらゆるツールが対象です。組織レベルのエンドポイントにより、N+1 API 呼び出しを回避できます。

API スキーマと優先度のランキングを含む全カタログについては、references/eve-horizon-primitives.md を参照してください。

Eve 固有の設計パターン

汎用インターフェースとしてのファイル

• エージェントは cat、grep、mv、mkdir を把握しています
• .eve/manifest.yaml を信頼できる唯一の情報源として使用します。エージェントが読み取り、編集します
• エージェント設定はリポジトリ内のファイル（agents.yaml、teams.yaml）に保存し、データベースには隠しません
• ディレクトリ構造 ＝ 情報アーキテクチャ：{entity_type}/{entity_id}/content
• ファイル名には用途を指定します：{entity}.json、{type}.md、agent_log.md

コンテキストの注入（3 つのレイヤー）

システムプロンプトには以下を含めてください：

1. 利用可能なリソース — 存在するものとその件数：「/notes に 12 件のメモ、3 件のプロジェクト」
2. 機能 — エージェントにできること：「メモの作成、編集、タグ付け、削除」
3. 最近のアクティビティ — 発生したこと：「ユーザーが 2 時間前に『Project kickoff』を作成」

Eve は、すべての環境に EVE_API_URL、EVE_PROJECT_ID、EVE_ORG_ID、EVE_ENV_NAME を注入します。スキルはドメイン用語を提供します。

明示的な完了シグナル

• ジョブは eve.status（"success"、"failed"、"waiting"）を含む json-result を返します
• ヒューリスティックによる完了検出は行いません。常に明示的なシグナルを使用します
• フェーズ遷移を伴うタスクレベルで進捗を追跡します
• 複数ステップの操作では shouldContinue をサポートします
• 中断時に再開できるよう、状態をチェックポイントに保存します

動的な機能の検出

• eve job list で利用可能な作業を検出します
• eve agents list で利用可能なエージェントを検出します
• スキルシステムはインストール時に機能を自動検出します
• ゲートウェイはスラッグでエージェントにメッセージをルーティングします。新しいエージェントは即座に呼び出し可能になります
• エンドポイントごとの静的なツールマッピングより、実行時の検出（list_available_types()）を優先します

エージェントと UI の通信

• イベントタイプ：thinking、toolCall、toolResult、textResponse、statusChange
• サイレントな操作は行いません。変更はすぐに表示されます
• 結果だけでなく、実行中の進捗も表示します
• 内部のノイズの多い操作には ephemeralToolCalls の使用を検討してください

成功のチェックリスト

アーキテクチャ：

• すべての UI 操作に同等の CLI/API がある（同等性）
• すべてのエンティティで完全な CRUD が可能である（完全性）
• ツールは 1 つの処理に専念し、エージェントが組み合わせを判断する（粒度）
• 機能の追加はコードではなく、スキル／プロンプトの追加で行う（合成可能性）
• 明示的に設計していないリクエストにもエージェントが対応できる（創発性）

実装：

• マニフェストと設定ファイルが信頼できる唯一の情報源である（インターフェースとしてのファイル）
• システムプロンプトにリソース、機能、最近のアクティビティが含まれている（コンテキストの注入）
• 完了はヒューリスティックではなく明示的である（eve.status を含む json-result）
• エージェントの操作が UI に即座に反映される（可視性）
• 新しい機能について動的な検出が機能する（拡張性）

バックエンドを備えたアプリを構築する場合：

• API アクセス用のサービスアカウント認証が設定されている
• Web チャットの方式（ゲートウェイまたはプロキシ）を選択している
• 構造化されたエージェント間コンテキストにジョブの添付ファイルを使用している
• 永続的なナレッジ用に組織ドキュメントストアを使用している（利用可能な場合）

アンチパターン

アンチパターン	修正方法
ルーターとしてしか機能しないエージェント	エージェントにルーティングだけでなく、実際に動作させます
ワークフロー型のツール（analyze_and_deploy）	原子的なプリミティブに分割します
UI 専用の操作	同等性を保ち、CLI／API の経路を追加します
コンテキスト不足	スキルと環境変数を介してリソースを注入します
理由のないゲート	既定では開放し、プリミティブを利用可能な状態に保ちます
ヒューリスティックな完了判定	明示的な完了シグナルを使用します
静的な API マッピング	動的な機能検出を使用します
ジョブの説明にコンテキストを詰め込む	構造化ドキュメントにはジョブの添付ファイルを使用します
バックエンドごとのユーザートークン	サービスアカウント／eve auth mint を使用します
イベントのポーリング	利用可能な場合は Webhook を使用します（普及が進んでいます）

参考資料

API スキーマ、DB 設計、実装優先度のランキングを含む、プラットフォームプリミティブの全カタログについては、references/eve-horizon-primitives.md を参照してください。

ソースとなる設計思想については、../eve-horizon/docs/ideas/agent-native-design.md を参照してください。 プラットフォームプリミティブの分析については、../eve-horizon/docs/ideas/platform-primitives-for-agentic-apps.md を参照してください。