Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

リクエストのライフサイクル

「ユーザーがメッセージを送信する」から「エージェントが応答する」までの間に起こること: ストリーミング、ツール呼び出し、セキュリティゲートを注釈付きで示した全経路。

インバウンド

flowchart LR
    A[External event] -->|webhook / push / poll / WS| B[Channel adapter]
    B -->|decode, dedup, pair-check| C[Inbound envelope]
    C -->|workspace binding| D[Runtime: process_message]

チャネルアダプター（例：discord.rs、telegram.rs、email_channel.rs）はプラットフォーム固有のイベントを受信し、それらを統一されたインバウンドエンベロープに変換します。アダプターは以下の処理を行います：

  • デコード: プラットフォーム固有のペイロード → 正規メッセージ形式
  • 重複排除: 同じメッセージが2回処理されること（再起動、再試行）を防止します
  • ペアチェック: イベントがランタイムに到達する前に [channels.<name>.allowed_users] / IAM ポリシーを強制します

チャンネルがペアリングされていないか、ユーザーに許可がない場合、イベントはランタイムがそれを見る前にドロップされます。

エージェントループ

sequenceDiagram
    participant CH as Channel
    participant RT as Runtime
    participant SEC as Security
    participant MEM as Memory / history
    participant PR as Provider
    participant TL as Tool

    CH->>RT: process_message(envelope)
    Note over RT: resolve memory-inject policy from the turn's TurnOrigin
    RT->>MEM: recall(query, session scopes)
    MEM-->>RT: entries
    Note over RT: render [Memory context] preamble (engine-side)
    RT->>PR: chat(system, history, tools)
    loop Streaming
        PR-->>RT: StreamEvent::TextDelta
        RT-->>CH: draft update (if channel supports it)
    end
    PR-->>RT: StreamEvent::ToolCall(args)
    RT->>SEC: evaluate_tool_access(name, args, risk)
    alt Blocked
        SEC-->>RT: Err(reason)
        RT->>PR: chat(..., + tool_error)
    else Approval required
        SEC->>CH: ask_operator(prompt)
        CH-->>SEC: approved / denied
    else Allowed
        SEC-->>RT: Ok
    end
    RT->>TL: invoke(args)
    TL-->>RT: ToolResult
    RT->>MEM: append to turn/session history
    RT->>PR: chat(..., + tool_result)
    PR-->>RT: StreamEvent::TextDelta (final)
    RT-->>CH: reply(final)
    RT->>MEM: persist conversation/session history

主要なプロパティ:

  • ストリーミングはエンドツーエンドです。 プロバイダはトークンをストリーミングします。チャネルアダプタが supports_draft_updates() を報告する場合、ランタイムはテキストが到着するたびに送信済みメッセージをその場で編集します。Discord、Slack、Telegram はこれをサポートしています。
  • **ツール呼び出しはストリームの途中で行われます。**モデルはテキストの生成中でもツール呼び出しを発行できます。ランタイムはストリームを最後まで読み取り、表示可能なテキストを到着したそばからフラッシュし、その後ツール呼び出しを復元して検証し、呼び出しを実行し、結果をフィードバックして、次のターンに向けて新しいストリームを開始します。
  • ストリーミングの完了はプロトコルイベントに従います。 プロバイダーは、サーバーが接続を閉じるのを待つのではなく、終端 SSE イベントが到着すると、正常なストリームを完了します。レスポンスボディでバイトの受信がない状態が続くと、プロバイダーのバイトアイドルタイムアウト後に失敗します。一方、生成処理がアクティブな間は、非ストリーミングリクエストのタイムアウトを超えて継続する場合があります。
  • セキュリティはすべてのツール呼び出しを検査します。 evaluate_tool_access は自律性レベル、許可/拒否リスト、パス境界を参照します。Supervised 自律性下での中リスクの呼び出しは、オペレーター承認パスへ送られます。
  • メモリコンテキストはエンジンによって注入されます。 最初のプロバイダー呼び出しの前に、ターンエンジンはターンの TurnOrigin（ターンを開始した主体）から注入ポリシーを解決します: ネストされたサブターンは決して注入せず、スケジュールされたオリジン（cron、daemon）は会話カテゴリのエントリを除外して注入し、ユーザー向けオリジンは注入します（ターンにセッションスコープがない場合は会話エントリを除外）。スポーンサイトは任意のオリジンに対して注入を抑制でき（たとえば uses_memory = false の cron ジョブ）、メモリバックエンドを持たないターンは完全にスキップします。単一のレンダラーが時間減衰、関連性フィルタリング、プロンプトポイズニングのスキップセット、および予算上限をすべてのパスで均一に適用します; メモリバックエンドは recall のみに応答し、コンテキストをフォーマットしません。
  • 履歴とメモリは別です。 セッション履歴は会話、tool-call、および tool-result の連続性を保持します。明示的なメモリ書き込みは、選択されたエントリをメモリバックエンドに永続化します。レシートは、別の永続化されたアーティファクトとしてではなく、会話テキスト内にインバンドで運ばれます。ペイロードの所有権の詳細については、メモリとペイロードのライフサイクル を参照してください。

ツール実行レシート

ツール実行が成功すると、HMAC-SHA256レシートを受け取ることができます。このレシートはツール結果のテキストに付加され、会話内でモデルに返されることで、署名された結果がランタイムから発行されたものであることを証明します。HMACは一時的なメモリ内キーでキー付けされ、tool_name || args || result || timestamp に対して計算されます。レシートは別のオンディスクログには書き込まれず、チェーン化もされません。モデルはレシートをエコーバックできますが、キーなしで有効な新しいレシートを偽造することはできません。ツールレシートを参照してください。

アウトバウンド

送信メッセージは同じチャネルアダプタを介して戻ります。マルチメッセージ対応のアダプタ（Discord、Slack）は、長い返信をメッセージのシーケンスとしてストリーミングできます。それ以外のアダプタ（メール、SMS）は、ストリームの完了時にフラッシュします。

コード内での場所

  • エージェントループ: crates/zeroclaw-runtime/src/agent/turn/ (run_tool_call_loop)、エントリーポイントは crates/zeroclaw-runtime/src/agent/loop_.rs (process_message, run)
  • メモリコンテキスト注入: crates/zeroclaw-runtime/src/agent/memory_inject.rs (resolve_inject_policy, render_memory_context)、zeroclaw-api の ingress 型の TurnOrigin をキーとし、ターンエンジンによって呼び出される
  • ツール呼び出しのアクセスチェック: crates/zeroclaw-runtime/src/security/ (iam_policy.rs evaluate_tool_access)
  • チャネルオーケストレーション: crates/zeroclaw-channels/src/orchestrator/
  • プロバイダーストリーミング: crates/zeroclaw-api/src/model_provider.rs （StreamEvent 列挙型、zeroclaw-providers から再エクスポート）、compatible.rs （SSE パーサー）

#7415 以降、すべてのトランスポート（チャンネル、CLI、cron、ゲートウェイ WebSocket、RPC/zerocode、ACP、および組み込み Agent API）が同じターンエンジン、すなわち crates/zeroclaw-runtime/src/agent/turn/ 内の run_tool_call_loop を実行します。ストリーミングおよび組み込みのエントリポイントは agent.rs 内の薄いラッパーであり、共有ループの周囲で呼び出し元ごとの設定（dedup、イテレーション上限の挙動、イベント発行）を設定します。turn/ モジュールは、ステップごとに 1 ファイルで構成されています。

ファイルステップ
mod.rsorchestrator: 反復制御、調整ノブ、ステアリングドレイン
history_window.rs · tool_specs.rs · vision_route.rs呼び出し前: 履歴の保守、ツール仕様、ビジョンルーティング
provider_call.rs · stream_consume.rs · stream_guard.rsLLM 呼び出し、ストリーム消費、ストリーム途中のプロトコルガード
parse_response.rs · protocol_detect.rs · context_recovery.rs応答の解釈、解析問題の検出、オーバーフロー回復
approval_gate.rs · call_prep.rsツール呼び出しの承認と準備（重複排除、フック、配信デフォルト）
post_exec.rs · results_collect.rs · history_append.rs · max_iter.rs結果の記録、ループ検出、履歴の追加、反復回数の上限
context.rs · events.rs · knobs.rs · steering.rs · outcome.rs · redact.rs · delivery_defaults.rs共有型: ターンコンテキスト、イベント、呼び出し元ごとの調整パラメーター、ステアリング、結果、認証情報のスクラビング