Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Agenten im Hintergrund ermöglichen es einem übergeordneten Agenten, unabhängige Aufgaben an benannte untergeordnete Agenten zu delegieren. Jede Aufgabe wird parallel in ihrer eigenen Sitzung untergeordneter Agenten ausgeführt, während der übergeordnete Agent eine Task-ID führt, mit der er warten, Ergebnisse abrufen, die Arbeit fortsetzen oder die Aufgabe freigeben kann.
Important
Hintergrund-Agents sind experimentell.
Hintergrund-Agents unterscheiden sich von Hintergrundantworten. Eine Hintergrundantwort stellt eine Anbieteranforderung dar, die von der Anwendung abgerufen oder fortgesetzt wird. Eine Hintergrund-Agentaufgabe ruft einen anderen Agenten des Agent Frameworks auf und gibt dessen Textergebnis später an den übergeordneten Agenten zurück.
Manuelles Einrichten von Hintergrund-Agents
Jeder untergeordnete Agent muss einen nicht leeren Namen haben, der ohne Berücksichtigung der Groß-/Kleinschreibung eindeutig ist. Geben Sie untergeordneten Agenten gezielte Anweisungen und nur die Tools, die sie für ihre zugewiesene Rolle benötigen.
Importieren Sie BackgroundAgentsProvider und fügen Sie es mithilfe von ChatClientAgentOptions.AIContextProviders zu einem regulären Agenten hinzu:
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 passt die Anbieteranweisungen und die Agentlistenformatierung an.
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()
Übergeben Sie instructions= an BackgroundAgentsProvider, um dessen Anweisungen zu ersetzen. Fügen Sie {background_agents} an der Stelle ein, an der die formatierte Liste der untergeordneten Agents erscheinen soll.
wait_timeout_seconds legt fest, wie lange jeder Aufruf von background_agents_wait_for_first_completion wartet. Es muss eine positive ganze Zahl sein und standardmäßig 300 Sekunden sein. Wenn das Timeout abläuft, beendet sich das Tool regulär und lässt die Aufgaben weiterlaufen, sodass der übergeordnete Prozess es erneut aufrufen kann.
Note
Der auf dieser Seite beschriebene gepackte Hintergrund-Agent-Anbieter ist derzeit in Go nicht verfügbar.
Aufgabenlebenszyklus
Der Anbieter fügt die gleichen modellorientierten Tools in .NET und Python hinzu:
| Tool | Lebenszyklusaktion |
|---|---|
background_agents_start_task |
Starten Sie eine nicht blockierende Aufgabe auf einem benannten Agenten und geben Sie deren ganzzahlige Aufgaben-ID zurück. |
background_agents_wait_for_first_completion |
Warten Sie, bis der erste Vorgang in einem angegebenen Satz einen Terminalstatus erreicht. |
background_agents_get_task_results |
Geben Sie fertiggestellten Text, eine Fehlermeldung oder den aktuellen Status zurück. |
background_agents_get_all_tasks |
IDs, Status, Agentennamen und Beschreibungen auflisten. |
background_agents_continue_task |
Führen Sie die Folgeeingabe in der bestehenden untergeordneten Sitzung aus, nachdem eine Aufgabe abgeschlossen wurde oder fehlgeschlagen ist. |
background_agents_clear_completed_task |
Entfernen Sie eine Terminalaufgabe und geben Sie ihre zugehörige untergeordnete Sitzung frei. |
Eine typische Parent-Agent-Sequenz ist:
- Starten Sie alle unabhängigen Aufgaben, bevor Sie warten, sodass die Aufgaben gleichzeitig ausgeführt werden.
- Warten Sie auf den ersten Abschluss, rufen Sie das Ergebnis ab, und wiederholen Sie den Vorgang, bis keine Aufgaben ausgeführt werden.
- Setzen Sie eine abgeschlossene oder fehlgeschlagene Aufgabe fort, wenn für die Folgearbeit der bestehende Gesprächskontext benötigt wird.
- Löschen Sie Terminalaufgaben nach dem Abrufen ihrer Ergebnisse, es sei denn, sie werden fortgesetzt.
Der Vorgangsstatus ist running, completed, , failedoder lost. Eine Aufgabe gilt als verloren, wenn ihr Aufgaben-Handle eines laufenden Prozesses oder ihre untergeordnete Sitzung nicht verfügbar ist, z. B. nach einem Prozessneustart oder einer Sitzungswiederherstellung. Serialisierbare Aufgabenmetadaten können in der übergeordneten Sitzung verbleiben, laufende Vorgänge und Handles der untergeordneten Sitzung überstehen diese Grenze jedoch nicht.
Es gibt kein Abbruchtool im Anbieter. Lassen Sie die Ausführung von Aufgaben einen Terminalzustand erreichen, bevor Sie sie löschen.
Verwenden Sie die gleiche übergeordnete Sitzung über Wendungen hinweg wieder. Jede Aufgabe empfängt eine dedizierte untergeordnete Sitzung. Durch fortsetzen einer Terminalaufgabe wird diese untergeordnete Sitzung wiederverwendet; Durch das Löschen werden die Aufgabenmetadaten entfernt und das Handle für untergeordnete Sitzungen freigegeben.
Aufgabenergebnisse werden als Text an das übergeordnete Element zurückgegeben. Der Anbieter leitet die strukturierte Anfrage zur Tool-Genehmigung eines untergeordneten Agents nicht über den übergeordneten Agenten zurück. Konfigurieren Sie untergeordnete Agenten daher so, dass sie delegierte Aufgaben ohne interaktive Genehmigung ausführen oder Genehmigungen im Host des untergeordneten Agents verarbeiten.
Freigeben einer übergeordneten Sitzung vom Host
Note
Hostseitige Hintergrund-Agent-Sitzungsfreigabe ist derzeit in .NET nicht verfügbar.
Wenn der Host eine übergeordnete Sitzung entfernt oder verwirft, geben Sie die prozessinterne Aufgabe des Anbieters und die Handles der untergeordneten Sitzungen in einem finally-Block frei:
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) ist eine hostseitige Lebenszyklus-API, kein modellorientiertes Tool. Standardmäßig wird die Ausführung untergeordneter Aufgaben abgebrochen und bis zu 30 Sekunden auf den Abbruch gewartet, bevor der gesamte Laufzeitstatus für die übergeordnete Sitzung freigegeben wird. Setzen Sie cancel_running=False so, dass die Freigabe abgelehnt wird, solange Aufgaben ausgeführt werden, oder setzen Sie timeout=None so, dass unbegrenzt gewartet wird.
Im Gegensatz dazu ermöglicht background_agents_clear_completed_task dem Modell, während einer Unterhaltung eine Terminal-Aufgabe und die zugehörige untergeordnete Sitzung zu entfernen. Sie weist laufende Aufgaben zurück und ersetzt nicht das hostseitige Herunterfahren der übergeordneten Sitzung.
Note
Hostseitige Hintergrund-Agent-Sitzungsfreigabe ist derzeit in Go nicht verfügbar.
Automatische Wartezeit manuell hinzufügen
Verpacken Sie das manuell erstellte übergeordnete Element mit LoopAgent.
BackgroundTaskCompletionLoopEvaluator wird nur fortgesetzt, während ein Vorgang im Running Zustand verbleibt:
AIAgent loopingParent = new LoopAgent(
parentAgent,
new BackgroundTaskCompletionLoopEvaluator(),
new LoopAgentOptions { MaxIterations = 10 });
Der Evaluator stoppt bei abgeschlossenen, fehlgeschlagenen und verlorenen Aufgaben.
Fügen Sie AgentLoopMiddleware dem regulären übergeordneten Element hinzu und koppeln Sie das Prädikat für Hintergrundaufgaben mit seiner Hilfsfunktion für die nächste Nachricht:
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,
)
],
)
Das Prädikat gilt nur so lange, wie der gespeicherte Aufgabenzustand weiterhin eine laufende Aufgabe angibt.
Die automatische Integration von Hintergrundaufgabenschleifen ist derzeit in Go nicht verfügbar.
Verwenden Sie Hintergrundagenten mit Harness Agent
Verwenden Sie dieses Setup, wenn Sie auch die standardmäßige Planungs-, Speicher-, Freigabe- und Observability-Pipeline des Harness Agent verwenden möchten.
Legen Sie HarnessAgentOptions.BackgroundAgents fest. Fügen Sie den Abschlussauswerter hinzu, wenn das übergeordnete Element weiterlaufen soll, bis die delegierte Aufgabe nicht mehr ausgeführt wird:
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();
Verwenden Sie HarnessAgentOptions.BackgroundAgentsProviderOptions, um Anweisungen für Anbieter und die Formatierung der Agentenliste anzupassen. Das Weglassen von LoopEvaluators sorgt dafür, dass die Hintergrunddelegierung ohne automatische erneute Ausführung verfügbar bleibt.
Liefern background_agents an create_harness_agent. Koppeln Sie sie mit einer gebundenen Schleife, wenn das übergeordnete Element automatisch warten soll:
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()
Verwenden Sie background_agents_instructions, um die Anweisungen des Anbieters zu ersetzen.
background_agents_wait_timeout_seconds konfiguriert dieselbe begrenzte Wartezeit wie wait_timeout_seconds für BackgroundAgentsProvider. Das Python-Harness aktiviert standardmäßig die Middleware zur automatischen Genehmigung von Tools. Übergeben Sie daher bei jeder Ausführung session.
Note
Die Delegierung im Hintergrund für Harness Agent ist in Go derzeit nicht verfügbar.
Sicherheitsüberlegungen
Registrieren Sie nur untergeordnete Agenten, denen Sie vertrauen. Das übergeordnete Element kann ihnen Text senden, der aus privatem oder nicht vertrauenswürdigem Kontext stammt, und ihre Ergebnisse werden dem Kontext des übergeordneten Elements wieder hinzugefügt. Eine kompromittierte untergeordnete Instanz kann delegierte Eingaben exfiltrieren oder Inhalte für indirekte Prompt-Injektion zurückgeben.