Arneses de agentes

Creación de un agente de prueba

El agente de prueba se expone como la clase HarnessAgent en el espacio de nombres Microsoft.Agents.AI (el paquete Microsoft.Agents.AI.Harness). La forma más sencilla de crear una es a partir de cualquier IChatClient utilizando el método de extensión AsHarnessAgent:

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

// chatClient is any IChatClient implementation (Foundry, Azure OpenAI, OpenAI, Anthropic, ...).
AIAgent agent = chatClient.AsHarnessAgent();

AgentResponse response = await agent.RunAsync("Plan a weekend trip to Seattle.");
Console.WriteLine(response.Text);

También puede crear el agente directamente:

AIAgent agent = new HarnessAgent(chatClient);

Proporcionar un HarnessAgentOptions para suministrar instrucciones y herramientas. Las instrucciones a nivel de arnés (HarnessAgentOptions.HarnessInstructions) describen las instrucciones generales de funcionamiento, mientras que las instrucciones específicas de la tarea se incluyen en ChatOptions.Instructions. El HarnessAgent viene con instrucciones predeterminadas a nivel del entorno de ejecución (HarnessAgent.DefaultInstructions), pero puedes sustituirlas por las tuyas mediante HarnessAgentOptions.HarnessInstructions.

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    Name = "research-agent",
    ChatOptions = new ChatOptions
    {
        Instructions = "You are a research assistant focused on academic sources.",
        Tools = [AIFunctionFactory.Create(GetStockPrice)],
    },
});

Activación de la compactación

La compactación impide que los bucles largos de llamadas a herramientas desborden la ventana de contexto. Cuando no se utiliza el historial de chat almacenado en el servicio de inferencia, al InMemoryChatHistoryProvider predeterminado también se le proporciona el mismo proveedor de compactación, de modo que el historial de chat almacenado en la sesión también se compacte. Especifique un tamaño máximo de ventana de contexto y un tamaño máximo de salida para habilitar la estrategia predeterminada que tiene en cuenta el presupuesto de tokens:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    MaxContextWindowTokens = 128_000,
    MaxOutputTokens = 16_384,
});

Para usar su propia estrategia, establezca HarnessAgentOptions.CompactionStrategy; para desactivar la compactación, establezca DisableCompaction = true.

Personalización y deshabilitación de características

Cada funcionalidad predeterminada tiene una marca de deshabilitación correspondiente en HarnessAgentOptions, por lo que puede mantener la canalización que desee y quitar el resto:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    HarnessInstructions = "Custom operating guidelines here.",
    DisableTodoProvider = true,      // No todo list
    DisableAgentModeProvider = true, // No plan/execute modes
    DisableWebSearch = true,         // No hosted web search tool
    DisableFileMemory = true,        // No file-based session memory
});

Otras marcas incluyen DisableFileAccess, DisableAgentSkillsProvider, DisableToolAutoApprovaly DisableOpenTelemetry. También puede añadir sus propios proveedores de contexto a través de AIContextProviders y configurar el proveedor de aptitudes para que apunte a ubicaciones personalizadas a través de AgentSkillsSource.

Repitiendo hasta terminar

Por defecto, el agente de prueba se ejecuta una vez por invocación. Proporcione una o varias LoopEvaluator instancias para volver a invocar el agente automáticamente hasta que los evaluadores decidan que finaliza (por ejemplo, cuando aparece un marcador de finalización, se cumple un predicado o un juez de IA aprueba):

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    LoopEvaluators = [new CompletionMarkerLoopEvaluator("DONE")],
});

El bucle se aplica como el decorador de agente más externo, por lo que cada iteración es una ejecución completa del agente, aprobada de forma independiente por la herramienta y con seguimiento.

Shell y agentes en segundo plano

Para permitir que el agente ejecute comandos de shell, pase un ShellExecutor. Esto añade una herramienta de ejecución de shell sujeta a aprobación y un proveedor que inyecta en el contexto información sobre el sistema operativo, el shell y el directorio de trabajo:

using Microsoft.Agents.AI.Tools.Shell;

// A shell confined to a working directory. Commands require approval by default;
// the deny-list is a UX pre-filter, not a security boundary.
await using var shell = new LocalShellExecutor(new LocalShellExecutorOptions
{
    WorkingDirectory = workingDir,
    ConfineWorkingDirectory = true,
    Policy = new ShellPolicy(denyList: [@"\brm\s+-rf\b", @"\bsudo\b"]),
});

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    ShellExecutor = shell,
});

Para habilitar la delegación paralela, pase un conjunto de agentes en segundo plano. El agente puede entregar subtareas para la ejecución simultánea:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    BackgroundAgents = [webSearchAgent, codeAgent],
});

Creación de un agente de prueba

El harness se expone como la función de fábrica create_harness_agent, que ensambla un Agent totalmente configurado a partir de un cliente de chat. El formulario más sencillo solo requiere un cliente:

from agent_framework import create_harness_agent
from agent_framework.openai import OpenAIChatClient

agent = create_harness_agent(
    OpenAIChatClient(model="gpt-4o"),
)

session = agent.create_session()
response = await agent.run("Plan a weekend trip to Seattle.", session=session)
print(response.text)

Las instrucciones a nivel del harness describen las directrices generales de funcionamiento, mientras que las instrucciones específicas de cada tarea se incluyen en agent_instructions. El harness se suministra con instrucciones predeterminadas a nivel del harness (DEFAULT_HARNESS_INSTRUCTIONS), que puedes anular mediante harness_instructions. También puede pasar herramientas adicionales:

agent = create_harness_agent(
    client=client,
    name="research-agent",
    agent_instructions="You are a research assistant focused on academic sources.",
    tools=get_stock_price,
)

Activación de la compactación

La compactación impide que los bucles largos de llamadas a herramientas desborden la ventana de contexto. Proporcione el tamaño máximo de ventana de contexto del modelo y un tamaño de salida máximo para habilitar las estrategias predeterminadas compatibles con el presupuesto del token:

agent = create_harness_agent(
    client=client,
    max_context_window_tokens=128_000,
    max_output_tokens=16_384,
)

Cuando no se proporciona ningún parámetro de token ni una estrategia personalizada, la compactación se deshabilita automáticamente. Para usar tus propias estrategias, pasa before_compaction_strategy y/o after_compaction_strategy; para desactivar explícitamente la compactación, establece disable_compaction=True.

Personalización y deshabilitación de características

Cada funcionalidad predeterminada tiene un argumento de palabra clave correspondiente disable_* , por lo que puede mantener las partes que desee y quitar el resto:

agent = create_harness_agent(
    client=client,
    harness_instructions="Custom operating guidelines here.",
    disable_todo=True,         # No todo list
    disable_mode=True,         # No plan/execute modes
    disable_web_search=True,   # No hosted web search tool
    disable_file_memory=True,  # No file-based session memory
)

Otras marcas incluyen disable_file_access, disable_tool_auto_approvaly disable_compaction. Puede apuntar la detección de aptitudes en ubicaciones personalizadas con skills_paths y agregar sus propios proveedores con context_providers.

Repitiendo hasta terminar

Por defecto, el agente de prueba se ejecuta una vez por invocación. Pase un predicado loop_should_continue para invocar de nuevo al agente automáticamente hasta que el predicado determine que ha finalizado. Utiliza loop_next_message para controlar el mensaje de solicitud de cada iteración de seguimiento y loop_max_iterations para limitar el número de pasadas:

from agent_framework import create_harness_agent, todos_remaining

agent = create_harness_agent(
    client=client,
    loop_should_continue=todos_remaining(),
    loop_max_iterations=10,
)

El predicado se invoca con argumentos de palabra clave (iteration, last_result, session, agent y así sucesivamente); todos_remaining ejecuta de nuevo el agente mientras su lista de tareas aún tiene elementos pendientes. Para escribir las tuyas propias, acepta esos argumentos clave; por ejemplo, lambda *, last_result, **kwargs: "DONE" not in last_result.text.

Shell y agentes en segundo plano

Para permitir que el agente ejecute comandos de shell, pase un shell_executor (por ejemplo, LocalShellTool de agent-framework-tools). Esto añade una herramienta de ejecución de comandos en el shell sujeta a aprobación y un proveedor que detecta el sistema operativo y el entorno del shell. El llamante es responsable del ciclo de vida del ejecutor:

from agent_framework_tools.shell import LocalShellTool, ShellPolicy

# A shell confined to a working directory. Commands require approval by default;
# the deny-list is a UX pre-filter, not a security boundary.
async with LocalShellTool(
    workdir="./working",
    confine_workdir=True,
    policy=ShellPolicy(denylist=[r"\brm\s+-rf\b", r"\bsudo\b"]),
) as shell:
    agent = create_harness_agent(
        client=client,
        shell_executor=shell,
    )

Para habilitar la delegación en paralelo, pasa una secuencia de agentes en segundo plano. El agente puede entregar subtareas para la ejecución simultánea:

agent = create_harness_agent(
    client=client,
    background_agents=[web_search_agent, code_agent],
)

El proyecto Harness.Shared.Console es la consola de ejemplo de .NET. Su punto de entrada es HarnessConsole.RunAgentAsync, que toma tu agente, un indicador de lugar reservado y un HarnessConsoleOptions opcional (observadores, controladores de comandos con barra, colores de modo):

using Harness.Shared.Console;

await HarnessConsole.RunAgentAsync(agent, userPrompt: "Ask me anything to get started.");

Personalízalo con tus propios observadores, formateadores de herramientas y controladores de comandos, o haz un fork del mismo como base para tu propia experiencia de terminal. Consulte los ejemplos de arnés de .NET.

La consola de ejemplo en Python es el paquete console que se encuentra junto a los ejemplos del entorno de pruebas. Su punto de entrada es run_agent_async, que ejecuta una aplicación basada en texto:

from console import run_agent_async

await run_agent_async(agent)

Se organiza en torno a observadores, componentes de interfaz de usuario y comandos de barra, todos ampliables mediante las clases base ConsoleObserver, ToolCallFormatter y CommandHandler (depende de textual y rich). Ejecútalo tal cual o cópialo como base para crear tu propia experiencia de terminal. Consulte los ejemplos de arnés de Python.