BoxAgnts入門（2）— AIエージェントツールボックス

User Message
  │
  ▼
┌─────────────────────────────────────────────────────────────┐
│  boxagnts-api            Unified API Abstraction Layer      │
│  LlmProvider trait → 20+ Providers → Message Normalization  │
├─────────────────────────────────────────────────────────────┤
│  boxagnts-query          Agent Query Loop                   │
│  run_query_loop() → Multi-turn Conversation → Tool Dispatch → Auto Recovery │
├─────────────────────────────────────────────────────────────┤
│  boxagnts-tools + tools-manager + wasm-tools                │
│  Tool trait → Built-in Tools + WASM Tools → Execution       │
├─────────────────────────────────────────────────────────────┤
│  boxagnts-gateway        Gateway & Scheduling               │
│  Cron Scheduler + Site Hosting                              │
├─────────────────────────────────────────────────────────────┤
│  boxagnts-workspace      Memory & Configuration             │
│  SQLite + JSON Config + Conversation History                │
└─────────────────────────────────────────────────────────────┘

#[async_trait]
pub trait LlmProvider: Send + Sync {
    fn id(&self) -> &ProviderId;       // 一意の識別子「anthropic」「openai」
    fn name(&self) -> &str;            // 人が読める名前

    // 非ストリーミングリクエスト
    async fn create_message(&self, request: ProviderRequest)
        -> Result<ProviderResponse, ProviderError>;

    // ストリーミングリクエスト（Pin<Box<dyn Stream>>を返す）
    async fn create_message_stream(&self, request: ProviderRequest)
        -> Result<Pin<Box<dyn Stream<Item = Result<StreamEvent, ProviderError>> + Send>>, ProviderError>;

    // 利用可能なモデルを列挙
    async fn list_models(&self) -> Result<Vec<ModelInfo>, ProviderError>;
}

Raw User Message
    │
    ▼
┌────────────────┐
│  Transformer   │  ← 内部メッセージ形式をプロバイダー固有の形式へ変換
│  (per-provider)│
└───────┬────────┘
        ▼
┌────────────────┐
│   Provider     │  ← 認証、HTTPリクエスト、ストリーム解析を担当
│  (per-provider)│
└───────┬────────┘
        ▼
    AI Response
        │
        ▼
┌────────────────┐
│  Transformer   │  ← プロバイダー応答を内部の統一フォーマットへ変換
└────────────────┘

pub fn api_key_env_vars_for_provider(provider_id: &str) -> &'static [&'static str] {
    match provider_id {
        "anthropic" => &["ANTHROPIC_API_KEY"],
        "openai"    => &["OPENAI_API_KEY"],
        "deepseek"  => &["DEEPSEEK_API_KEY"],
        "zhipu"     => &["ZHIPU_API_KEY"],
        "minimax"   => &["MINIMAX_API_KEY"],
        // ... 30+ providers
    }
}

loop {
    turn += 1;

    // 0. キャンセルシグナルを確認
    if cancel_token.is_cancelled() { return Cancelled; }

    // 1. 最大ターン数の制限を確認
    if turn > effective_max_turns { return EndTurn; }

    // 2. 保留中のユーザーメッセージを注入（マルチモーダル・インタラクション）
    if let Some(queue) = pending_messages.as_deref_mut() {
        for text in queue.drain(..) { /* ユーザーメッセージとして追加 */ }
    }

    // 3. 自動コンテキスト圧縮
    compact_state.maybe_compact(messages, config);

    // 4. APIリクエストを構築
    let request = build_request(messages, tools, config);

    // 5. AIモデルへ送信（ストリーミング対応）
    let response = client.create_message_stream(request).await;

    // 6. 返信からContentBlocksを解析
    for block in response.content {
        match block {
            ContentBlock::Text { text } => { /* テキストの応答を蓄積 */ }
            ContentBlock::ToolUse { name, input, .. } => {
                // ツールを照合して実行
                let tool = find_tool(name);
                let result = tool.execute(input, tool_ctx).await;
                messages.push(tool_result);  // 結果を会話に注入
            }
            ContentBlock::Thinking { thinking, .. } => {
                // 深い思考コンテンツを処理（ユーザーには表示しない）
            }
        }
    }

返却形式: {"translated": "翻訳されたHTML"}// 7. モデルが終了 → 最終メッセージを返す
    if stop_reason == "end_turn" { return EndTurn; }
}

"出力トークンの上限に到達しました。直接再開してください — 謝罪も、あなたが行っていたことの要約も不要です。切り取られたところが思考の途中だった場合は、その途中から引き継いでください。残りの作業をより小さな部分に分割してください。"

// query.rs — 過負荷エラー時にバックアップモデルへ自動切り替え
if is_overloaded_error(&err) && fallback_model.is_some() && !used_fallback {
    effective_model = fallback_model;
    used_fallback = true;
    continue; // バックアップモデルで再試行
}

pub enum QueryOutcome {
    BudgetExceeded { cost_usd: f64, limit_usd: f64},
    // ...
}

pub enum ContentBlock {
    Text { text: String },                          // プレーンテキスト
    Image { source: ImageSource },                  // 画像
    ToolUse { id, name, input },                    // ツール呼び出し
    ToolResult { tool_use_id, content, is_error },  // ツール結果
    Thinking { thinking, signature },               // 深い思考
    Document { source, title, context },            // ドキュメント参照
    UserLocalCommandOutput { command, output },     // シェルコマンドの出力
    UserCommand { name, args },                     // ユーザーコマンド
    UserMemoryInput { key, value },                 // ユーザーの記憶
    SystemAPIError { message, retry_secs },         // APIエラー
    CollapsedReadSearch { tool_name, paths },       // 折りたたまれた検索結果
    TaskAssignment { id, subject, description },    // 下位タスクの割り当て
    // ...
}

                    ユーザー
                      │
                      ▼
         ┌───────────────────────┐
         │  マネージャー・エージェント │  ← 強力なモデルを使用（例: Claude Opus）
         │ タスクを分析 → 分解 → 割り当て │
         └───────┬───────────────┘
                 │
        ┌────────┼────────┐
        ▼        ▼        ▼
   ┌────────┐┌────────┐┌────────┐
   │Executor││Executor││Executor│  ← 経済的なモデルを使用（例: Claude Sonnet/Deepseek）
   │Subtask1││Subtask2││Subtask3│
   └────┬───┘└────┬───┘└────┬───┘
        │         │         │
        └────────┼─────────┘
                 ▼
          マネージャーが結果を集約
                 │
                 ▼
              最終出力

pub struct ManagedAgentConfig {
    pub enabled: bool,
    pub manager_model: String,           // マネージャーのモデル（例: "claude-opus-4-6"）
    pub executor_model: String,          // エグゼキューターのモデル（例: "claude-sonnet-4-6"）
    pub executor_max_turns: u32,         // エグゼキューターごとの最大ターン数
    pub max_concurrent_executors: u32,   // 最大同時エグゼキューター数
    pub total_budget_usd: Option<f64>,   // 総予算の上限
    pub executor_isolation: bool,        // Git worktree を分離するかどうか
}

あなたはマネージャーであり、計画と推論のレイヤーです。
あなたは作業を調整しますが、ファイル／bash ツールを直接使ってタスクは実行しません。
すべての実装作業は、エグゼキューター・エージェントに委任されます（Agent ツール経由）。
各エグゼキューターは {executor_model} を使用し、最大 {max_turns} ターンまでです。
最大 {max_concurrent} 個のエグゼキューターを並列で実行できます。

#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &'static str;
    fn description(&self) -> &'static str;
    fn input_schema(&self) -> Value;    // パラメータを定義する JSON スキーマ
    async fn execute(&self, input: Value, ctx: &ToolContext) -> ToolResult;
}

pub struct ToolContext {
    pub cost_tracker: Arc<CostTracker>,         // コスト追跡
    pub session_id: Option<String>,             // セッション ID
    pub current_turn: Arc<AtomicUsize>,         // 現在のターン
    pub non_interactive: bool,                  // ノンインタラクティブ・モード
    pub config: Config,                         // グローバル設定
    pub managed_agent_config: Option<ManagedAgentConfig>,
    pub allowed_outbound_hosts: Vec<String>,    // アウトバウンド接続のホワイトリスト
    pub block_url: Option<String>,              // ブロックされた URL
}

// tools-manager/src/lib.rs
pub fn all_tools() -> Vec<Box<dyn Tool>> {
    vec![
        // Rust ネイティブツール
        Box::new(AskUserQuestionTool),
        Box::new(BriefTool),
        Box::new(EnterPlanModeTool),
        Box::new(ExitPlanModeTool),
        Box::new(SleepTool),
        Box::new(SkillTool),
        Box::new(ToolSearchTool),

        // WASM サンドボックスツール — 同じインターフェース、別実装
        Box::new(WasmTool::new("read",  "file-read-component.wasm",  ...)),
        Box::new(WasmTool::new("write", "file-write-component.wasm", ...)),
        Box::new(WasmTool::new("edit",  "file-edit-component.wasm",  ...)),
        Box::new(WasmTool::new("glob",  "file-glob-component.wasm",  ...)),
        Box::new(WasmTool::new("bash",  "bash-component.wasm",       ...)),
        Box::new(WasmTool::new("web_fetch", "web-fetch-component.wasm", ...)),
        Box::new(WasmTool::new("js_exec", "boxedjs-execute-component.wasm", ...)),
    ]
}

// コアとなるスケジューリングロジック
let cron_job = Job::new_async(cron_expr, move |_uuid, _lock| {
    Box::pin(async move {
        let handle = job::execute(prompt, model).await;
        // タイムアウト付きでの実行 + 結果のログ出力
        let result = timeout(Duration::from_secs(timeout), fut).await;
        append_execution_log(job_id, job_name, success, message).await;
    })
});

pub struct QueryConfig {
    pub model: String,                           // モデル名
    pub max_tokens: u32,                         // 最大出力トークン数
    pub max_turns: u32,                          // 最大推論ターン数
    pub system_prompt: Option<String>,           // システムプロンプト
    pub thinking_budget: Option<u32>,            // 思考予算（深い推論）
    pub temperature: Option<f32>,                // 温度パラメータ
    pub tool_result_budget: usize,               // ツール結果の総文字数上限（50000）
    pub effort_level: Option<EffortLevel>,       // 努力量（thinking_budget に影響）
    pub max_budget_usd: Option<f64>,             // USD の予算上限
    pub fallback_model: Option<String>,          // バックアップモデル
    pub agent_definition: Option<AgentDefinition>, // エージェント定義
    pub managed_agents: Option<ManagedAgentConfig>, // 管理モード
    pub output_style: OutputStyle,               // 出力スタイル
    // ... and more
}