agent-signal

Agent Signal

このスキルを使用して、フォアグラウンドのチャットリクエストに処理を結び付けずに、エージェント向けのイベント駆動型バックグラウンド処理を実装します。

Agent Signal のランタイム構成は一貫しています。

ソースイベント -> シグナルの解釈 -> アクションの実行 -> 組み込みの結果シグナル

永続的な自己反復処理には、完了時の分岐がもう 1 つあります。

メモリ／スキルのアクション -> execAgent のキューへの登録 -> agent.execution.completed -> selfIteration のレシート投影

ここから始める

1. references/architecture.md を読み、パッケージ境界、ランタイムキュー、スコープモデル、非同期ワークフローへの引き継ぎを把握します。
2. 新しいポリシー、ソースハンドラー、シグナルハンドラー、アクションハンドラーを作成する前に、references/handlers.md を読みます。
3. トレース、メトリクス、デバッグ、ワークフロースナップショットの確認が必要な場合は、references/observability.md を読みます。

適切なエントリーポイントを使う

• サーバーが管理するプロデューサーからパイプラインを即時実行する場合は、emitAgentSignalSourceEvent(...) を使います。
• ワーカーまたは制御されたバックエンドの処理経路がすでに実行タイミングを管理しており、ランタイムガードのバックエンドを注入できる場合は、executeAgentSignalSourceEvent(...) を使います。
• 呼び出し元がすぐに応答し、Upstash Workflow にイベントを帯域外で処理させる場合は、enqueueAgentSignalSourceEvent(...) を使います。
• 周囲の Redis 状態の影響を避けたい分離テストや評価には、emitAgentSignalSourceEventWithStore(...) を使います。

確認するファイル：

• apps/server/src/services/agentSignal/index.ts
• apps/server/src/workflows/agentSignal/index.ts
• apps/server/src/workflows/agentSignal/run.ts

コアモデル

• source：発生した事実を正規化したものです。ソースは、ランタイムのライフサイクルイベント、ユーザーメッセージ、ボットの受信処理などのプロデューサーから発生します。
• signal：1 つのソース、または別のシグナルから導出された意味的な解釈です。シグナルは意味、ルーティング、ポリシーの状態を表します。
• action：1 つのシグナルをもとに計画される、具体的な副作用です。アクションが処理を実行します。
• policy：ソース、シグナル、アクションのハンドラーを登録する、インストール可能なミドルウェアバンドルです。
• procedure：独立したランタイムノードではありません。「procedure」は、あるユースケースのエンドツーエンドのフローを指すものとして扱います。つまり、受信ソース、一致するハンドラー、計画されたアクション、実行結果、可観測性までを含みます。

境界を厳密に保ちます。

• 外部で新しいイベントが発生した場合は、新しい source を追加します。
• システムで再利用可能な意味的解釈が必要な場合は、新しい signal を追加します。
• ランタイムで具体的な副作用が必要な場合は、新しい action を追加します。
• これらの要素を連携させる場合は、policy を追加または更新します。

実装ワークフロー

1. ユースケースが同期処理か、静かなバックグラウンド処理かを判断します。
2. packages/agent-signal/src/source/sourceTypes.ts でソースタイプを定義するか、既存のものを再利用します。
3. apps/server/src/services/agentSignal/policies/types.ts でシグナルタイプとアクションタイプを定義するか、既存のものを再利用します。
4. defineSourceHandler、defineSignalHandler、または defineActionHandler を使ってハンドラーを実装します。
5. プロデューサーのペイロードを整形する必要がある場合は、apps/server/src/services/agentSignal/sources/** にソースの正規化またはハイドレーション処理を追加します。
6. defineAgentSignalHandlers(...) を使ってハンドラーをまとめます。
7. apps/server/src/services/agentSignal/policies/index.ts にポリシーを登録し、必要に応じてランタイムファクトリーに渡します。
8. ソースイベントを発行またはキューに登録する受信処理のコードを追加または更新します。
9. 非同期の自己反復書き込みでは、Agent Signal の操作マーカーを付与し、完了処理の経路からユーザーに表示するレシートを投影します。
10. フローの完成とみなす前に、可観測性の対応とテストを追加します。

デフォルトの読み込みセット

• 共有セマンティックコア： packages/agent-signal/src/index.ts packages/agent-signal/src/base/builders.ts packages/agent-signal/src/base/types.ts packages/agent-signal/src/source/sourceTypes.ts packages/agent-signal/src/source/sourceEvent.ts
• サーバーが所有するランタイムとミドルウェア： apps/server/src/services/agentSignal/runtime/AgentSignalRuntime.ts apps/server/src/services/agentSignal/runtime/AgentSignalScheduler.ts apps/server/src/services/agentSignal/runtime/middleware.ts apps/server/src/services/agentSignal/runtime/context.ts
• 既存のポリシー例： apps/server/src/services/agentSignal/policies/analyzeIntent/index.ts apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackSatisfaction.ts apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackDomain.ts apps/server/src/services/agentSignal/policies/analyzeIntent/feedbackAction.ts apps/server/src/services/agentSignal/policies/analyzeIntent/actions/userMemory.ts apps/server/src/services/agentSignal/policies/analyzeIntent/actions/skillManagement.ts apps/server/src/services/agentSignal/policies/analyzeIntent/completionSkillSynthesis.ts apps/server/src/services/agentSignal/policies/completionPolicy.ts apps/server/src/services/agentSignal/services/selfIteration/completion/buildSelfIterationReceipts.ts apps/server/src/services/agentSignal/services/selfIteration/completion/selfIterationCompletionHandler.ts
• 可観測性： apps/server/src/services/agentSignal/observability/projector.ts apps/server/src/services/agentSignal/observability/traceEvents.ts packages/observability-otel/src/modules/agent-signal/index.ts

実装ルール

• 新しい型を追加する前に、既存のソース、シグナル、アクションの型を再利用してください。
• ソースハンドラーは、重い副作用ではなく、解釈と振り分けに専念させてください。
• アクションハンドラーは、副作用、冪等性、エグゼキューター形式の結果報告を担うようにしてください。メモリ／スキルの自己反復アクションでは、副作用は execAgent のキューへの登録です。永続的な書き込みとレシートの投影は完了後に行われます。
• 同じソースが複数回届く可能性がある場合は、安定した ID と冪等性キーを使用してください。
• スコープの規律を守ってください。ランタイムは scopeKey を使用して、関連するバックグラウンド処理を直列化します。
• 正規化されたノードと結果コントラクトには、@lobechat/agent-signal の専用共有パッケージの型とビルダーを優先して使用してください。
• キューへの登録アクションからメモリまたはスキルのレシートを投影しないでください。createSelfIterationCompletionHandler(...) を介して、agent.execution.completed と selfIteration の finalState を使用してください。
• 変更したランタイム、ポリシー、またはストアモジュールの近くに、対象を絞ったテストを追加してください。apps/server/src/services/agentSignal/**/__test__ および **/__tests__ にある既存のテストが参考パターンです。

参考資料

• アーキテクチャと境界：references/architecture.md
• ハンドラーとポリシーの作成：references/handlers.md
• 可観測性、メトリクス、デバッグ：references/observability.md