エージェントランタイム

アーキテクチャとコード

エージェントランタイム

オーケストレーションとエージェントエンジンの間に位置するハーネス — ランタイムインターフェース、インボーカ、アダプタ対ランタイム設定、環境レイヤー、実行スコープ認証。

Claude CodePi Agent$RUN_TOKEN

ランタイムインターフェース、インボーカ、環境レイヤー、実行スコープ認証。上部の全画面ボタンをご利用いただくか、エージェントランタイム図を新しいタブで開く ↗。

オーケストレーションと実際のエージェントエンジンの間に位置するハーネスです。

ハーネスとエージェントランタイム

ハーネスは、LifeOSAIオーケストレーションと実際のエージェントエンジンの間のランタイム境界です。

ランタイムインターフェース

packages/agent/src/runtimes/types.ts がランタイム契約を定義します。

AgentRuntime
  sessionId
  stream(prompt)
  sendMessage(content)
  interrupt()
  respondToPermission(toolUseId, response)
  close()

ランタイムオプションには以下が含まれます。

• cwd
• systemPrompt
• model
• sessionId
• permissionMode
• allowedTools
• env
• mcpServers
• userManagementUrl
• projectPath
• channelsMessageHandler
• additionalSkillPaths

アプリケーションの他の部分は、内部のランタイムがClaude CodeかPi Agentかを知る必要はありません。正規化されたストリームイベントを消費するだけで十分です。

サポートされるランタイム

ランタイム	配置場所	責務
Claude Code	packages/agent/src/runtimes/claude-code-runtime.ts	Claude Code SDKセッションをラップし、SDKメッセージをストリーム
Pi Agent	packages/agent/src/runtimes/pi-agent-runtime.ts	Piコーディングエージェントセッションを実行し、イベントを正規化
ランタイムファクトリ	packages/agent/src/runtimes/factory.ts	設定されたアダプタ/ランタイムキーに基づきランタイムを選択
イベントノーマライザ	packages/agent/src/runtimes/event-normalizer.ts	フロントエンドとオーケストレーション利用者向けにイベントを正規化

エージェントインボーカ

apps/api/src/orchestration/engine/agent-invoker.ts は、ハートビート実行からランタイムプロセスへの橋渡しを担います。

その責務は以下の通りです。

• アダプタ種別とモデルの解決
• インストラクションファイルとスキルパスの解決
• 企業、エージェント、プロジェクトのcwdの解決
• エージェント環境とプロジェクト環境の読み込み
• 企業シークレット参照の解決
• ランタイム環境のマージ
• 実行スコープのベアラートークンの発行
• LIFEOSAI_* ウェイクコンテキストの注入
• channels MCPサーバーのアタッチ
• Claude CodeまたはPi Agentの起動
• ログからのシークレットの秘匿化
• 実行ログイベントの発行
• セッションID、使用量、結果、エラー状態の返却

アダプタ設定とランタイム設定

これら2つを一つのBlobにまとめてはいけません。読み手と検証パスが異なります。

フィールド種別	格納先	理由
env, cwd, command, args, model	adapter_config	プロセス起動およびアダプタ入力
instructionsBundleMode, instructionsRootPath, instructionsEntryFile	adapter_config	アダプタの発見ロジック
アダプタ固有のノブ	adapter_config	アダプタ実行で使用
heartbeat enabled, intervalSec, wakeOnDemand, maxConcurrentRuns	runtime_config	スケジューラポリシー
session compaction policy	runtime_config	セッションローテーションポリシー

デフォルト値はエージェント作成時に適用すべきです。PATCHは呼び出し元が送ったフィールドのみマージすべきで、部分更新が古いデフォルトを復活させないようにします。

ランタイム環境

LifeOSAIは2層の環境変数をサポートします。

1. エージェントスコープ環境変数: エージェントに格納されます。
2. プロジェクトスコープ環境変数: プロジェクトに格納されます。

キーが衝突した場合、プロジェクト環境変数がエージェント環境変数を上書きします。これにより、共通のランタイムキーをエージェントレベルで一度定義し、特定のプロジェクトでのみ上書きできます。

環境変数の値は、packages/shared/src/orchestration/env-config.ts の共有バインディングスキーマを使用します。

KEY=value
KEY={ type: "plain", value: "value" }
KEY={ type: "secret_ref", ref: "company-secret-name" }

検証ルール:

• キーは ^[A-Za-z_][A-Za-z0-9_]*$ にマッチすること
• 機密キーの平文はストリクトモードで拒否される場合がある
• ***REDACTED*** は値として書き戻せない
• シークレット参照は同じ企業に属している必要がある
• シークレットに紐づくキーはログ秘匿化のためマークされる

実行スコープAPI認証

エージェントが公開するAPIは、実行スコープのベアラートークンで保護されます。

Authorization: Bearer $LIFEOSAI_RUN_TOKEN

このトークンはリクエストを以下に紐付けます。

• 企業ID
• エージェントID
• 実行ID

これは X-LIFEOSAI-AGENT-ID のようなユーザー提供ヘッダを信頼するよりも強固です。ヘッダは診断や後方互換性には引き続き有用ですが、セキュリティ境界として用いるべきではありません。

ランタイム環境変数

インボーカは、ウェイクおよび実行コンテキストを環境変数として注入します。一般的な値は以下の通りです。

• LIFEOSAI_API_URL
• LIFEOSAI_RUN_TOKEN
• LIFEOSAI_RUN_ID
• LIFEOSAI_AGENT_ID
• LIFEOSAI_COMPANY_ID
• LIFEOSAI_WAKE_REASON
• LIFEOSAI_WAKE_SOURCE
• LIFEOSAI_TASK_ID または該当する場合は課題ID
• LIFEOSAI_TIMEZONE
• ウェイクソースがチャネルの場合のチャネル固有値

タイマーウェイクには課題IDが含まれないことがあります。その場合、エージェントはハートビートまたはインボックスのインストラクションに従い、利用可能な作業を確認すべきです。

次に読む

エージェントシステム UIの下にある全システムを一つの文書に。

プラットフォーム サービス境界、責務、デプロイ、セキュリティ、コードマップ。

オーケストレーション 企業、エージェント、ウェイクアップ、実行、ライブイベント。

チャネル WhatsAppとTelegramの受信、ディスパッチ、送信ツール。

アーキテクチャ概要 セクションマップと全体システム図に戻る。