Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Un agent harness, a veces denominado AI harness, es la infraestructura de ejecución que convierte un modelo de lenguaje en un agente capaz de realizar tareas. Impulsa las llamadas al modelo y a las herramientas, gestiona el estado y el contexto de la conversación, aplica políticas de aprobación y puede hacer que el agente siga avanzando en una tarea de varios pasos.
Agent Framework proporciona una estructura con opiniones, baterías incluidas para la investigación, codificación, análisis de datos y otro trabajo de larga duración. Proporciona un cliente de chat y personaliza solo las funcionalidades que necesita la aplicación.
Architecture
Harness se compone de los componentes básicos existentes de Agent Framework en lugar de definir un entorno de ejecución para agentes independiente:
- Cliente de chat : conecta el agente a un modelo.
- Canalización de chat : agrega invocación de funciones, inyección de mensajes, persistencia del historial de llamadas por servicio y compactación opcional.
- Proveedores de agentes y contextos: agregue instrucciones con ámbito de sesión, herramientas, memoria, estado de tareas pendientes, modos operativos y funcionalidades opcionales.
- Middleware y decoradores: añada gestión de aprobaciones, observabilidad e iteración acotada opcional.
- Experiencia del usuario de la aplicación : transmite respuestas, muestra el progreso y recopila entradas como aprobaciones de herramientas.
El objeto resultante sigue siendo un agente normal de Agent Framework: un HarnessAgent que se deriva de AIAgent en .NET, un Agent devuelto por create_harness_agent en Python o un *agent.Agent respaldado por un proveedor configurado con harness.AgentConfig en Go. Sus sesiones usan las mismas abstracciones de sesión y de proveedor de contexto que otros agentes.
Matriz de funcionalidades de Harness
| Capability | Funcionamiento de Harness | Guía canónica |
|---|---|---|
| function_invocation | Habilitado con un límite configurable de iteración por solicitud. Los constructores del proveedor de Go controlan el bucle de invocación de herramientas. | Herramientas de función |
| Persistencia del historial de llamadas por servicio | Conserva el historial después de cada llamada al modelo durante una ejecución con llamadas a herramientas. | Sesiones |
| Compactación | Se habilita cuando se proporcionan límites de token o una estrategia personalizada en .NET y Python. Go requiere composición explícita del proveedor. | Compactación |
| Seguimiento de tareas pendientes | Habilitado de forma predeterminada. | Planificación y tareas pendientes |
| Modos de agente | Los modos de planeamiento y ejecución están habilitados de forma predeterminada. | Planificación y tareas pendientes |
| Memoria de archivos y acceso a archivos | La memoria del archivo de sesión está habilitada de forma predeterminada; el acceso a archivos compartidos es opcional. | Proveedores de contexto |
| Aprobación de herramientas | Las aprobaciones permanentes y las reglas de aprobación automática están habilitadas de forma predeterminada. | Aprobación de herramientas |
| OpenTelemetry | La observabilidad del agente está habilitada de forma predeterminada. | Observabilidad |
| Búsqueda web | Se ha agregado de forma predeterminada donde el cliente de chat seleccionado lo admite. | Búsqueda web |
| Aptitudes del agente | Habilitado de forma predeterminada en .NET y Go; opcional mediante un proveedor o rutas de acceso en Python. | Aptitudes del agente |
| Agentes en segundo plano | Delegación paralela opcional a agentes secundarios nombrados en .NET y Python. No hay ningún proveedor de agente en segundo plano de Go empaquetado. | Agentes en segundo plano |
| Ejecución del shell | Compuesto por el paquete shell; la factoría de Python puede conectarlo automáticamente. | Herramientas de shell |
| Bucle | Reinvocación acotada opcional impulsada por evaluadores o predicados. | Bucle del agente |
La delegación del agente en segundo plano es independiente de las respuestas en segundo plano administradas por el proveedor. Los agentes en segundo plano ejecutan agentes secundarios en tareas delegadas; Las respuestas en segundo plano sondean o reanudan una solicitud de proveedor mediante un token de continuación.
Tip
Para obtener guía para agentes de programación que ayude a crear una aplicación harness de Python, instale agent-framework-builder-python.
Esta aptitud externa de agente de codificación es independiente de la capacidad de aptitudes de agente en tiempo de ejecución que figura en la matriz.
Crear un agente de Harness
El paquete Microsoft.Agents.AI.Harness expone HarnessAgent en el espacio de nombres Microsoft.Agents.AI. Cree uno a partir de cualquiera IChatClient con AsHarnessAgento construya HarnessAgent directamente:
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
AIAgent agent = chatClient.AsHarnessAgent();
AgentResponse response = await agent.RunAsync("Plan a weekend trip to Seattle.");
Console.WriteLine(response.Text);
Utilice HarnessAgentOptions para establecer instrucciones de funcionamiento a nivel del arnés, instrucciones específicas del agente y opciones de funciones:
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
Name = "research-agent",
HarnessInstructions = "Use tools deliberately and report verified results.",
ChatOptions = new ChatOptions
{
Instructions = "You are a research assistant focused on academic sources.",
},
MaxContextWindowTokens = 128_000,
MaxOutputTokens = 16_384,
});
HarnessAgent.DefaultInstructions proporciona la guía de arnés predeterminada.
HarnessInstructions aparece antes de ChatOptions.Instructions.
Personalización de la composición
Las funcionalidades predeterminadas tienen opciones de destino, como DisableTodoProvider, DisableAgentModeProvider, DisableFileMemory, DisableAgentSkillsProviderDisableWebSearch, , DisableToolAutoApproval, y DisableOpenTelemetryDisableCompaction.
Agregue proveedores de contexto personalizados con AIContextProviders. Activa el acceso a archivos con FileAccessStore, la delegación en segundo plano con BackgroundAgents y la repetición en bucle con LoopEvaluators.
Crear un agente de Harness
La create_harness_agent factoría devuelve un Agent totalmente configurado:
from agent_framework import create_harness_agent
from agent_framework.openai import OpenAIChatClient
agent = create_harness_agent(
client=OpenAIChatClient(model="gpt-4o"),
)
session = agent.create_session()
response = await agent.run("Plan a weekend trip to Seattle.", session=session)
print(response.text)
Establezca por separado instrucciones en el nivel del entorno y específicas del agente:
agent = create_harness_agent(
client=client,
name="research-agent",
harness_instructions="Use tools deliberately and report verified results.",
agent_instructions="You are a research assistant focused on academic sources.",
max_context_window_tokens=128_000,
max_output_tokens=16_384,
)
DEFAULT_HARNESS_INSTRUCTIONS proporciona la guía de arnés predeterminada.
harness_instructions aparece antes de agent_instructions.
Personalización de la composición
Deshabilite los valores predeterminados con opciones como disable_todo, disable_mode, disable_file_memory, disable_web_search, disable_tool_auto_approvaly disable_compaction.
Reemplace los proveedores integrados por todo_provider o mode_providery agregue proveedores por context_providers. Las capacidades se activan opcionalmente mediante skills_provider o skills_paths; el acceso a archivos, los agentes en segundo plano, las herramientas del shell y la ejecución en bucle también se activan opcionalmente.
El acceso a archivos usa el almacén proporcionado como un área de trabajo compartida de forma predeterminada. Para aislar los archivos mediante el identificador de sesión activo, habilite el acceso a archivos con ámbito de sesión:
from agent_framework import FileSystemAgentFileStore, create_harness_agent
file_store = FileSystemAgentFileStore("agent-files")
agent = create_harness_agent(
client=client,
file_access_store=file_store,
file_access_session_scoped=True,
)
Para compartir intencionadamente entre sesiones seleccionadas, construya FileAccessProvider(store=file_store, scope="tenant-1") directamente y agréguelo a través de context_providers. El ámbito es una clave opaca que corresponde a una carpeta administrada por el proveedor, no a una ruta. El acceso compartido falla en lugar de usar la raíz del almacén compartido cuando no hay disponible ni un ID de sesión activo ni un ámbito explícito.
Utilice tool_name_prefix cuando un agente tenga varios proveedores de acceso a archivos. El prefijo genera nombres como workspace_file_access_read y evita colisiones de nombres de herramienta. En el caso de los proveedores con prefijo, use las factorías de reglas de aprobación específicas del proveedor para que cada regla coincida con los nombres generados de ese proveedor:
from agent_framework import FileAccessProvider, create_harness_agent
workspace = FileAccessProvider(
store=file_store,
tool_name_prefix="workspace",
)
agent = create_harness_agent(
client=client,
context_providers=[workspace],
auto_approval_rules=[workspace.get_read_only_tools_auto_approval_rule()],
)
get_all_tools_auto_approval_rule() crea la regla equivalente para las herramientas de lectura y escritura. Mantenga habilitada la aprobación de escritura a menos que el límite de almacenamiento y las entradas de herramientas sean de confianza.
Cuando el acceso a archivos está habilitado, use file_access_grep para buscar números de línea basados en 1, file_access_read_lines para inspeccionar un intervalo inclusivo y file_access_replace_lines editar líneas completas.
file_access_read_lines prefijos cada línea con su número y una pestaña; omita ese prefijo al pasar el texto de línea como expected_line. El texto esperado impide que un número de línea obsoleto o no coincidente edite la línea incorrecta.
file_access_grep usa expresiones regulares que no distinguen mayúsculas de minúsculas, acepta patrones de hasta 256 caracteres y aplica un presupuesto de 10 segundos a toda la búsqueda. Los patrones y las búsquedas no válidos o excesivamente largos que exceden el límite devuelven un error. Restrinja el directorio o el patrón antes de volver a intentarlo.
Important
file_access_grep devuelve texto de línea coincidente con su terminador de línea. Una implementación personalizada de AgentFileStore.search() debe devolver números de línea con base 1 que hagan referencia a las mismas líneas que AgentFileStore.split_lines() en el texto devuelto por read().
Note
create_harness_agent se libera. Los agentes en segundo plano, el acceso a archivos y la ejecución en bucle siguen siendo experimentales, y las herramientas de shell provienen del paquete agent-framework-tools en versión preliminar.
El paquete agent/harness de Go ensambla el middleware, los proveedores de contexto y los valores predeterminados del historial para un agente respaldado por un proveedor normal. Llame a harness.AgentConfig(harness.Config{}, agent.Config{...}), controle su error y pase la configuración devuelta al constructor del proveedor. No introduce un tipo de agente distinto ni un bucle de ejecución de herramientas.
Crear un agente de Harness
El ejemplo compuesto configura un agente Harness respaldado por Foundry:
import (
"context"
"fmt"
"os"
"path/filepath"
"github.com/microsoft/agent-framework-go/agent"
"github.com/microsoft/agent-framework-go/agent/harness"
"github.com/microsoft/agent-framework-go/examples/internal/demo"
"github.com/microsoft/agent-framework-go/message"
"github.com/microsoft/agent-framework-go/provider/foundryprovider"
)
workingDirectory, err := os.Getwd()
if err != nil {
return fmt.Errorf("get working directory: %w", err)
}
cfg, err := harness.AgentConfig(harness.Config{WorkingDirectory: workingDirectory}, agent.Config{
Name: "HarnessAssistant",
Middlewares: []agent.Middleware{logger},
})
if err != nil {
return err
}
a := foundryprovider.NewAgent(
demo.FoundryProjectEndpoint,
demo.FoundryTokenCredential(),
foundryprovider.ModelDeployment(demo.FoundryModel),
foundryprovider.AgentConfig{
Config: cfg,
DisableStoreOutput: true,
Instructions: "Help with software engineering tasks. Use memory and todos to track the current session's work.",
},
)
Personalización de la composición
El asistente habilita los valores predeterminados siguientes:
| Componente | Valor predeterminado del arnés de Go |
|---|---|
| Planificación | Herramientas de tareas pendientes respaldadas por sesión y modos de planificación y ejecución, comenzando en modo de planificación |
| Memoria de archivo | Archivos persistentes en agent-file-memory, con una carpeta de trabajo aislada por sesión |
| Aptitudes | Detección respaldada por archivos del directorio de trabajo, excluyendo el subárbol de memoria |
| Búsqueda web | Una declaración de búsqueda web hospedada, a menos que quien llama ya haya proporcionado una. |
| Approval | Middleware de aprobación permanente y aprobación automática para herramientas que requieren aprobación |
| History | Historial en memoria con persistencia por llamada por servicio |
| Inserción de mensajes | Un agent.MessageInjector por agente |
| Tracing | Instrumentación del agente, de las herramientas y de la llamada al modelo compatible |
Utilice harness.Config para deshabilitar componentes o anular su configuración. Deshabilite la búsqueda web hospedada cuando el servicio o la implementación seleccionados no lo admitan. Los scripts de habilidad respaldados por archivos requieren un ejecutor de scripts configurado explícitamente.
El asistente conserva las herramientas del cliente llamante, el middleware, los proveedores de contexto y un proveedor de historial configurado explícitamente. Con una implementación de modelo de Foundry, use DisableStoreOutput: true cuando el historial local sea el propietario de la conversación.
El asistente de Go no añade compactación, bucles ni herramientas de shell. Configúrelos explícitamente cuando sea necesario. El proveedor de delegación de agente en segundo plano empaquetado descrito en los otros SDK no está disponible en Go.
Vea Crear un agente de arnés de Go para la configuración y la guía de configuración del arnés de Go para los valores predeterminados y las sustituciones.
Experiencia del usuario de terminal de ejemplo
Harness no prescribe una interfaz de aplicación. El repositorio incluye aplicaciones de ejemplo para terminal que muestran la salida en tiempo real, las tareas pendientes y el modo actual, muestran solicitudes de aprobación de herramientas y proporcionan comandos como /todos, /mode y /exit.
Important
Estos proyectos de consola son ejemplos, no componentes de marco enviados. Úselos como ejemplos ejecutables o como punto de partida para su propia experiencia de terminal.
El punto de entrada de ejemplo .NET es HarnessConsole.RunAgentAsync:
using Harness.Shared.Console;
await HarnessConsole.RunAgentAsync(
agent,
userPrompt: "Ask me anything to get started.");
Personalice el ejemplo con observadores, formateadores de herramientas, controladores de comandos y HarnessConsoleOptions. Consulte los ejemplos de .NET Harness.
En el ejemplo de Python se usa el paquete basado en console texto junto a los ejemplos de Harness:
from console import run_agent_async
await run_agent_async(agent)
Personalice el ejemplo con observadores, formateadores, comandos y componentes de interfaz de usuario. Consulte los ejemplos de Python Harness.
El repositorio de Go incluye un ejemplo de entorno de prueba compuesto con control de aprobación y una demostración independiente de la CLI de chat interactivo. La CLI de chat usa un agente simple; no es un equivalente de la consola de C# o Python Harness.