Planification et tâches

Deux fournisseurs de contexte prennent en charge le travail de longue durée :

  • Un fournisseur de tâches stocke des éléments de travail suivables et fournit à l’agent les outils nécessaires pour les ajouter, les marquer comme terminés, les supprimer et les consulter.
  • Un fournisseur de mode agent stocke le mode d’exploitation actuel et donne aux outils de l’agent de lire ou de le modifier.

Composez ces fournisseurs directement lorsque vous avez uniquement besoin de planifier ou utilisez l’agent Harness pour activer les deux dans le cadre de son pipeline par défaut plus large.

Outils de gestion des tâches

Les fournisseurs .NET et Python exposent les mêmes outils orientés modèle :

Tool Purpose
todos_add Ajoutez un ou plusieurs éléments avec un titre et une description facultative.
todos_complete Marquez un ou plusieurs éléments terminés et incluez une raison d’achèvement.
todos_remove Supprimez les éléments qui ne sont plus pertinents.
todos_get_remaining Retourner des éléments incomplets.
todos_get_all Retournez des éléments complets et incomplets.

Le fournisseur injecte la liste des tâches actuelles avant chaque exécution, afin que l’agent puisse reprendre le travail en attente.

Modes Planification et Exécution

AgentModeProvider fournit par défaut les modes plan et execute :

  1. Le plan est interactif. L’assistant analyse les exigences, crée des tâches, pose des questions de clarification, présente un plan et demande confirmation avant de changer de mode.
  2. L’exécution est autonome. L’agent suit le plan, fait des choix raisonnables lorsque certains détails sont ambigus et marque les tâches comme terminées.

Le fournisseur expose mode_get et mode_set. Ses instructions indiquent au modèle d’utiliser mode_set uniquement lorsque l’utilisateur autorise explicitement la transition. Les applications peuvent également modifier le mode directement, ce qui entraîne l’injection d’une notification de modification de mode lors de l’exécution suivante.

Mettre en place manuellement la planification et les tâches

Importez et construisez les fournisseurs, puis ajoutez-les via 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();

Personnaliser les noms et instructions du mode avec AgentModeProviderOptions.Modes. Le fournisseur de gestion des tâches .NET stocke l’état dans AgentSession.StateBag. TodoProviderOptions peut remplacer ses instructions, supprimer le message todo-list injecté ou fournir un générateur de messages personnalisé.

Les instructions par défaut plan incluent l’écriture du plan dans la mémoire du fichier. Si l’agent composé manuellement ne fournit pas d’outils de mémoire de fichier, personnalisez les instructions de mode ou ajoutez un fournisseur de mémoire approprié.

Modifier les modes de l’application

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

Utilisez GetModeAsync pour lire le mode actuel.

Importez et construisez les fournisseurs de service, puis ajoutez-les à un Agent classique :

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 utilise TodoSessionStore par défaut. Utilisez TodoFileStore ou votre propre TodoStore si l’état des tâches à faire doit être stocké en dehors de la charge utile de la session. Personnaliser les modes avec AgentModeProvider(mode_instructions={...}).

Les instructions par défaut plan incluent l’écriture du plan dans la mémoire du fichier. Si l’agent composé manuellement ne fournit pas d’outils de mémoire de fichier, personnalisez mode_instructions ou ajoutez un fournisseur de mémoire approprié.

Modifier les modes de l’application

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

Omettez available_modes pour utiliser les modes intégrés execute et plan. Si vous fournissez available_modes, il doit contenir au moins un mode ; une séquence vide se déclenche ValueError avant la modification de l’état de session.

Outils en mode de contrôle à partir de l’application

Masquez l’un ou l’autre des outils du mode intégré lorsque votre application fournit sa propre interface utilisateur ou un outil destiné au modèle :

mode_provider = AgentModeProvider(
    default_mode="plan",
    expose_mode_set=False,
    expose_mode_get=False,
)

Les deux options sont indépendantes et sont définies par défaut sur True. Masquer les deux outils conserve l’état du mode pris en charge par la session, les instructions à chaque tour et les notifications externes de changement de mode. Ajoutez un outil de remplacement côté modèle via l’argument tools de l’agent et faites en sorte qu’il appelle set_agent_mode(..., notify=False), car le modèle observe déjà le résultat de cet outil. Les modifications apportées à l’application ou à l’interface utilisateur peuvent conserver la valeur par défaut notify=True afin que l’agent reçoive la notification de modification lors de sa prochaine exécution.

Go fournit une planification sauvegardée par session via agent/harness/todo et agent/harness/agentmode. Inscrivez les deux sous agent.Config.ContextProviders :

import (
    "context"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/agent/harness/agentmode"
    "github.com/microsoft/agent-framework-go/agent/harness/todo"
    "github.com/microsoft/agent-framework-go/examples/internal/demo"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)
    modeProvider := agentmode.New(agentmode.Config{
        DefaultMode: new("plan"),
    })

    // The todo provider gives the agent a persistent todo list it can add to, query, and complete.
    todoProvider := todo.New(&todo.Options{})

    // Create a Microsoft Foundry agent with both context providers attached.
    // Providers are invoked in sequence, each contributing tools, instructions, and context messages.
    a := foundryprovider.NewAgent(
        demo.FoundryProjectEndpoint,
        token,
        foundryprovider.ModelDeployment(demo.FoundryModel),
        foundryprovider.AgentConfig{
            Instructions: `You are a diligent engineering assistant that plans before acting.
Start every substantive request in plan mode: analyze the work, then record concrete todo items with todos_add.
Only switch to execute mode with mode_set when the user explicitly asks you to.
As you finish each item, mark it done with todos_complete (include a reason describing how it was completed), and use todos_get_remaining to see what is left.`,
            DisableStoreOutput: true,
            Config: agent.Config{
                Name: "PlanningAssistant",
                ContextProviders: []agent.ContextProvider{
                    modeProvider,
                    todoProvider,
                },
                Middlewares: []agent.Middleware{logger}, // for logging agent interactions
            },
        },
    )

Le fournisseur todo expose todos_add, todos_complete, todos_remove, todos_get_remaininget todos_get_all. Le fournisseur de mode expose mode_get et mode_set, avec les modes intégrés de planification et d’exécution.

Réutilisez le même agent.Session d’un tour à l’autre pour conserver le mode et l’état todo. L’exemple utilise l’historique local via DisableStoreOutput: true.

Consultez l’exemple de planification complet pour la création de l’agent et l’exécution à plusieurs tour.

Exécutez manuellement le plan jusqu’à son terme

Le suivi des tâches enregistre la progression, mais ne réinvoque pas à lui seul l’assistant. Combinez-la avec une boucle d’agent délimitée lorsque le mode d’exécution doit continuer jusqu’à ce que chaque todo soit terminé :

Encapsulez l’agent composé manuellement avec LoopAgent. TodoCompletionLoopEvaluator peut restreindre la boucle aux modes sélectionnés :

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

Ajoutez AgentLoopMiddleware à l’agent standard et utilisez-le todos_remaining() avec un filtre de mode :

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

Le suivi des tâches ne réinvoque pas automatiquement un agent Go. Pour la continuation en mode d’exécution, composez loop.New avec un loop.EvaluatorFunc défini par l’application. Inspectez todo.Provider.RemainingTodos(session) et renvoyez loop.Continue(feedback) ou loop.Stop() selon le cas.

Conservez le mode plan sous contrôle utilisateur et définissez loop.Config.MaxIterations sur l’exécution limitée. Go ne fournit pas d’évaluateur todo-completion intégré. Consultez Looping pour connaître les interfaces d’évaluateur prises en charge.

Utiliser la planification et les tâches avec Harness Agent

Utilisez cette configuration lorsque vous souhaitez également utiliser l’historique préconfiguré, la mémoire, l’approbation et le pipeline d’observabilité de l’agent Harness.

HarnessAgent active TodoProvider et AgentModeProvider par défaut. Configurez le fournisseur du mode et la boucle optionnelle pilotée par les TODO à l’aide 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();

Définissez DisableTodoProvider ou DisableAgentModeProvider pour supprimer un fournisseur par défaut. Pour utiliser un paramètre configuré TodoProvider, désactivez la valeur par défaut et ajoutez votre instance via AIContextProviders. Vous pouvez résoudre les fournisseurs activés via agent.GetService<TProvider>().

create_harness_agent active les deux fournisseurs par défaut. Fournissez des instances configurées pour les remplacer et ajoutez une boucle todo-pilotée facultative :

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

Définissez disable_todo ou disable_mode pour supprimer un fournisseur par défaut. Le harnais Python active par défaut l’intergiciel d’approbation automatique des outils ; passez donc session à chaque exécution.

L’assistant Go harness.AgentConfig active les fournisseurs todo et du mode agent par défaut, en commençant en mode plan. Définissez harness.Config.DisableTodo ou DisableAgentMode pour omettre l’un des deux composants, ou personnalisez les modes via harness.Config.AgentMode.

L’assistant n’ajoute pas automatiquement de bouclage. Configurez explicitement une boucle lorsque l’application doit continuer à exécuter un plan sur plusieurs invocations d’agent. Consultez Agent Harness pour la configuration.

Comportement de session

Utilisez la même session à plusieurs tours. L’état du mode est sauvegardé par session dans les deux kits SDK. L’état des tâches .NET est stocké dans AgentSession.StateBag ; Python utilise TodoSessionStore par défaut, tandis que TodoFileStore ou un TodoStore personnalisé peut externaliser la persistance des tâches.

Changer de mode depuis le code de l’application place en file d’attente une notification unique de changement de mode pour l’exécution suivante. L’outil destiné au modèle mode_set ne place pas cette notification supplémentaire dans la file d’attente, car le modèle a déjà observé son propre appel à l’outil.

La confirmation de plan à exécuter est un comportement au niveau des instructions, et non une demande d’approbation d’outil. Les outils todo et en mode eux-mêmes ne nécessitent pas d’approbation de fonction ; le code d’application peut modifier les modes directement lorsque votre hôte a déjà obtenu l’autorisation requise.

Étapes suivantes

Approfondir la question