Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Een agent-harnas is de scaffolding waarmee een taalmodel wordt omgezet in een agent die daadwerkelijk dingen kan doen . Een model kan alleen tekst genereren. Als u hulpprogramma's wilt aanroepen, voert u taken met meerdere stappen uit, onthoudt u wat de taak heeft gedaan en gaat u door totdat de taak is voltooid, hebt u een runtime nodig rond het model en die runtime is het harnas.
Een harnas drijft de agent aan: het voert de lus uit die het model aanroept en voert de hulpprogramma's uit die het model vraagt, beheert de gespreksgeschiedenis en context, zodat het model binnen de grenzen blijft, goedkeurings- en veiligheidsbeleid toepast voordat er acties worden ondernomen en de agent wordt voortgezet totdat de taak is voltooid. Codeassistenten en autonome agents zijn allemaal gebouwd op een vorm van harnas. Het is de motor die rond het model wordt verpakt.
Agent Framework biedt een kant-en-klare harnas, zodat u deze scaffolding niet zelf hoeft te bouwen. Het is een eigenzinnige, compleet uitgeruste agent die een chatclient omhult met een volledige agentpipeline — functieaanroepen, contextbeheer en een zorgvuldig samengestelde set tools en providers — afgestemd op langdurig, autonoom werk zoals onderzoek, programmeren, data-analyse en algemene taakautomatisering.
U levert nog steeds uw eigen chatclient en configureert alleen de onderdelen die u wilt wijzigen. Alles anders heeft een verstandige standaardwaarde die u kunt uitschakelen of aanpassen.
Intern is de Agent Framework harness een op een chatclient gebaseerde agent (Agent in Python en ChatClientAgent in C#), waaraan een aantal Agent Framework-functies is toegevoegd. Al deze functies zijn ook beschikbaar als zelfstandige functies in Agent Framework.
Wat vormt de Agent Framework-harnas
Het Agent Framework brengt de volgende mogelijkheden samen in één agent. Elke optie is standaard ingeschakeld (tenzij vermeld als optioneel) en kan afzonderlijk worden uitgeschakeld of aangepast.
| Vermogen | Description |
|---|---|
| Functie aanroepen | Automatische lus voor het aanroepen van hulpprogramma's met een configureerbare iteratielimiet. |
| Persistentie van oproepgeschiedenis per service | Chatgeschiedenis blijft behouden na elke afzonderlijke modelaanroep, waardoor crashherstel en inspectie halverwege de uitvoering mogelijk zijn. |
| Compressie | Compactie van het contextvenster voorkomt dat lange toolaanroeplussen het contextvenster overschrijden. Actief wanneer een tokenbudget (of een aangepaste strategie) wordt opgegeven. |
| Todo-provider | Een permanente takenlijst die de agent gebruikt om plannen met meerdere stappen bij te houden. |
| Aanbieder van agentmodus | Registratie van de modi Plannen/Uitvoeren/Aangepast waarmee wordt gestructureerd hoe de agent werkt. |
| Provider voor bestandsgeheugen | Bestandsgebaseerd sessiegeheugen voor notities en artefacten die tussen interacties bewaard blijven. |
| Bestandstoegangsprovider | Lees-/schrijfhulpprogramma's beperkt tot een werkmap. |
| Goedkeuring van hulpprogramma's | "Niet opnieuw vragen" staande goedkeuringsregels plus heuristische automatische goedkeuring voor veilige, onbeheerde uitvoering. |
| OpenTelemetry | Ingebouwde waarneembaarheid volgens de semantische ai-conventies. |
| Zoeken op internet | Een gehost hulpprogramma voor zoeken op internet is standaard toegevoegd. |
| Leverancier van vaardigheden(optioneel) | Detecteert en laadt agentvaardigheden geleidelijk vanuit het bestandssysteem. |
| Achtergrondagents(optioneel) | Parallel werk delegeren aan subagents op de achtergrond. |
| Shell-omgeving(optioneel) | Uitvoering van Shell-opdrachten plus OS/shell/working-directory-testen. |
| Herhalen(optioneel) | Roep de agent opnieuw aan totdat aan een voltooiingsvoorwaarde is voldaan. |
Een harness-agent maken
De harnas wordt weergegeven als de HarnessAgent klasse in de Microsoft.Agents.AI naamruimte (het Microsoft.Agents.AI.Harness pakket). De eenvoudigste manier om er een te maken, is vanuit een willekeurige IChatClient met behulp van de extensiemethode 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);
U kunt de agent ook rechtstreeks samenstellen:
AIAgent agent = new HarnessAgent(chatClient);
Geef een HarnessAgentOptions op om instructies en hulpmiddelen te bieden. Instructies op harnessniveau (HarnessAgentOptions.HarnessInstructions) beschrijven algemene bedieningsrichtlijnen, terwijl taakspecifieke instructies op ChatOptions.Instructions staan.
De HarnessAgent wordt geleverd met standaard instructies op harness-niveau (HarnessAgent.DefaultInstructions), maar u kunt deze vervangen door uw eigen instructies via 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)],
},
});
Compactie inschakelen
Compactie voorkomt dat lange lussen voor het aanroepen van tools het contextvenster overschrijden.
Wanneer u geen door de inferenceservice opgeslagen chatgeschiedenis gebruikt, krijgt ook InMemoryChatHistoryProvider dezelfde compactieprovider, zodat ook de in de sessie opgeslagen chatgeschiedenis wordt gecompacteerd.
Geef zowel een maximale contextvenstergrootte als een maximale uitvoergrootte op om de standaardstrategie voor tokenbudgetbewust in te schakelen:
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
MaxContextWindowTokens = 128_000,
MaxOutputTokens = 16_384,
});
Als u uw eigen strategie wilt gebruiken, stelt u HarnessAgentOptions.CompactionStrategyin; om compressie uit te schakelen, in te stellen DisableCompaction = true.
Functies aanpassen en uitschakelen
Elke standaardfunctionaliteit heeft op HarnessAgentOptions een bijbehorende vlag om deze uit te schakelen, zodat u de gewenste pipeline kunt behouden en de rest kunt weglaten:
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
});
Andere vlaggen zijn onder andere DisableFileAccess, DisableAgentSkillsProvider, DisableToolAutoApprovalen DisableOpenTelemetry. U kunt ook uw eigen contextproviders toevoegen via AIContextProviders en verwijzen naar de vaardighedenprovider op aangepaste locaties via AgentSkillsSource.
Herhalen totdat u klaar bent
Standaard wordt het testharnas één keer per aanroep uitgevoerd. Geef een of meer LoopEvaluator instanties op om de agent automatisch opnieuw aan te roepen totdat de evaluators besluiten dat deze is voltooid (bijvoorbeeld wanneer een voltooiingsmarkering wordt weergegeven, een predicaat wordt voldaan of een AI-rechter goedkeurt):
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
LoopEvaluators = [new CompletionMarkerLoopEvaluator("DONE")],
});
De lus wordt ingezet als de buitenste Agent-decorator, zodat elke iteratie een volledige, onafhankelijk door tools goedgekeurde en getraceerde uitvoering van de agent is.
Shell en achtergrondagenten
Als u de agent shell-opdrachten wilt laten uitvoeren, geeft u een ShellExecutor. Hiermee wordt een hulpprogramma voor shelluitvoering waarvoor goedkeuring is vereist toegevoegd, evenals een provider die informatie over het besturingssysteem, de shell en de werkmap aan de context toevoegt:
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,
});
Als u parallelle delegering wilt inschakelen, geeft u een set achtergrondagents door. De agent kan subtaken overdragen voor gelijktijdige uitvoering:
AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
BackgroundAgents = [webSearchAgent, codeAgent],
});
Een harness-agent maken
De harnas wordt weergegeven als de create_harness_agent fabrieksfunctie, die een volledig geconfigureerde Agent client van een chatclient samenstelt. Voor het eenvoudigste formulier is alleen een client vereist:
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)
Instructies op harness-niveau beschrijven algemene bedieningsrichtlijnen, terwijl taakspecifieke instructies in agent_instructions worden geplaatst. De harness wordt geleverd met standaardinstructies op harnessniveau (DEFAULT_HARNESS_INSTRUCTIONS), die u kunt overschrijven via harness_instructions. U kunt ook extra hulpmiddelen doorgeven:
agent = create_harness_agent(
client=client,
name="research-agent",
agent_instructions="You are a research assistant focused on academic sources.",
tools=get_stock_price,
)
Compactie inschakelen
Compactie voorkomt dat lange lussen voor het aanroepen van tools het contextvenster overschrijden. Geef zowel de maximale contextvenstergrootte als de maximale uitvoergrootte van het model op om de standaardstrategieën voor tokenbudget in te schakelen:
agent = create_harness_agent(
client=client,
max_context_window_tokens=128_000,
max_output_tokens=16_384,
)
Wanneer geen tokenparameter of een aangepaste strategie wordt opgegeven, wordt compressie automatisch uitgeschakeld. Als u uw eigen strategieën wilt gebruiken, geeft u door before_compaction_strategy en/of after_compaction_strategy; om compressie expliciet uit te schakelen, stelt u in disable_compaction=True.
Functies aanpassen en uitschakelen
Elke standaardmogelijkheid heeft een bijbehorend disable_* trefwoordargument, zodat u de gewenste onderdelen kunt behouden en de rest kunt verwijderen:
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
)
Andere vlaggen zijn onder andere disable_file_access, disable_tool_auto_approvalen disable_compaction. U kunt vaardigheidsdetectie aanwijzen op aangepaste locaties met skills_paths en uw eigen providers toevoegen met context_providers.
Herhalen totdat u klaar bent
Standaard wordt het testharnas één keer per aanroep uitgevoerd. Geef een loop_should_continue predicaat door om de agent automatisch opnieuw aan te roepen totdat het predicaat besluit dat deze is voltooid. Gebruik loop_next_message dit om de prompt voor elke opvolgingsiteratie te bepalen en loop_max_iterations om het aantal geslaagden te bepalen:
from agent_framework import create_harness_agent, todos_remaining
agent = create_harness_agent(
client=client,
loop_should_continue=todos_remaining(),
loop_max_iterations=10,
)
Het predicaat wordt aangeroepen met trefwoordargumenten (iteration, last_result, session, agent, enzovoort); todos_remaining start de agent opnieuw terwijl de takenlijst nog steeds openstaande items bevat. Als u uw eigen argumenten wilt schrijven, accepteert u deze trefwoordargumenten, bijvoorbeeld lambda *, last_result, **kwargs: "DONE" not in last_result.text.
Shell en achtergrondagenten
Als u de agent shell-opdrachten wilt laten uitvoeren, geeft u een shell_executor (bijvoorbeeld LocalShellTool van agent-framework-tools). Hiermee voegt u een shell-uitvoeringsprogramma met goedkeuringspoort toe plus een provider waarmee het besturingssysteem en de shell-omgeving worden gecontroleerd. De beller is eigenaar van de levenscyclus van de uitvoerder:
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,
)
Als u parallelle delegering wilt inschakelen, geeft u een reeks achtergrondagents door. De agent kan subtaken overdragen voor gelijktijdige uitvoering:
agent = create_harness_agent(
client=client,
background_agents=[web_search_agent, code_agent],
)
Note
Go-ondersteuning voor agent-harnas is binnenkort beschikbaar. Zie de opslagplaats Agent Framework Go voor de meest recente status.
Werkstroom plannen en uitvoeren
De provider van de agentmodus maakt een tweefasige werkstijl mogelijk die op natuurlijke wijze overeenkomt met de takenlijst:
- Planmodus : interactief. De agent stelt verduidelijkingsvragen, ontwerpt een takenlijst en plan en krijgt uw goedkeuring voordat u aanzienlijk werk doet.
- Uitvoeringsmodus : autonoom. De agent werkt de taken zelfstandig af en rapporteert onderweg over de voortgang.
Hoewel de modusprovider wordt geleverd met plan- en uitvoermodi als de standaardmodi, kunnen deze worden vervangen door andere modi en aangepaste instructies voor elke modus, indien nodig.
Een voorbeeldterminal-UX
Het harnas geeft u een geschikte agent, maar schrijft niet voor hoe mensen ermee communiceren. Om de testomgeving van begin tot eind te demonstreren, hebben we een voorbeeld van een terminalinterface opgenomen — een interactieve console (TUI) die de uitvoer van de agent streamt, de takenlijst en de huidige modus toont, goedkeuringsverzoeken voor tools toont en slash-opdrachten zoals /todos, /mode en /exit ondersteunt.
Important
Deze consoleprojecten zijn voorbeelden, geen onderdeel van het verzonden framework. Ze zijn opzettelijk zelfstandig opgezet, zodat u ze ongewijzigd kunt uitvoeren om de testomgeving te verkennen, of ze naar uw eigen project kunt kopiëren als uitgangspunt voor het bouwen van uw eigen terminalomgeving.
De .NET voorbeeldconsole is het Harness.Shared.Console project. Het ingangspunt is HarnessConsole.RunAgentAsync, waarbij uw agent, een tijdelijke aanduidingsprompt en een optionele HarnessConsoleOptions (waarnemers, slash-command handlers, moduskleuren) wordt gebruikt:
using Harness.Shared.Console;
await HarnessConsole.RunAgentAsync(agent, userPrompt: "Ask me anything to get started.");
Pas het aan met je eigen observers, toolformatters en opdrachtverwerkers — of maak er een fork van als basis voor je eigen terminalomgeving. Bekijk de .NET harnasvoorbeelden.
De Python voorbeeldconsole is het console pakket naast de harnasvoorbeelden. Het toegangspunt is run_agent_async, waarmee een op tekst gebaseerde app wordt uitgevoerd:
from console import run_agent_async
await run_agent_async(agent)
Het is georganiseerd rond waarnemers, UI-onderdelen en slash-opdrachten, allemaal uitbreidbaar via de ConsoleObserver, ToolCallFormatteren CommandHandler basisklassen (afhankelijk van textual en rich). Voer het uit zoals het is, of kopieer het als basis voor je eigen terminalervaring. Bekijk de Python harnasvoorbeelden.