Planificación y tareas pendientes

Dos proveedores de contexto permiten tareas de larga duración:

  • Un proveedor de tareas pendientes almacena elementos de trabajo rastreables y proporciona las herramientas del agente para agregar, completar, quitar e inspeccionarlos.
  • Un proveedor de modo de agente almacena el modo operativo actual y proporciona las herramientas del agente para leerlo o cambiarlo.

Combine estos proveedores directamente cuando solo necesite la planificación, o use Harness Agent para habilitar ambos como parte de su pipeline predeterminado más amplio.

Herramientas de tareas

Los proveedores de .NET y Python exponen las mismas herramientas orientadas al modelo:

Herramienta propósito
todos_add Agregue uno o varios elementos con un título y una descripción opcional.
todos_complete Marque uno o varios elementos completados e incluya un motivo de finalización.
todos_remove Quite los elementos que ya no son pertinentes.
todos_get_remaining Devuelve elementos incompletos.
todos_get_all Devuelve elementos completos e incompletos.

El proveedor inserta la lista de tareas pendientes actual antes de cada ejecución, por lo que el agente puede reanudar el trabajo pendiente.

Modos de planificación y ejecución

AgentModeProvider proporciona los modos plan y execute de forma predeterminada:

  1. El plan es interactivo. El agente analiza los requisitos, crea tareas, hace preguntas de aclaración, presenta un plan y pregunta antes de cambiar de modo.
  2. Execute es autónomo. El agente sigue el plan, toma decisiones razonables cuando los detalles son ambiguos y marca las tareas pendientes como completadas.

El proveedor expone mode_get y mode_set. Sus instrucciones indican al modelo que use mode_set solo cuando el usuario permita explícitamente la transición. Las aplicaciones también pueden cambiar el modo directamente, lo que hace que el proveedor inserte una notificación de cambio de modo en la siguiente ejecución.

Configurar manualmente la planificación y las tareas

Importe y construya los proveedores y agréguelos a través 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();

Personalice los nombres de modo e instrucciones con AgentModeProviderOptions.Modes. El proveedor de tareas pendientes .NET almacena el estado en AgentSession.StateBag. TodoProviderOptions puede reemplazar sus instrucciones, suprimir el mensaje de lista de tareas pendientes insertado o proporcionar un generador de mensajes personalizado.

Las instrucciones predeterminadas plan incluyen escribir el plan en la memoria del archivo. Si el agente compuesto manualmente no proporciona herramientas de memoria de archivos, personalice las instrucciones de modo o agregue un proveedor de memoria adecuado.

Cambiar los modos desde la aplicación

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

Use GetModeAsync para leer el modo actual.

Importe y construya los proveedores; a continuación, agréguelos a un Agent normal:

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 de forma predeterminada. Use TodoFileStore o un personalizado TodoStore cuando el estado de la tarea pendiente se debe almacenar fuera de la carga de la sesión. Personalice los modos con AgentModeProvider(mode_instructions={...}).

Las instrucciones predeterminadas plan incluyen escribir el plan en la memoria del archivo. Si el agente compuesto manualmente no proporciona herramientas de memoria de archivos, personalice mode_instructions o agregue un proveedor de memoria adecuado.

Cambiar modos desde la aplicación

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

Los proveedores incluidos de tipo todo y de modo de agente descritos en esta página no están disponibles por el momento en Go.

Ejecute el plan hasta completarlo manualmente

El seguimiento de tareas pendientes registra el progreso, pero no reinvoca al agente por sí solo. Combínalo con un bucle de agente acotado cuando el modo de ejecución deba continuar hasta que se hayan completado todas las tareas pendientes:

Envuelva el agente compuesto de forma manual con LoopAgent. TodoCompletionLoopEvaluator puede restringir el bucle a los modos seleccionados:

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

Agregue AgentLoopMiddleware al agente normal y use todos_remaining() con un 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,
        )
    ],
)

La integración con bucles controlados por TODO no está disponible actualmente en Go.

Usa la planificación y las tareas pendientes con Harness Agent

Utilice esta configuración si también desea el historial preconfigurado, la memoria, las aprobaciones y el canal de observabilidad del agente de Harness.

HarnessAgent habilita TodoProvider y AgentModeProvider de forma predeterminada. Configure el proveedor de modos y el bucle opcional basado en TODO a través 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();

Establezca DisableTodoProvider o DisableAgentModeProvider para quitar un proveedor predeterminado. Para usar una instancia de TodoProvider configurada, deshabilite el valor predeterminado y añada su instancia mediante AIContextProviders. Puede resolver los proveedores habilitados mediante agent.GetService<TProvider>().

create_harness_agent habilita ambos proveedores de forma predeterminada. Proporcione instancias configuradas para sustituirlas y añada un bucle opcional basado en 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()

Establezca disable_todo o disable_mode para quitar un proveedor predeterminado. El entorno de ejecución de Python activa de forma predeterminada el middleware de aprobación automática de herramientas, por lo que debes pasar session en cada ejecución.

Note

Los proveedores de planificación y tareas de Harness Agent no están disponibles actualmente en Go.

Comportamiento de la sesión

Usa la misma sesión a lo largo de los turnos. El estado del modo se almacena en la sesión en ambos SDK. El estado de las tareas pendientes en .NET se almacena en AgentSession.StateBag; Python usa TodoSessionStore de forma predeterminada, mientras que TodoFileStore o un TodoStore personalizado permiten externalizar la persistencia de las tareas pendientes.

Cambiar el modo desde el código de la aplicación pone en cola una notificación única de cambio de modo para la siguiente ejecución. La herramienta orientada al mode_set modelo no pone en cola esa notificación adicional porque el modelo ya ha observado su propia llamada a herramienta.

La confirmación del plan para ejecutar es un comportamiento de nivel de instrucción, no una solicitud de aprobación de herramientas. Las herramientas «todo» y «mode» no requieren autorización para funciones; el código de la aplicación puede cambiar de modo directamente cuando el host ya ha obtenido el permiso necesario.

Pasos siguientes

Descripción de la composición de Agent Harness

Profundizar un poco más

  • Last updated on