原文（日本語）

Agent SDKのストリーミングモードで、バックグラウンドタスクの通知が配信されない問題を修正しました。

原文（英語）

Fixed background task notifications not being delivered in streaming Agent SDK mode

概要

Claude Code v2.1.41では、Agent SDKをストリーミングモードで使用している際に、バックグラウンドで実行されているタスクの完了通知やステータス更新が配信されない問題が修正されました。これにより、非同期タスクの監視と管理が正常に機能するようになりました。

問題の背景

Agent SDKとは

Agent SDKは、カスタムエージェントを構築するためのフレームワークで、Claude Codeの機能を拡張できます。ストリーミングモードでは、応答が逐次的に返されます。

バックグラウンドタスク

長時間実行されるタスク（テストの実行、ビルド、データ処理など）は、バックグラウンドで非同期実行され、完了時に通知が送信されます。

発生していた問題

ストリーミングモード使用時、バックグラウンドタスクが完了しても通知が届かず、タスクの状態を確認できませんでした。

基本的な使い方

バックグラウンドタスクの実行

修正後は、ストリーミングモードでも通知が正常に配信されます。

# バックグラウンドでテストを実行
> "テストをバックグラウンドで実行してください"

# タスクがバックグラウンドで開始
🔄 Running tests in background (task_id: abc123)

# 他の作業を継続可能
> "ドキュメントを更新してください"

# バックグラウンドタスク完了時に通知が届く（修正後）
✅ Background task completed: abc123
Test results: 42 passed, 0 failed

実践例

長時間ビルドプロセスの監視

複雑なプロジェクトのビルドをバックグラウンドで実行しながら、他の作業を継続します。

# バックグラウンドビルド開始
> "プロジェクト全体をビルドしてください（バックグラウンド）"

🔄 Building project in background (task_id: build-001)

# 他のコード編集を継続
> "認証ロジックを修正してください"

# ビルド完了通知が配信される（修正後）
✅ Background task completed: build-001
Build successful: 234 files compiled, 0 errors

# ビルド結果を確認
> "ビルド結果を表示してください"

データ処理パイプラインの並列実行

複数のデータ処理タスクをバックグラウンドで並列実行します。

# 3つのデータ処理タスクをバックグラウンド実行
> "3つのデータセットを並列処理してください"

🔄 Processing dataset A (task_id: proc-a)
🔄 Processing dataset B (task_id: proc-b)
🔄 Processing dataset C (task_id: proc-c)

# 他の作業を継続
> "レポートテンプレートを作成してください"

# 各タスク完了時に通知が配信される（修正後）
✅ Background task completed: proc-a
Dataset A processed: 10,000 records

✅ Background task completed: proc-c
Dataset C processed: 8,500 records

✅ Background task completed: proc-b
Dataset B processed: 12,300 records

CI/CDパイプラインの監視

複数のCI/CDステージをバックグラウンドで実行し、進捗を監視します。

# CI/CDパイプライン開始
> "CI/CDパイプラインを実行してください"

🔄 Stage 1: Linting (task_id: lint-001)
🔄 Stage 2: Unit tests (task_id: test-001)
🔄 Stage 3: Integration tests (task_id: integration-001)

# 他の開発作業を継続
> "次の機能を実装してください"

# 各ステージ完了時に通知が届く（修正後）
✅ Background task completed: lint-001
Linting passed: 0 issues found

✅ Background task completed: test-001
Unit tests passed: 156/156

✅ Background task completed: integration-001
Integration tests passed: 23/23

Agent SDKカスタムエージェントでの活用

カスタムエージェントでバックグラウンドタスクを使用する例です。

// custom-agent.ts
import { ClaudeAgentSDK } from 'claude-agent-sdk';

const agent = new ClaudeAgentSDK({
  streaming: true,  // ストリーミングモード有効
});

// バックグラウンドタスクを開始
agent.runInBackground(async (taskId) => {
  console.log(`Task ${taskId} started`);

  // 長時間実行される処理
  await performHeavyComputation();

  // 完了通知（修正後は正常に配信される）
  return {
    status: 'completed',
    result: 'Computation finished'
  };
});

マルチステップワークフローの管理

複数のステップを持つワークフローをバックグラウンドで実行します。

# マルチステップワークフロー開始
> "データ収集→処理→分析のワークフローを実行してください"

🔄 Step 1: Data collection (task_id: wf-step1)
🔄 Step 2: Data processing (task_id: wf-step2)
🔄 Step 3: Data analysis (task_id: wf-step3)

# 各ステップの通知が順次配信される（修正後）
✅ Background task completed: wf-step1
Collected 50,000 records from API

✅ Background task completed: wf-step2
Processed 50,000 records, cleaned 48,234

✅ Background task completed: wf-step3
Analysis complete: Key insights saved to report.pdf

この修正の利点

タスク監視の改善

• バックグラウンドタスクの状態をリアルタイムで把握
• 完了通知が確実に配信される
• ストリーミングモードでも通知が機能

非同期処理の信頼性向上

• 長時間実行タスクの管理が容易
• 複数タスクの並列実行を安心して利用
• タスクの失敗やエラーも適切に通知

開発効率の向上

• バックグラウンドタスクを待つ必要がない
• 並列作業が可能
• ワークフローの自動化が容易

バックグラウンドタスクの管理コマンド

タスク一覧の確認

# 実行中のバックグラウンドタスクを表示
> /tasks

タスクの出力確認

# 特定のタスクの出力を確認
> /task-output <task_id>

タスクの停止

# バックグラウンドタスクを停止
> /task-stop <task_id>

注意点

• この修正はストリーミングモードでのAgent SDK使用時にのみ適用されます
• バックグラウンドタスクの実行には、適切な権限とリソースが必要です
• 大量のバックグラウンドタスクを同時実行すると、システムリソースに影響する可能性があります
• タスクの通知はターミナルに表示されますが、履歴は/tasksコマンドで確認できます

Agent SDKストリーミングモードの設定

ストリーミングモード有効化

// agent-config.ts
import { ClaudeAgentSDK } from 'claude-agent-sdk';

const agent = new ClaudeAgentSDK({
  streaming: true,  // ストリーミングモード
  backgroundTasks: true,  // バックグラウンドタスク有効化
});

関連情報

• Claude Code - How it works
• Agent SDK Documentation
• Background Tasks Guide