バックグラウンド エージェントを使用すると、親エージェントは独立したタスクを名前付き子エージェントに委任できます。 各タスクは独自の子エージェント セッションで同時に実行されますが、親はタスク ID を保持します。この ID は、待機、結果の取得、作業の続行、またはタスクの解放に使用できます。
Important
バックグラウンドエージェントは実験的な機能です。
バックグラウンド エージェントは、 バックグラウンド応答とは異なります。 バックグラウンド応答は、アプリケーションがポーリングまたは再開する 1 つのプロバイダー リクエストを指します。 バックグラウンド エージェント タスクは、別の Agent Framework エージェントを呼び出し、後でそのエージェントのテキスト結果を親にフィードします。
バックグラウンド エージェントを手動で設定する
各子エージェントには、空でなく、大文字と小文字を区別しない一意の名前が必要です。 子エージェントに重点を置いた指示と、委任されたロールに必要なツールのみを提供します。
BackgroundAgentsProviderインポートし、ChatClientAgentOptions.AIContextProvidersを使用して通常のエージェントに追加します。
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
var backgroundProvider = new BackgroundAgentsProvider(
[webSearchAgent, codeAnalysisAgent]);
AIAgent parentAgent = chatClient.AsAIAgent(new ChatClientAgentOptions
{
Name = "research-coordinator",
AIContextProviders = [backgroundProvider],
});
AgentSession session = await parentAgent.CreateSessionAsync();
BackgroundAgentsProviderOptions は、プロバイダーの指示とエージェントリストの書式設定をカスタマイズします。
from agent_framework import Agent, BackgroundAgentsProvider
background_provider = BackgroundAgentsProvider(
[web_search_agent, code_analysis_agent],
wait_timeout_seconds=30,
)
parent_agent = Agent(
client=client,
name="research-coordinator",
context_providers=[background_provider],
)
session = parent_agent.create_session()
instructions=をBackgroundAgentsProviderに渡して、その指示を置き換えます。 書式設定された子エージェントの一覧が表示される場所 {background_agents} 含めます。
wait_timeout_seconds は、 background_agents_wait_for_first_completion の各呼び出しが待機する時間を設定します。 正の整数で、既定値は 300 秒にする必要があります。 タイムアウトが切れると、ツールは正常に戻り、タスクを実行し続けます。そのため、親はそれを再度呼び出すことができます。
Note
このページで説明されているパッケージ化されたバックグラウンド エージェント プロバイダーは、現在 Go では使用できません。
タスクのライフサイクル
プロバイダーは、.NETとPythonに同じモデル向けツールを追加します。
| ツール | ライフサイクル アクション |
|---|---|
background_agents_start_task |
名前付きエージェントで非ブロッキング タスクを開始し、その整数タスク ID を返します。 |
background_agents_wait_for_first_completion |
指定されたセット内の最初のタスクが終了状態になるまで待ちます。 |
background_agents_get_task_results |
完了したテキスト、エラー メッセージ、または現在の状態を返します。 |
background_agents_get_all_tasks |
ID、状態、エージェント名、および説明を一覧表示します。 |
background_agents_continue_task |
タスクが完了または失敗した後、既存の子セッションでフォローアップ入力を実行します。 |
background_agents_clear_completed_task |
ターミナル タスクを削除し、その子セッションを解放します。 |
一般的な親エージェント シーケンスは次のとおりです。
- 待機する前にすべての独立したタスクを開始し、タスクが同時に実行されるようにします。
- 最初の完了を待ち、その結果を取得し、タスクが実行されないまで繰り返します。
- フォローアップ作業に既存の会話コンテキストが必要な場合は、完了したタスクまたは失敗したタスクを続行します。
- 結果を取得した後、続行されない限り、ターミナル タスクをクリアします。
タスクの状態は、 running、 completed、 failed、または lostです。 プロセスの再起動やセッションの復元後など、インプロセス タスク ハンドルまたは子セッションが使用できない場合、タスクは失われます。 シリアライズ可能なタスクのメタデータは親セッションに残すことができますが、処理中の作業や子セッションのハンドルはその境界を越えると失われます。
プロバイダーにキャンセル ツールはありません。 タスクをクリアする前に、実行中のタスクを終了状態にします。
同じ親セッションを順番に再利用します。 各タスクには、専用の子セッションが割り当てられます。 ターミナル タスクを続行すると、その子セッションが再利用されます。これをクリアすると、タスク メタデータが削除され、子セッション ハンドルが解放されます。
タスクの結果は、親にテキストとして返されます。 プロバイダーは、子の構造化されたツール承認要求を親経由でプロキシ処理しないため、対話型の承認なしで委任された作業を完了するか、子エージェント ホスト内で承認を処理するように子エージェントを構成します。
ホストから親セッションを解放する
Note
ホスト側のバックグラウンド エージェント セッション リリースは、現在、.NETでは使用できません。
ホストが親セッションを削除または破棄したら、プロバイダーのインプロセス タスクハンドルと子セッション ハンドルを finally ブロックで解放します。
session = parent_agent.create_session()
try:
await parent_agent.run("Coordinate the research.", session=session)
finally:
await background_provider.release_session(session)
release_session(session, *, cancel_running=True, timeout=30.0) はホスト側ライフサイクル API であり、モデル向けツールではありません。 既定では、実行中の子タスクが取り消され、キャンセルされるまで最大 30 秒待ってから、親セッションのすべてのランタイム状態が解放されます。 タスクの実行中にリリースを拒否するように cancel_running=False を設定するか、 timeout=None を無期限に待機するように設定します。
これに対し、 background_agents_clear_completed_task では、モデルは会話中に 1 つのターミナル タスクとその子セッションを削除できます。 実行中のタスクは受け付けず、ホスト側の親セッションの終了処理の代わりにはなりません。
Note
ホスト側のバックグラウンド エージェント セッション リリースは、Go では現在使用できません。
自動待機を手動で追加する
手動で作成した親要素を LoopAgent でラップします。
BackgroundTaskCompletionLoopEvaluator は、タスクが Running 状態の間のみ続行されます。
AIAgent loopingParent = new LoopAgent(
parentAgent,
new BackgroundTaskCompletionLoopEvaluator(),
new LoopAgentOptions { MaxIterations = 10 });
エバリュエーターは、完了したタスク、失敗したタスク、および失われたタスクを停止します。
通常の親に AgentLoopMiddleware を追加し、background-task の述語をその next-message ヘルパーと組み合わせます:
from agent_framework import (
Agent,
AgentLoopMiddleware,
background_tasks_running,
background_tasks_running_message,
)
parent_agent = Agent(
client=client,
context_providers=[background_provider],
middleware=[
AgentLoopMiddleware(
background_tasks_running(),
next_message=background_tasks_running_message,
max_iterations=10,
)
],
)
この条件式は、永続化されたタスク状態がタスクが実行中であることを示している間だけ継続します。
バックグラウンド タスク ループの自動統合は、現在 Go では使用できません。
Harness Agent でバックグラウンド エージェントを使用する
Harness エージェントの既定の計画、メモリ、承認、および可観測パイプラインも必要な場合は、このセットアップを使用します。
HarnessAgentOptions.BackgroundAgentsを設定します。 委任された作業が実行されなくなるまで親が実行を続ける必要がある場合は、完了エバリュエーターを追加します。
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
var options = new HarnessAgentOptions
{
Name = "research-coordinator",
BackgroundAgents = [webSearchAgent, codeAnalysisAgent],
LoopEvaluators = [new BackgroundTaskCompletionLoopEvaluator()],
LoopAgentOptions = new LoopAgentOptions { MaxIterations = 10 },
};
HarnessAgent parentAgent = chatClient.AsHarnessAgent(options);
// Equivalent construction: new HarnessAgent(chatClient, options)
AgentSession session = await parentAgent.CreateSessionAsync();
HarnessAgentOptions.BackgroundAgentsProviderOptionsを使用して、プロバイダーの指示とエージェントリストの書式設定をカスタマイズします。
LoopEvaluatorsを省略すると、自動再呼び出しなしでバックグラウンド委任を使用できます。
create_harness_agentにbackground_agentsを供給します。 親が自動的に待機する必要がある場合は、有界ループと組み合わせます。
from agent_framework import (
background_tasks_running,
background_tasks_running_message,
create_harness_agent,
)
parent_agent = create_harness_agent(
client=client,
name="research-coordinator",
background_agents=[web_search_agent, code_analysis_agent],
background_agents_wait_timeout_seconds=30,
loop_should_continue=background_tasks_running(),
loop_next_message=background_tasks_running_message,
loop_max_iterations=10,
)
session = parent_agent.create_session()
プロバイダーの指示を置き換えるには、 background_agents_instructions を使用します。
background_agents_wait_timeout_secondsは、BackgroundAgentsProviderのwait_timeout_secondsと同じ境界付き待機を構成します。 Python ハーネスでは、ツールの自動承認ミドルウェアが既定で有効になるため、実行ごとにsession渡します。
Note
Harness エージェントのバックグラウンド委任は、現在 Go では使用できません。
セキュリティに関する考慮事項
信頼できる子エージェントのみを登録します。 親は、プライベート コンテキストまたは信頼されていないコンテキストから派生したテキストを送信でき、その結果は親のコンテキストに追加されます。 侵害された子は、委任された入力を流出させたり、間接的なプロンプト挿入コンテンツを返したりする可能性があります。