Pianificazione e attività

Due provider di contesto supportano attività di lunga durata:

  • Un fornitore di attività archivia elementi di lavoro tracciabili e fornisce all'agente gli strumenti per aggiungerli, completarli, rimuoverli e ispezionarli.
  • Un provider della modalità agente memorizza la modalità operativa corrente e fornisce all'agente gli strumenti per leggerla o modificarla.

Combinare direttamente questi provider quando serve solo la pianificazione, oppure usare l'Harness Agent per abilitarli entrambi come parte della sua pipeline predefinita più ampia.

Strumenti Todo

I provider di .NET e Python espongono gli stessi strumenti per il modello:

Tool Finalità
todos_add Aggiungere uno o più elementi con un titolo e una descrizione facoltativa.
todos_complete Contrassegnare uno o più elementi completati e includere un motivo di completamento.
todos_remove Rimuovere gli elementi che non sono più rilevanti.
todos_get_remaining Restituisce elementi incompleti.
todos_get_all Restituisce elementi completi e incompleti.

Il fornitore inserisce l'elenco attuale delle attività prima di ogni esecuzione, in modo che l'agente possa riprendere le attività in sospeso.

Modalità di pianificazione ed esecuzione

AgentModeProvider fornisce le modalità plan e execute per impostazione predefinita:

  1. Il piano è interattivo. L'agente analizza i requisiti, crea attività, pone domande di chiarimento, presenta un piano e chiede prima di cambiare modalità.
  2. L'esecuzione è autonoma. L'agente segue il piano, compie scelte ragionevoli quando alcuni dettagli sono ambigui e contrassegna le attività da svolgere come completate.

Il fornitore rende disponibili mode_get e mode_set. Le istruzioni indicano al modello di usare mode_set solo quando l'utente consente esplicitamente la transizione. Le applicazioni possono anche modificare direttamente la modalità, che fa sì che il provider inserisca una notifica di modifica della modalità all'esecuzione successiva.

Imposta manualmente la pianificazione e le attività

Importare e costruire i provider, quindi aggiungerli tramite ChatClientAgentOptions.AIContextProviders:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var todoProvider = new TodoProvider();
var modeProvider = new AgentModeProvider(
    new AgentModeProviderOptions
    {
        DefaultMode = "plan",
    });

AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions
{
    AIContextProviders = [todoProvider, modeProvider],
});

AgentSession session = await agent.CreateSessionAsync();

Personalizzare i nomi e le istruzioni della modalità con AgentModeProviderOptions.Modes. Il provider todo .NET archivia lo stato in AgentSession.StateBag. TodoProviderOptions può sostituire le istruzioni, eliminare il messaggio todo-list inserito o fornire un generatore di messaggi personalizzato.

Le istruzioni predefinite plan includono la scrittura del piano nella memoria file. Se l'agente composto manualmente non fornisce strumenti di memoria dei file, personalizza le istruzioni della modalità oppure aggiungi un provider di memoria appropriato.

Modificare le modalità dall'applicazione

await modeProvider.SetModeAsync(session, "execute");

Usare GetModeAsync per leggere la modalità corrente.

Importa e crea i provider, quindi aggiungili a un normale Agent:

from agent_framework import (
    Agent,
    AgentModeProvider,
    TodoFileStore,
    TodoProvider,
)

todo_provider = TodoProvider(
    store=TodoFileStore("./todo-state"),
)
mode_provider = AgentModeProvider(
    default_mode="plan",
)

agent = Agent(
    client=client,
    context_providers=[todo_provider, mode_provider],
)

session = agent.create_session()

TodoProvider usa TodoSessionStore per impostazione predefinita. Usare TodoFileStore o un oggetto personalizzato TodoStore quando lo stato di todo deve essere archiviato all'esterno del payload della sessione. Personalizzare le modalità con AgentModeProvider(mode_instructions={...}).

Le istruzioni predefinite plan includono la scrittura del piano nella memoria file. Se l'agente composto manualmente non fornisce strumenti di memoria file, personalizzare mode_instructions o aggiungere un provider di memoria appropriato.

Modificare le modalità dall'applicazione

from agent_framework import get_agent_mode, set_agent_mode

set_agent_mode(
    session,
    "execute",
    source_id=mode_provider.source_id,
    available_modes=mode_provider.available_modes,
)

current_mode = get_agent_mode(
    session,
    source_id=mode_provider.source_id,
    default_mode=mode_provider.default_mode,
    available_modes=mode_provider.available_modes,
)

Annotazioni

I provider in modalità todo e agente in pacchetto descritti in questa pagina non sono attualmente disponibili in Go.

Eseguire manualmente il piano fino al completamento

Todo tracking registra lo stato di avanzamento, ma non richiama di nuovo l'agente. Combinarlo con un ciclo dell'agente delimitato quando la modalità di esecuzione deve continuare finché tutte le attività non sono state completate:

Racchiudi l'agente composto manualmente con LoopAgent. TodoCompletionLoopEvaluator può limitare il ciclo alle modalità selezionate:

AIAgent loopingAgent = new LoopAgent(
    agent,
    new TodoCompletionLoopEvaluator(
        new TodoCompletionLoopEvaluatorOptions
        {
            Modes = ["execute"],
        }),
    new LoopAgentOptions { MaxIterations = 10 });

Aggiungere AgentLoopMiddleware all'agente normale e usare todos_remaining() con un filtro in modalità:

from agent_framework import (
    Agent,
    AgentLoopMiddleware,
    todos_remaining,
    todos_remaining_message,
)

agent = Agent(
    client=client,
    context_providers=[todo_provider, mode_provider],
    middleware=[
        AgentLoopMiddleware(
            todos_remaining(looping_modes=["execute"]),
            next_message=todos_remaining_message,
            max_iterations=10,
        )
    ],
)

L'integrazione del loop basato sui TODO non è al momento disponibile in Go.

Usa la pianificazione e le attività con Harness Agent

Usa questa configurazione se vuoi anche la cronologia, la memoria, il flusso di approvazione e la pipeline di osservabilità preconfigurati di Harness Agent.

HarnessAgent abilita TodoProvider e AgentModeProvider per impostazione predefinita. Configurare il provider di modalità e il ciclo todo-driven facoltativo tramite HarnessAgentOptions:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var options = new HarnessAgentOptions
{
    AgentModeProviderOptions = new AgentModeProviderOptions
    {
        DefaultMode = "plan",
    },
    LoopEvaluators =
    [
        new TodoCompletionLoopEvaluator(
            new TodoCompletionLoopEvaluatorOptions
            {
                Modes = ["execute"],
            }),
    ],
    LoopAgentOptions = new LoopAgentOptions { MaxIterations = 10 },
};

HarnessAgent agent = chatClient.AsHarnessAgent(options);
// Equivalent construction: new HarnessAgent(chatClient, options)
AgentSession session = await agent.CreateSessionAsync();

Impostare DisableTodoProvider o DisableAgentModeProvider rimuovere un provider predefinito. Per usare un'istanza di TodoProvider già configurata, disabilita quella predefinita e aggiungi la tua istanza tramite AIContextProviders. È possibile risolvere i provider abilitati tramite agent.GetService<TProvider>().

create_harness_agent abilita entrambi i provider per impostazione predefinita. Fornire istanze configurate per sostituirle e aggiungere un ciclo todo-driven facoltativo:

from agent_framework import (
    AgentModeProvider,
    TodoFileStore,
    TodoProvider,
    create_harness_agent,
    todos_remaining,
    todos_remaining_message,
)

todo_provider = TodoProvider(store=TodoFileStore("./todo-state"))
mode_provider = AgentModeProvider(default_mode="plan")

agent = create_harness_agent(
    client=client,
    todo_provider=todo_provider,
    mode_provider=mode_provider,
    loop_should_continue=todos_remaining(looping_modes=["execute"]),
    loop_next_message=todos_remaining_message,
    loop_max_iterations=10,
)
session = agent.create_session()

Impostare disable_todo o disable_mode rimuovere un provider predefinito. L'harness Python abilita per impostazione predefinita il middleware per l'approvazione automatica degli strumenti, quindi devi passare session a ogni esecuzione.

Annotazioni

La pianificazione dell'agente harness e i provider di todo non sono attualmente disponibili in Go.

Comportamento della sessione

Usare la stessa sessione tra turni. Lo stato della modalità è gestito dalla sessione in entrambi gli SDK. Lo stato delle attività in .NET viene memorizzato in AgentSession.StateBag; Python usa TodoSessionStore per impostazione predefinita, mentre TodoFileStore o un TodoStore personalizzato possono esternalizzare la persistenza delle attività.

La modifica della modalità dal codice dell'applicazione accoda una notifica di cambio modalità una tantum per l'esecuzione successiva. Lo strumento rivolto al modello mode_set non mette in coda quella notifica aggiuntiva perché il modello ha già rilevato la propria chiamata allo strumento.

La conferma dal piano all'esecuzione è un comportamento a livello di istruzione, non una richiesta di approvazione di uno strumento. Gli strumenti todo e mode stessi non richiedono l'approvazione della funzione; il codice dell'applicazione può modificare le modalità direttamente quando l'host ha già ottenuto l'autorizzazione necessaria.

Passaggi successivi

Comprendere la composizione di Agent Harness

Approfondimento

  • Last updated on