eve-agentic-app-design

Eve Horizon でのエージェント型アプリ設計

アプリケーション全体を、エージェントが人間と並んで推論、連携、記憶、コミュニケーションを行う、エージェントが主要な役割を担うアプリに変えます。

使用するタイミング

次のような場合に、このスキルを読み込みます：

• エージェントが人間と並んで（または人間に代わって）主要なユーザーとなるアプリを設計するとき
• 既存の Eve アプリにエージェント機能を追加するとき
• 人間優先とエージェント優先のアーキテクチャを選ぶとき
• エージェントの連携、記憶、コミュニケーションの方法を決めるとき

前提条件：基盤から始める

まず eve-fullstack-app-design を読み込んでください。 エージェント型のレイヤーは、堅牢な PaaS 基盤の上に構築されます。適切に設計されたマニフェスト、サービス構成、データベース、パイプライン、デプロイ戦略がなければ、エージェント機能は混乱に陥ります。

手順：

1. eve-agent-native-design — 原則（同等性、粒度、構成可能性、創発的な機能）
2. eve-fullstack-app-design — PaaS 基盤（マニフェスト、サービス、DB、パイプライン、デプロイ）
3. このスキル — エージェント型のレイヤー（エージェント、チーム、メモリー、イベント、チャット、連携）

各レイヤーは、その前のレイヤーを前提としています。どれも省略しないでください。

エージェントのアーキテクチャ

エージェントの定義

エージェントは agents.yaml で定義します（パスはマニフェストの x-eve.agents.config_path で設定）。各エージェントは、スキル、アクセス範囲、ポリシーを持つペルソナです。

version: 1
agents:
  coder:
    slug: coder
    description: "Implements features and fixes bugs"
    skill: eve-orchestration
    harness_profile: primary-coder
    access:
      envs: [staging]
      services: [api, worker]
    policies:
      permission_policy: auto_edit
      git:
        commit: auto
        push: on_success
    gateway:
      policy: routable

各エージェントで決めること：

決定事項	選択肢	指針
スラッグ	小文字、英数字とハイフン	組織内で一意にします。チャットのルーティングに使用します：@eve coder fix the login bug
スキル	インストール済みの任意のスキル名	エージェントの中核となる能力です。エージェントごとにスキルを1つ設定します。
ハーネスプロファイル	マニフェストで定義されたプロファイル名	エージェントを特定のモデルから切り離します。プロファイルを使用し、ハーネスを直接指定しないでください。
ゲートウェイポリシー	none、discoverable、routable	デフォルトは none にします。routable にするのは、直接チャットを受け取るエージェントに限ります。
権限ポリシー	default、auto_edit、never、yolo	ワーカーエージェントには auto_edit から始めます。人間の承認が必要なエージェントには default を使用します。
Git ポリシー	commit、push	コーディングエージェントには、コミットを auto、プッシュを on_success にします。読み取り専用エージェントには never を設定します。

チームの設計

チームは teams.yaml で定義します。チームでは、ディスパッチ戦略とともにリードの下にエージェントをまとめます。

version: 1
teams:
  review-council:
    lead: mission-control
    members: [code-reviewer, security-auditor]
    dispatch:
      mode: council
      merge_strategy: majority
  deploy-ops:
    lead: ops-lead
    members: [deploy-agent, monitor-agent]
    dispatch:
      mode: relay

適切なディスパッチモードを選ぶ：

モード	使用するタイミング	動作
fanout	独立した並列作業	ルートジョブと、メンバーごとの並列子ジョブを作成します。分割可能なタスクに最適です。
council	集合的な判断	すべてのエージェントが応答し、戦略（多数決、全員一致、リードが決定）に従って結果を統合します。レビューや監査に最適です。
relay	順次の引き継ぎ	リードが最初のメンバーに委任し、出力を次のメンバーに渡します。段階的なワークフローに最適です。

設計原則：作業の大半には fanout を使用します。複数の視点によって結果が実際に向上する場合に限り council を使います。各段階の出力が次の段階の入力となる場合に限り relay を使います。

ハーネスプロファイル

マニフェストで名前付きプロファイルを定義します。エージェントは特定のハーネスではなく、プロファイルを参照します。

x-eve:
  agents:
    profiles:
      primary-coder:
        - harness: claude
          model: opus-4.5
          reasoning_effort: high
        - harness: codex
          model: gpt-5.2-codex
          reasoning_effort: high
      fast-reviewer:
        - harness: mclaude
          model: sonnet-4.5
          reasoning_effort: medium

プロファイルのエントリーはフォールバックチェーンです。最初のハーネスを利用できない場合は、次のハーネスが試されます。プロバイダーへのこだわりではなく、必要な能力に基づいてプロファイルを設計してください。

ジョブごとのハーネスオーバーライド

同じエージェントでリクエストごとに異なる頭脳を使う必要がある場合（ユーザーのプロジェクトごとのモデル選択、BYOK 認証情報、セルフホスト可能なエンドポイントなど）は、リクエストごとに agents.yaml を変更するのではなく、ディスパッチ時にインラインオーバーライドを渡します。

• ジョブ作成：--harness-override-file <path>（JSON {harness, model?, reasoning_effort?, variant?, temperature?}）および --env-override KEY=VALUE（繰り返し指定可能で、${secret.KEY} の補間に対応）
• ワークフローの実行／呼び出し：--env-override KEY=VALUE（繰り返し指定可能）
• API：CreateJobRequest およびチャットのディスパッチで harness_profile_override と env_overrides を指定

オーケストレーターは harness_profile_source（agent_default、string_ref、inline_override、workflow_template）と、監査用の安定したハッシュを記録します。オーバーライドを使うのは呼び出しごとに実際に変化がある場合に限り、それ以外の場合は名前付きプロファイルを優先してください。

モデル選択の指針

タスクの種類	プロファイル戦略
複雑なコーディング、アーキテクチャ	高い推論能力を持つモデル（opus、gpt-5.2-codex）
コードレビュー、ドキュメント作成	中程度の推論能力を持つモデル（sonnet、gemini）
トリアージ、ルーティング、分類	高速なモデル（haiku 相当、低い推論能力）
専門分野	その分野で最も優れた性能を発揮するモデルを選択

メモリ設計

ストレージプリミティブの全カタログについては、eve-agent-memory を読み込んでください。このセクションではアーキテクチャ上の判断に焦点を当てます。

情報の保存先

情報の種類	ストレージプリミティブ	理由
ジョブ実行中の一時メモ	ワークスペースファイル（.eve/）	一時的なもので、ジョブとともに消去されます
親に渡すジョブの出力	ジョブの添付ファイル	ジョブ完了後も保持され、ジョブ ID で参照できます
継続的な会話コンテキスト	スレッド	セッション間の継続性があり、要約できます
厳選された知識	組織ドキュメントストア	バージョン管理され、検索可能で、プロジェクト間で共有されます
ファイルツリーとアセット	組織ファイルシステム（同期）	双方向同期に対応し、ローカルで編集できます
構造化クエリ	マネージドデータベース	SQL、リレーションシップ、RLS に対応します
再利用可能なワークフロー	スキル	長期メモリとして最も忠実度が高い方法です

名前空間の規約

エージェントと目的ごとに組織ドキュメントを整理します。

/agents/{agent-slug}/learnings/      — discoveries and patterns
/agents/{agent-slug}/decisions/      — decision records
/agents/{agent-slug}/runbooks/       — operational procedures
/agents/shared/                      — cross-agent shared knowledge
/projects/{project-slug}/            — project-scoped knowledge

ライフサイクル戦略

有効期限のないメモリはノイズになります。各ストレージの場所について、以下を決めてください。

1. 誰が書き込みますか？ この知識を作成、更新するエージェントを決めます。
2. 誰が読み込みますか？ どのエージェントがいつ（ジョブ開始時か、必要に応じてか）クエリするかを決めます。
3. いつ期限切れになりますか？ 作成日をタグ付けします。定期的なクリーンアップジョブを作成します。
4. どのように最新の状態を保ちますか？ 書き込む前に検索します。新規作成より更新を優先します。

イベント駆動型の連携

イベントスパイン

イベントはエージェント型アプリの神経系です。リアクティブな自動化、つまり他の事象への応答として実行すべき処理に使用します。

トリガーパターン

トリガー	イベント	応答
main にコードがプッシュされた	github.push	CI パイプラインを実行
PR が開かれた	github.pull_request	レビュー評議会を実行
デプロイパイプラインが失敗した	system.pipeline.failed	自己修復ワークフローを実行
ジョブが失敗した	system.job.failed	診断エージェントを実行
ジョブの試行が完了した	system.job.attempt.completed	セッション後の学習ワークフローを実行（user／learnings メモリに書き戻す）
組織ドキュメントが作成された	system.doc.created	購読者に通知し、インデックスを更新
メンテナンスの予定時刻になった	cron.tick	監査、クリーンアップ、レポート作成を実行
カスタムアプリイベント	app.*	アプリケーション固有の自動化

自己修復パターン

システム障害イベントを復旧パイプラインに接続します。

pipelines:
  self-heal:
    trigger:
      system:
        event: job.failed
        pipeline: deploy
    steps:
      - name: diagnose
        agent:
          prompt: "Diagnose the failed deploy and suggest a fix"

エージェントの学習ループ

セッション中の試行を通じて学習するエージェントを構築するには、成功時、失敗時、オーケストレーターのエラー時に発行される system.job.attempt.completed を、引き継ぎコンテキストを要約してエージェントのメモリに保存するレビューのワークフローに接続します。プラットフォームは .eve/context/ の引き継ぎ情報を次の試行のワークスペースに書き込みます。また、AgentContextMemorySchema は learnings、decisions、runbooks、context、conventions に加えて user カテゴリーも受け付けます。ユーザーごとの好みややり取りの履歴には user を使用してください。

カスタムアプリイベント

サービスからアプリケーション固有のイベントを発行します。

eve event emit --type app.invoice.created --source app --payload '{"invoice_id":"inv_123"}'

これらをマニフェスト内のワークフローまたはパイプラインに接続します。アプリのイベント語彙は意図的に設計してください。イベントは、アプリのロジックとエージェントの自動化をつなぐ API です。

チャットと人間とエージェントのインターフェース

ゲートウェイアーキテクチャ

Eve は、統合ゲートウェイを通じて複数のチャットプロバイダーをサポートします。

プロバイダー	トランスポート	最適な用途
Slack	Webhook	チームでのコラボレーション、既存の Slack ワークスペース
Nostr	Subscription	分散型、プライバシー重視、検閲耐性
WebChat	WebSocket	ブラウザーにネイティブ、アプリへの埋め込み

ルーティング設計

chat.yaml でルートを定義し、受信メッセージをエージェントまたはチームに割り当てます。

version: 1
default_route: route_default
routes:
  - id: deploy-route
    match: "deploy|release|ship"
    target: agent:deploy-agent
  - id: review-route
    match: "review|PR|pull request"
    target: team:review-council
  - id: route_default
    match: ".*"
    target: agent:mission-control

ルートのターゲットには、agent:<key>、team:<key>、workflow:<name>、pipeline:<name> を指定できます。

ゲートウェイ、バックエンドプロキシ経由のチャット、埋め込み型会話の比較

方法	使用する場面
埋め込み型会話 API（@eve-horizon/chat / @eve-horizon/chat-react）	プロダクトオブジェクト（プロジェクト、ドキュメント、チケット）に関連付けた、アプリネイティブのチャットペイン。アプリ内チャットの標準的な選択肢です。
ゲートウェイプロバイダー（Eve への WebSocket 接続）	シンプルなチャットウィジェット、管理コンソール、プロダクトオブジェクトへの関連付けが不要な場合
バックエンドプロキシ経由（POST /internal/orgs/:id/chat/route）	本番環境の SaaS、会話の傍受、拡充、保存が必要な場合

埋め込み型アプリ会話

アプリ内のチャット画面には、chat/route を直接使用して構築するのではなく、conversations ファサードを使用してください。SDK がスレッドのマッピング、認証、ディスパッチ、再開可能な SSE、楽観的送信、再接続を処理します。

const conversation = createConversationClient({
  baseUrl: '/api/eve',
  projectId: 'proj_xxx',
  appKey: `open-design:${projectId}:${conversationId}`,
  getToken: async () => session.token,
});

await conversation.ensure({ metadata: { product_route: '/projects/x' } });
await conversation.send({ text: '...', target: { kind: 'agent', agent_slug: 'designer' } });
for await (const event of conversation.stream({ resumeFrom: lastEventId })) { /* ... */ }

サーバーエンドポイント：POST /projects/{id}/conversations、POST .../conversations/{app_key}/turns、GET .../conversations/{app_key}/stream（SSE）、GET .../conversations/{app_key}/messages。イベントは構造化された cevt_* レコード（メッセージ、進捗状況、ステータス）としてストリーム配信され、バックフィルに対応し、Last-Event-ID を使用して再開できます。ストリーミング接続を維持できない場合は、provider: "api" クライアント（ポーリング）を使用してください。プラットフォームは no-op 配信プロバイダーを登録するため、永続化は引き続き機能します。

スレッドの継続性

チャットスレッドはメッセージ間でコンテキストを維持します。スレッドキーは連携アカウントにスコープされます。アプリがプロダクトオブジェクトとともに Eve のスレッド ID を保存している場合は、thr_* ID を指定してルーティング済みのスレッドを直接続けられます（ルートは一度だけ解決され、以降のやり取りでは再ルーティングされません）。会話のコンテキストが保たれるようにチャット UX を設計してください。エージェントは会話履歴を参照できると、はるかに高い効果を発揮します。

ジョブを調整の基本単位として使う

親子オーケストレーション

ジョブはエージェントの作業の基本単位です。複雑なワークフローはジョブツリーとして設計します。

Parent (orchestrator)
├── Child A (research)
├── Child B (implementation)
└── Child C (testing)

親はディスパッチし、待機し、再開し、統合します。子は独立して実行されます。依存関係を表すには waits_for 関係を使用します。パターンの全容については eve-orchestration を参照してください。

添付ファイルによる構造化コンテキスト

エージェント間で構造化データを渡すには、長大な説明文ではなく、ジョブの添付ファイルを使用します。

# Child stores findings
eve job attach $EVE_JOB_ID --name findings.json --content '{"patterns": [...]}'

# Parent reads on resume
eve job attachment $CHILD_JOB_ID findings.json --out ./child-findings.json

ドキュメントのマウントに使うリソース参照

ジョブの入力として、組織ドキュメントの特定のバージョンを指定します。

eve job create \
  --description "Review the approved plan" \
  --resource-refs='[{"uri":"org_docs:/pm/features/FEAT-123.md@v3","label":"Plan","mount_path":"pm/plan.md"}]'

ドキュメントはマウントパスにワークスペースへ展開されます。イベントで展開の成功または失敗を追跡します。

調整スレッド

チームで作業を割り当てる際、調整スレッド（coord:job:{parent_job_id}）が親と子を結び付けます。子エージェントは、兄弟エージェントに関するコンテキストを .eve/coordination-inbox.md から読み取ります。eve thread post で更新を投稿します。リードエージェントは eve supervise でジョブツリーを監視できます。

アクセスとセキュリティ

サービスアカウント

バックエンドサービスが API を呼び出すには、ユーザーに紐付かないトークンが必要です。eve auth mint を使って、スコープを指定したトークンを作成します。

eve auth mint --email [email protected] --project proj_xxx --role admin

各サービスアカウントは、必要最小限のスコープで設計してください。

アクセスグループ

グループを使って、データプレーンへのアクセスを分割します。グループは、組織のドキュメント、組織のファイルシステムパス、データベーススキーマの読み書きができるユーザーを制御します。

# .eve/access.yaml
version: 2
access:
  groups:
    eng-team:
      name: Engineering
      members:
        - type: user
          id: user_abc
  bindings:
    - subject: { type: group, id: eng-team }
      roles: [data-reader]
      scope:
        orgdocs: { allow_prefixes: ["/agents/shared/"] }
        envdb: { schemas: ["public"] }

eve access sync --file .eve/access.yaml --org org_xxx で同期します。

エージェント権限ポリシー

ポリシー	用途
default	リスクの高い操作に人間の承認を必要とする対話型エージェント
auto_edit	コードやファイルを自律的に編集するワーカーエージェント
never	読み取り専用エージェント（監査担当、レビュー担当）
yolo	管理された環境で動作する完全自律型エージェント（慎重に使用してください）

ポリシー・アズ・コード

すべてのアクセス権を .eve/access.yaml で宣言し、宣言的に同期します。これにより、アクセス権をバージョン管理でき、レビュー可能かつ再現可能になります。v2 ポリシースキーマの詳細については、eve-auth-and-secrets を参照してください。

エージェント構築チェックリスト

エージェントアーキテクチャ：

• エージェントが agents.yaml で明確なスラッグ、スキル、プロファイルとともに定義されている
• チームが適切なディスパッチモードとともに teams.yaml で定義されている
• ゲートウェイポリシーが意図的に設定されている（すべてをルーティング可能にしない）
• 受信メッセージ処理用のチャットルートが定義されている

ハーネスプロファイル：

• ハーネスプロファイルがマニフェストで定義されている（エージェントはハーネスではなくプロファイルを参照する）
• 耐障害性を高めるため、プロファイルにフォールバックチェーンが設定されている
• モデルの選択がタスクの複雑さに合っている

メモリ：

• 各情報タイプに適したストレージプリミティブが選択されている（上の表を参照）
• 組織のドキュメントに名前空間の規則が定められている
• ライフサイクルと有効期限の方針が定義されている
• エージェントは書き込む前に検索する（新規作成より更新を優先）

イベント：

• 重要なイベント（プッシュ、PR、失敗）に対するトリガーパターンが設定されている
• デプロイやジョブの失敗に対応する自己修復パイプラインがある
• ドメイン固有の自動化に使うカスタムアプリイベントが定義されている

チャット：

• ゲートウェイプロバイダー（Slack、Nostr、WebChat、または複数）が選択されている
• チャットのルーティングが設定されている（chat.yaml）
• ゲートウェイ経由かバックエンドプロキシ経由かが決定されている
• UX でスレッドの継続性が保たれている

調整：

• 複雑な作業がジョブツリー（親子）として分解されている
• 構造化されたコンテキストの受け渡しに添付ファイルが使われている
• チーム間のコミュニケーションに調整スレッドが使われている
• ドキュメントのマウントにリソース参照が使われている

セキュリティ：

• バックエンドサービス用のサービスアカウントが作成されている
• データプレーンを分割するアクセスグループが定義されている
• 各エージェントの役割に適したエージェント権限ポリシーが設定されている
• アクセスポリシーがコード（.eve/access.yaml）として宣言されている

本当のテスト — このアプリは本当にエージェントネイティブか？

• エージェントがユーザーにできることをすべて実行できる（同等性）
• 機能の追加がコードではなくプロンプトの作成で実現できる（コンポーザビリティ）
• エージェントが独自のつなぎ込みではなくプラットフォームのプリミティブを通じて連携する（粒度）
• エージェントが予想外の解決策であなたを驚かせたことがある（創発的な能力）

相互参照

• 原則：eve-agent-native-design — 同等性、粒度、合成可能性、創発的な能力
• PaaS の基盤：eve-fullstack-app-design — マニフェスト、サービス、DB、パイプライン、デプロイ
• ストレージのプリミティブ：eve-agent-memory — 各メモリプリミティブに関する詳細なガイダンス
• ジョブのオーケストレーション：eve-orchestration — 深度の伝播、並列分解、制御シグナル
• エージェントとチームのリファレンス：eve-read-eve-docs → references/agents-teams.md
• ハーネスの実行：eve-read-eve-docs → references/harnesses.md
• チャットゲートウェイ：eve-read-eve-docs → references/gateways.md
• 組み込み型会話 SDK：eve-read-eve-docs → references/eve-sdk.md（組み込み型会話ペイン）
• イベントとトリガー：eve-read-eve-docs → references/events.md