Agenti in background

Gli agenti in background permettono a un agente principale di delegare attività indipendenti ad agenti figli con nome. Ogni attività viene eseguita simultaneamente nella propria sessione dell'agente figlio, mentre l'elemento padre mantiene un ID attività che può usare per attendere, recuperare i risultati, continuare il lavoro o rilasciare l'attività.

Importante

Gli agenti in background sono sperimentali.

Gli agenti in background sono diversi dalle risposte in background. Una risposta in background rappresenta una richiesta del provider che esegue il polling o la ripresa dell'applicazione. Un'attività di un agente in background richiama un altro agente di Agent Framework e successivamente restituisce il risultato testuale di quell'agente all'agente padre.

Configurare manualmente gli agenti in background

Ogni agente figlio deve avere un nome non vuoto e univoco senza distinzione tra maiuscole e minuscole. Fornite agli agenti figli istruzioni mirate e solo gli strumenti necessari per il ruolo loro delegato.

Importa BackgroundAgentsProvider e aggiungilo a un agente normale attraverso 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 personalizza le istruzioni del provider e la formattazione dell'elenco agenti.

from agent_framework import Agent, BackgroundAgentsProvider

background_provider = BackgroundAgentsProvider(
    [web_search_agent, code_analysis_agent]
)

parent_agent = Agent(
    client=client,
    name="research-coordinator",
    context_providers=[background_provider],
)
session = parent_agent.create_session()

Passare instructions= a BackgroundAgentsProvider per sostituire le istruzioni. Inserire {background_agents} nel punto in cui deve essere visualizzato l'elenco formattato degli agenti secondari.

Annotazioni

Il fornitore dell'agente in background predefinito descritto in questa pagina al momento non è disponibile in Go.

Ciclo di vita delle attività

Il provider aggiunge gli stessi strumenti per il modello in .NET e Python:

Tool Azione del ciclo di vita
background_agents_start_task Avvia un'attività non bloccante su un agente con nome specificato e restituisce il relativo ID intero dell'attività.
background_agents_wait_for_first_completion Attendere che la prima attività in un set fornito raggiunga uno stato terminale.
background_agents_get_task_results Restituisce il testo completato, un messaggio di errore o lo stato corrente.
background_agents_get_all_tasks Elenca gli ID, gli stati, i nomi degli agenti e le descrizioni.
background_agents_continue_task Eseguire l'input successivo nella sessione figlia esistente dopo il completamento o l'errore di un'attività.
background_agents_clear_completed_task Rimuovere un processo del terminale e rilasciare la relativa sessione figlia.

Una tipica sequenza padre-agente è la seguente:

  1. Avviare ogni attività indipendente prima dell'attesa, quindi le attività vengono eseguite simultaneamente.
  2. Attendere il completamento della prima, recuperarne il risultato e ripetere finché non ci sono più attività in esecuzione.
  3. Continuare un'attività completata o non riuscita quando il lavoro successivo richiede il contesto della conversazione esistente.
  4. Cancellare le attività del terminale dopo aver recuperato i risultati, a meno che non vengano continuate.

Lo stato dell'attività è running, completed, failed o lost. Un'attività si perde quando il relativo riferimento all'attività in corso o la sessione figlia non sono disponibili, ad esempio dopo un riavvio del processo o il ripristino di una sessione. I metadati di attività serializzabili possono rimanere nella sessione padre, ma il lavoro in corso e i riferimenti alle sessioni figlie non oltrepassano tale confine.

Non esiste alcuno strumento di annullamento nel provider. Lasciare che le attività in esecuzione raggiungano uno stato del terminale prima di cancellarle.

Riutilizzare la stessa sessione padre tra turni. Ogni attività riceve una sessione figlio dedicata. Riprendere un'attività del terminale riutilizza quella sessione figlia; cancellarla rimuove i metadati dell'attività e rilascia l'handle della sessione figlia.

I risultati dell'attività vengono restituiti al padre come testo. Il provider non inoltra attraverso l'agente padre una richiesta strutturata di approvazione degli strumenti proveniente da un agente figlio, quindi configurate gli agenti figlio in modo che completino il lavoro delegato senza approvazione interattiva oppure gestite le approvazioni all'interno dell'host dell'agente figlio.

Aggiungi manualmente l'attesa automatica

Eseguire il wrapping dell'elemento padre composto manualmente con LoopAgent. BackgroundTaskCompletionLoopEvaluator continua solo mentre un'attività rimane nello Running stato:

AIAgent loopingParent = new LoopAgent(
    parentAgent,
    new BackgroundTaskCompletionLoopEvaluator(),
    new LoopAgentOptions { MaxIterations = 10 });

Il valutatore si arresta in caso di attività completate, non riuscite o perse.

Aggiungi AgentLoopMiddleware al genitore regolare e abbina il predicato dell'attività in background con il relativo helper 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,
        )
    ],
)

Il predicato continua solo mentre lo stato dell'attività persistente segnala ancora un'attività in esecuzione.

L'integrazione automatica del ciclo di attività in background non è attualmente disponibile in Go.

Usare agenti in background con Harness Agent

Utilizza questa configurazione se vuoi anche la pianificazione, la memoria, l'approvazione e la pipeline di osservabilità predefinite dell'agente Harness.

Imposta HarnessAgentOptions.BackgroundAgents. Aggiungere l'analizzatore di completamento quando l'elemento padre deve continuare l'esecuzione fino a quando il lavoro delegato non è più in esecuzione:

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();

Usare HarnessAgentOptions.BackgroundAgentsProviderOptions per personalizzare le istruzioni del provider e la formattazione dell'elenco agenti. Omettere LoopEvaluators mantiene disponibile la delega in background senza nuova invocazione automatica.

Fornire background_agents a create_harness_agent. Abbinalo a un loop delimitato quando il genitore deve attendere automaticamente:

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],
    loop_should_continue=background_tasks_running(),
    loop_next_message=background_tasks_running_message,
    loop_max_iterations=10,
)
session = parent_agent.create_session()

Usare background_agents_instructions per sostituire le istruzioni del provider. L'harness Python abilita per impostazione predefinita il middleware per l'approvazione automatica degli strumenti, quindi devi passare session a ogni esecuzione.

Annotazioni

La delega in background dell'agente harness non è attualmente disponibile in Go.

Considerazioni relative alla sicurezza

Registra solo gli agenti secondari di cui ti fidi. L'elemento padre può inviare loro del testo derivato da un contesto privato o non attendibile e i relativi risultati vengono aggiunti nuovamente al contesto dell'elemento padre. Un figlio compromesso può esfiltrare l'input delegato o restituire contenuto di inserimento indiretto tramite prompt.

Passaggi successivi

Pianifica il lavoro e tieni traccia delle attività

Approfondimento

  • Last updated on