Planejamento e tarefas

Dois provedores de contexto oferecem suporte a tarefas de longa duração:

  • Um provedor de tarefas armazena itens de trabalho rastreáveis e fornece ao agente ferramentas para adicionar, marcar como concluídos, remover e inspecionar esses itens.
  • Um provedor de modo de agente armazena o modo operacional atual e fornece às ferramentas do agente para lê-lo ou alterá-lo.

Combine esses provedores diretamente quando precisar apenas de planejamento, ou use o Harness Agent para habilitar os dois como parte do pipeline padrão mais amplo dele.

Ferramentas todo

Os provedores de .NET e Python expõem as mesmas ferramentas voltadas para o modelo:

Tool Purpose
todos_add Adicione um ou mais itens com um título e uma descrição opcional.
todos_complete Marque um ou mais itens concluídos e inclua um motivo de conclusão.
todos_remove Remova itens que não são mais relevantes.
todos_get_remaining Retornar itens incompletos.
todos_get_all Retornar itens completos e incompletos.

O provedor injeta a lista atual de tarefas antes de cada execução para que o agente possa retomar as tarefas pendentes.

Modos de planejamento e execução

AgentModeProvider fornece os modos plan e execute por padrão:

  1. O plano é interativo. O agente analisa os requisitos, cria listas de tarefas, faz perguntas de esclarecimento, apresenta um plano e pede confirmação antes de mudar de modo.
  2. Executar é autônomo. O agente segue o plano, faz escolhas razoáveis quando os detalhes são ambíguos e marca as tarefas pendentes como concluídas.

O provedor expõe mode_get e mode_set. Suas instruções dizem ao modelo para usar mode_set somente quando o usuário permite explicitamente a transição. Os aplicativos também podem alterar o modo diretamente, o que faz com que o provedor injete uma notificação de alteração de modo na próxima execução.

Configurar o planejamento e as tarefas manualmente

Importe e construa os provedores, depois adicione-os por meio de 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();

Personalize os nomes dos modos e as instruções com AgentModeProviderOptions.Modes. O provedor .NET todo armazena o estado em AgentSession.StateBag. TodoProviderOptions pode substituir suas instruções, suprimir a mensagem de lista completa injetada ou fornecer um construtor de mensagens personalizado.

As instruções padrão plan incluem gravar o plano na memória do arquivo. Se o agente composto manualmente não fornecer ferramentas de memória de arquivo, personalize as instruções de modo ou adicione um provedor de memória adequado.

Alterar os modos do aplicativo

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

Use GetModeAsync para ler o modo atual.

Importe e crie os provedores e, em seguida, adicione-os a um Agent comum:

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 por padrão. Use TodoFileStore ou um personalizado TodoStore quando o estado todo precisar ser armazenado fora do conteúdo da sessão. Personalize os modos com AgentModeProvider(mode_instructions={...}).

As instruções padrão plan incluem gravar o plano na memória do arquivo. Se o agente composto manualmente não fornecer ferramentas de memória de arquivo, personalize mode_instructions ou adicione um provedor de memória adequado.

Alterar os modos do aplicativo

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,
)

Note

Os provedores empacotados "todo" e "agent-mode" descritos nesta página não estão disponíveis no momento para Go.

Execute o plano manualmente até a conclusão

O rastreamento de tarefas registra o progresso, mas por si só não reinvoca o agente. Combine isso com um loop limitado de agente quando o modo de execução precisar continuar até que cada todo seja concluído:

Encapsular o agente composto manualmente com LoopAgent. TodoCompletionLoopEvaluator pode restringir a repetição a modos selecionados:

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

Adicione AgentLoopMiddleware ao agente regular e use todos_remaining() com um filtro de modo:

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,
        )
    ],
)

A integração de loop orientada por TODO não está disponível no momento no Go.

Use planejamento e tarefas com o Harness Agent

Use essa configuração quando você também quiser o histórico pré-configurado, a memória, a aprovação e o pipeline de observabilidade do Harness Agent.

HarnessAgent habilita TodoProvider e AgentModeProvider por padrão. Configure o provedor de modo e o loop opcional baseado em TODO por meio de 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();

Defina DisableTodoProvider ou DisableAgentModeProvider para remover um provedor padrão. Para usar uma instância configurada de TodoProvider, desative o padrão e adicione sua instância por meio de AIContextProviders. Você pode resolver provedores habilitados por meio de agent.GetService<TProvider>().

create_harness_agent habilita ambos os provedores por padrão. Forneça instâncias configuradas para substituí-las e adicionar um loop opcional controlado por todo:

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

Defina disable_todo ou disable_mode para remover um provedor padrão. O harness do Python ativa, por padrão, o middleware de aprovação automática de ferramentas, portanto passe session em cada execução.

Note

Atualmente, os provedores de planejamento e tarefas do Harness Agent não estão disponíveis em Go.

Comportamento da sessão

Use a mesma sessão entre turnos. O estado do modo é mantido pela sessão em ambos os SDKs. O estado das tarefas pendentes no .NET é armazenado em AgentSession.StateBag; o Python usa TodoSessionStore por padrão, enquanto TodoFileStore ou um TodoStore personalizado podem externalizar a persistência das tarefas pendentes.

Alterar o modo por meio do código do aplicativo enfileira uma notificação única de alteração de modo na próxima execução. A ferramenta voltada ao modelo mode_set não enfileira essa notificação extra porque o modelo já observou sua própria invocação da ferramenta.

A confirmação de plano para executar é o comportamento no nível da instrução, não uma solicitação de aprovação de ferramentas. As próprias ferramentas todo e mode não exigem aprovação para função; o código do aplicativo pode alterar modos diretamente quando seu host já tiver obtido a permissão necessária.

Próximas Etapas 

Entender a composição do Agent Harness

Aprofunde-se

  • Last updated on