Agent Harness

Een agent-harnas, ook wel een AI-harnas genoemd, is de runtime-scaffolding waarmee een taalmodel wordt omgezet in een agent die werk kan uitvoeren. Het stuurt model- en toolaanroepen aan, beheert de status van het gesprek en de context, past goedkeuringsbeleidsregels toe en kan ervoor zorgen dat de agent voortgang blijft boeken bij een taak die uit meerdere stappen bestaat.

Agent Framework biedt een geïndeerd, accu-inbegrepen Harness voor onderzoek, codering, gegevensanalyse en ander langlopend werk. U biedt een chatclient en past alleen de mogelijkheden aan die uw toepassing nodig heeft.

Architecture

De Harness stelt bestaande bouwstenen van het Agent Framework samen in plaats van een afzonderlijke agentruntime te definiëren:

  1. Chatclient : verbindt de agent met een model.
  2. Chat-pijplijn — voegt functieaanroepen, berichtinjectie, geschiedenispersistentie per serviceaanroep en optionele compactie toe.
  3. Agent- en contextaanbieders — voeg sessiegebonden instructies, hulpmiddelen, geheugen, de to-dostatus, werkingsmodi en optionele functies toe.
  4. Middleware en decorators — voeg afhandeling van goedkeuringen, observeerbaarheid en optionele begrensde herhaling toe.
  5. Applicatie-UX — streamt reacties, geeft voortgang weer en verzamelt invoer zoals goedkeuringen voor hulpprogramma's.

Het resulterende object blijft een normale Agent Framework-agent: een HarnessAgent agent die is afgeleid van AIAgent in .NET, een Agent geretourneerd door create_harness_agent in Python, of een door een provider ondersteunde *agent.Agent geconfigureerd met harness.AgentConfig in Go. De sessies ervan gebruiken dezelfde abstracties voor sessie en contextprovider als andere agenten.

Mogelijkhedenmatrix benutten

Capability Gedrag van het harnas Canonieke richtlijnen
Functie aanroepen Ingeschakeld met een configureerbare iteratielimiet per aanvraag. Go-providerconstructors beheren de toolaanroeplus. Functiegereedschappen
Persistentie van oproepgeschiedenis per service Slaat de geschiedenis na elke modelaanroep op tijdens een uitvoering met hulpprogramma-aanroepen. Sessies
Verdichting Ingeschakeld wanneer tokenlimieten of een aangepaste strategie worden opgegeven in .NET en Python. Go vereist expliciete providersamenstelling. Compressie
To-do’s bijhouden Standaard ingeschakeld. Planning en todos
Modi voor agents Plan- en uitvoermodi zijn standaard ingeschakeld. Planning en todos
Bestandsopslag en bestandstoegang Geheugen van sessiebestand is standaard ingeschakeld; Gedeelde bestandstoegang is opt-in. Contextproviders
Goedkeuring van tools Permanente goedkeuringen en regels voor automatische goedkeuring zijn standaard ingeschakeld. Goedkeuring van hulpprogramma's
OpenTelemetry De waarneembaarheid van agents is standaard ingeschakeld. Observatievermogen
Zoeken op internet Standaard toegevoegd waar de geselecteerde chatclient deze ondersteunt. Zoeken op internet
Agentvaardigheden Standaard ingeschakeld in .NET en Go; optioneel via een provider of paden in Python. Agentvaardigheden
Achtergrondagenten Optionele parallelle delegering naar benoemde onderliggende agents in .NET en Python. Geen verpakte Go-provider voor achtergrondagent. Achtergrondagenten
Shell-uitvoering Opgebouwd uit het shell-pakket; de Python-factory kan dit automatisch koppelen. Shell-hulpprogramma's
Looping Optioneel beperkt opnieuw aanroepen, gestuurd door evaluatoren of predicaten. Lusvorming van agenten

De achtergrondagentdelegatie staat los van door de provider beheerde achtergrondreacties. Achtergrondagenten voeren onderliggende agents uit voor gedelegeerde taken; achtergrondantwoorden peilen of één provideraanvraag hervatten met behulp van een vervolgtoken.

Tip

Voor richtlijnen voor de coding-agent die helpen een Python-harnastoepassing samen te stellen, installeer agent-framework-builder-python. Deze vaardigheid voor externe coding-agent staat los van de runtimefunctionaliteit Agent Skills die in de matrix wordt vermeld.

Een harness-agent maken

Het Microsoft.Agents.AI.Harness-pakket stelt HarnessAgent beschikbaar in de naamruimte Microsoft.Agents.AI. Maak er een van elke IChatClient met AsHarnessAgent, of construeer rechtstreeks een HarnessAgent:

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

Gebruik HarnessAgentOptions deze optie om bedieningsrichtlijnen op harnasniveau, agentspecifieke instructies en functieopties in te stellen:

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 levert de standaard harnasrichtlijnen. HarnessInstructions wordt weergegeven vóór ChatOptions.Instructions.

De samenstelling aanpassen

Standaardmogelijkheden bevatten gerichte opties, waaronder DisableTodoProvider, DisableAgentModeProvider, DisableFileMemory, DisableAgentSkillsProvider, DisableWebSearch, DisableToolAutoApproval, DisableOpenTelemetry en DisableCompaction.

Aangepaste contextproviders toevoegen met AIContextProviders. Meld u aan voor bestandstoegang met FileAccessStore, achtergronddelegering met BackgroundAgentsen lus met LoopEvaluators.

Een harness-agent maken

De create_harness_agent fabriek retourneert een volledig geconfigureerde Agent:

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)

Stel instructies op harness-niveau en agent-specifieke instructies afzonderlijk in:

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 levert de standaard harnasrichtlijnen. harness_instructions wordt weergegeven vóór agent_instructions.

De samenstelling aanpassen

Schakel standaardwaarden uit met opties zoals disable_todo, disable_mode, disable_file_memory, disable_web_search, disable_tool_auto_approval en disable_compaction.

Vervang ingebouwde providers door todo_provider of mode_provider, en voeg providers toe door context_providers. Vaardigheden zijn opt-in via skills_provider of skills_paths; bestandstoegang, achtergrondagenten, shelltools en herhaalde uitvoering zijn ook opt-in.

Bestandstoegang gebruikt standaard de opgegeven opslag als één gedeelde werkruimte. Als u bestanden wilt isoleren op basis van de actieve sessie-id, schakelt u toegang tot het sessiebereik in:

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

Voor bewust delen tussen geselecteerde sessies maakt u FileAccessProvider(store=file_store, scope="tenant-1") rechtstreeks en voegt u deze toe via context_providers. De scope is een ondoorzichtige sleutel die verwijst naar een door de provider beheerde map, geen pad. Toegang binnen een bereik wordt standaard geweigerd in plaats van de hoofdmap van de gedeelde opslag te gebruiken wanneer er noch een actieve sessie-id noch een expliciet bereik beschikbaar is.

Gebruik tool_name_prefix wanneer één agent meerdere providers voor bestandstoegang heeft. Het voorvoegsel produceert namen zoals workspace_file_access_read en voorkomt naamconflicten van tools. Voor providers met voorvoegsels gebruikt u de providerspecifieke goedkeuringsregelfabrieken, zodat elke regel overeenkomt met de gegenereerde namen van die provider:

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() maakt de equivalente regel voor zowel lees- als schrijftools. Houd schrijftoestemming ingeschakeld, tenzij de opslagafbakening en de invoer van hulpprogramma's worden vertrouwd.

Wanneer bestandstoegang is ingeschakeld, gebruikt u file_access_grep om regelnummers vanaf 1 te zoeken, file_access_read_lines om een inclusief interval te inspecteren en file_access_replace_lines om hele regels te bewerken. file_access_read_lines plaatst voor elke regel het regelnummer en een tab; laat dat voorvoegsel weg wanneer je de regeltekst doorgeeft als expected_line. De verwachte tekst voorkomt dat een verouderd of niet-overeenkomend regelnummer de verkeerde regel bewerkt.

file_access_grep maakt gebruik van hoofdlettergevoelige reguliere expressies, accepteert patronen van maximaal 256 tekens en past een budget van 10 seconden toe op de hele zoekopdracht. Ongeldige of te lange patronen en zoekopdrachten die het budget overschrijden, geven een foutmelding. Beperk de map of het patroon voordat u het opnieuw probeert.

Belangrijk

file_access_grep retourneert overeenkomende regeltekst met de bijbehorende regeleindteken. Een aangepaste AgentFileStore.search() implementatie moet regelnummers op basis van 1 retourneren die dezelfde regels aanpakken als AgentFileStore.split_lines() voor de tekst die wordt geretourneerd door read().

Opmerking

create_harness_agent wordt vrijgegeven. Achtergrondagenten, bestandstoegang en lusfunctionaliteit blijven experimenteel, en shell-hulpmiddelen komen uit het pre-releasepakket agent-framework-tools.

Het Go-pakket agent/harness stelt middleware, contextproviders en geschiedenisstandaarden samen voor een normale agent op basis van een provider. Roep harness.AgentConfig(harness.Config{}, agent.Config{...}) aan, handel de fout af en geef de geretourneerde configuratie door aan de providerconstructor. Er wordt geen afzonderlijk agenttype of een lus voor het uitvoeren van hulpprogramma's geïntroduceerd.

Een harness-agent maken

In het samengestelde voorbeeld wordt een foundry-ondersteunde harness-agent geconfigureerd:

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.",
        },
    )

De samenstelling aanpassen

De helper biedt de volgende standaardinstellingen:

Component Standaard Go harness
Planning Met sessie ondersteunde todo-hulpmiddelen en plan-/executemodi, te beginnen in de planmodus
Bestandsgeheugen Permanente bestanden onder agent-file-memory, met een geïsoleerde werkmap per sessie
Skills Bestandsgestuurde detectie uit de werkmap, met uitzondering van de subboom van het geheugen
Zoeken op internet Een gehoste declaratieverklaring voor zoeken op internet, tenzij de aanroeper er al een heeft opgegeven
Approval Middleware voor doorlopende goedkeuring en automatische goedkeuring voor hulpprogramma's waarvoor goedkeuring is vereist
History Geschiedenis in het geheugen met persistentie per service-aanroep
Berichtinjectie Per agent agent.MessageInjector
Tracing Instrumentatie voor agent-, tool- en ondersteunde modelaanroepen

Gebruik harness.Config om onderdelen uit te schakelen of hun configuratie te overschrijven. Schakel gehoste zoekopdrachten op internet uit wanneer de geselecteerde service of deployment deze niet ondersteunt. Op bestanden gebaseerde scripts voor vaardigheden vereisen een expliciet geconfigureerde scriptrunner.

De helper behoudt aanroeperhulpprogramma's, middleware, contextproviders en een expliciet geconfigureerde geschiedenisprovider. Gebruik bij een Foundry-modelimplementatie DisableStoreOutput: true wanneer de lokale geschiedenis het gesprek beheert.

Hulpprogramma's voor compactie, looping en shell worden niet toegevoegd door de Go-helper. Stel ze expliciet in wanneer dat nodig is. De provider voor delegatie van verpakte achtergrondagenten die in de andere SDK's wordt beschreven, is niet beschikbaar in Go.

Zie Een Go harness-agent maken voor de installatie en de go-harness-configuratiehandleiding voor standaardinstellingen en overschrijvingen.

Voorbeeld van terminal-UX

De Harness schrijft geen toepassingsinterface voor. De repository bevat voorbeeldterminaltoepassingen die uitvoer streamen, taken en de huidige modus weergeven, goedkeuringsverzoeken voor tools tonen en opdrachten bieden zoals /todos, /mode en /exit.

Belangrijk

Deze consoleprojecten zijn voorbeelden, geen frameworkonderdelen die worden verzonden. Gebruik ze als uitvoerbare voorbeelden of als uitgangspunt voor uw eigen terminalervaring.

Het .NET voorbeeldinvoerpunt isHarnessConsole.RunAgentAsync:

using Harness.Shared.Console;

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

Pas het voorbeeld aan met observers, toolformatters, opdrachtverwerkers en HarnessConsoleOptions. Bekijk de .NET Harness-voorbeelden.

Het Python voorbeeld maakt gebruik van het op Tekst gebaseerde console pakket naast de Harness-voorbeelden:

from console import run_agent_async

await run_agent_async(agent)

Pas het voorbeeld aan met waarnemers, formatters, opdrachten en UI-onderdelen. Bekijk de Python Harness-voorbeelden.

De Go-repository bevat een voorbeeld van een samengesteld harnas met goedkeuringsafhandeling en een afzonderlijke interactieve chat CLI-demo. De chat-CLI maakt gebruik van een eenvoudige agent; het is geen equivalent van de C#- of Python Harness-console.

Volgende stappen 

Werk plannen en taken bijhouden

Dieper ingaan

  • Laatst bijgewerkt om