Agent Harnais

Créer un assistant harnais

Le package Microsoft.Agents.AI.Harness expose HarnessAgent dans l’espace de noms Microsoft.Agents.AI. Créez-en un à partir d’un IChatClient avec AsHarnessAgentou construisez HarnessAgent directement :

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

Permet HarnessAgentOptions de définir des instructions d’exploitation au niveau du harnais, des instructions spécifiques à l’agent et des options de fonctionnalité :

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 fournit les conseils par défaut sur le harnais. HarnessInstructions apparaît avant ChatOptions.Instructions.

Personnaliser la composition

Les fonctionnalités par défaut ont des options ciblées, notamment DisableTodoProvider, , DisableAgentModeProviderDisableFileMemory, DisableAgentSkillsProviderDisableWebSearch, , DisableToolAutoApproval, DisableOpenTelemetry, et DisableCompaction.

Ajoutez des fournisseurs de contexte personnalisés avec AIContextProviders. Activez l’accès aux fichiers avec FileAccessStore, la délégation en arrière-plan avec BackgroundAgents et l’exécution en boucle avec LoopEvaluators.

Créer un assistant harnais

La fabrique create_harness_agent renvoie un Agent entièrement configuré :

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)

Définissez séparément les instructions spécifiques au niveau du harnais et à l’agent :

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 fournit les conseils par défaut sur le harnais. harness_instructions apparaît avant agent_instructions.

Personnaliser la composition

Désactivez les valeurs par défaut avec des options telles que disable_todo, , disable_mode, disable_file_memorydisable_web_search, , disable_tool_auto_approvalet disable_compaction.

Remplacez les fournisseurs intégrés par todo_provider ou mode_provider, et ajoutez des fournisseurs avec context_providers. Les compétences nécessitent une activation explicite via skills_provider ou skills_paths ; l’accès aux fichiers, les assistants en arrière-plan, les outils interprétateurs de commandes et les boucles nécessitent également une activation explicite.

L’accès aux fichiers utilise le magasin fourni comme espace de travail partagé par défaut. Pour isoler les fichiers par l’ID de session actif, activez l’accès aux fichiers dans l’étendue de la session :

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

Pour le partage intentionnel entre les sessions sélectionnées, construisez FileAccessProvider(store=file_store, scope="tenant-1") directement et ajoutez-le via context_providers. La portée est une clé opaque qui correspond à un dossier géré par le fournisseur, et non pas à un chemin. L’accès limité à l’étendue échoue de manière sécurisée au lieu d’utiliser la racine du magasin partagé lorsqu’aucun ID de session actif ni aucune étendue explicite n’est disponible.

Lorsque l’accès aux fichiers est activé, utilisez file_access_grep cette option pour rechercher des numéros de ligne basés sur 1, file_access_read_lines pour inspecter une plage inclusive et file_access_replace_lines modifier des lignes entières. file_access_read_lines préfixe chaque ligne avec son nombre et un onglet ; omettez ce préfixe lors du passage du texte de ligne en tant que expected_line. Le texte attendu empêche un numéro de ligne obsolète ou incompatible de modifier la ligne incorrecte.

file_access_grep utilise des expressions régulières sans distinction entre majuscules et minuscules, accepte des motifs allant jusqu’à 256 caractères et applique une limite de 10 secondes à l’ensemble de la recherche. Les modèles et recherches non valides ou trop longs qui dépassent le budget retournent une erreur. Limitez le répertoire ou le modèle avant de réessayer.

Le package Go agent/harness assemble les middlewares, les fournisseurs de contexte et les valeurs d’historique par défaut pour un agent normal basé sur un fournisseur. Appelez harness.AgentConfig(harness.Config{}, agent.Config{...}), gérez son erreur et transmettez la configuration retournée au constructeur du fournisseur. Il n’introduit pas de type d’agent distinct ou de boucle d’exécution d’outil.

Créer un assistant harnais

L’exemple composite configure un agent de test basé sur 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.",
        },
    )

Personnaliser la composition

L’assistant active les valeurs par défaut suivantes :

Utilisez harness.Config pour désactiver les composants ou remplacer leur configuration. Désactivez la recherche web hébergée lorsque le service ou le déploiement sélectionné ne le prend pas en charge. Les scripts de compétence basés sur des fichiers nécessitent un moteur d’exécution de scripts explicitement configuré.

L’assistant conserve les outils de l’appelant, les intergiciels, les fournisseurs de contexte et un fournisseur d’historique configuré explicitement. Avec un déploiement de modèle Foundry, utilisez DisableStoreOutput: true lorsque l’historique local gère la conversation.

Les outils de compactage, de bouclage et de shell ne sont pas ajoutés par l’assistant Go. Configurez-les explicitement si nécessaire. Le fournisseur de délégation d’agent en arrière-plan empaqueté décrit dans les autres kits sdk n’est pas disponible dans Go.

Consultez Créer un agent Go harness pour la configuration et le guide de configuration Go harness pour connaître les valeurs par défaut et les remplacements.

L’exemple de point d’entrée .NET est HarnessConsole.RunAgentAsync:

using Harness.Shared.Console;

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

Personnalisez l’exemple avec des observateurs, des formatteurs d’outils, des gestionnaires de commandes et HarnessConsoleOptions. Consultez les exemples .NET Harness.

L’exemple Python utilise le package textuel console en regard des exemples Harness :

from console import run_agent_async

await run_agent_async(agent)

Personnalisez l’exemple avec des observateurs, des formateurs, des commandes et des composants d’interface utilisateur. Consultez les exemples Python Harness.

Le référentiel Go inclut un exemple de banc d’essai composite avec gestion des approbations et une démonstration d’un CLI de chat interactif distincte. La CLI de chat utilise un agent standard ; ce n'est pas l'équivalent de la console Harness C# ou Python.