Agentramverk

Ett agentramverk är det ramverk som förvandlar en språkmodell till en agent som faktiskt kan göra saker. En modell på egen hand kan bara generera text. För att få den att anropa verktyg, utföra uppgifter i flera steg, komma ihåg vad den har gjort och fortsätta tills uppgiften är slutförd behöver du en körmiljö som omger modellen – och den körmiljön är ramverket.

En sele driver agenten: den kör loopen som anropar modellen och kör de verktyg som modellen ber om, hanterar konversationshistorik och kontext så att modellen håller sig inom sina gränser, tillämpar godkännande- och säkerhetsprinciper innan åtgärder vidtas och håller agenten på väg mot slutförd uppgift. Kodningsassistenter och autonoma agenter är alla byggda på någon form av sele – det är motorn lindad runt modellen.

Agent Framework tillhandahåller en färdig sele så att du inte behöver skapa den här byggnadsställningen själv. Det är en åsiktsbaserad, batteriindelad agent som omsluter en chattklient med en komplett agentisk pipeline – funktionsanrop, kontexthantering och en kuraterad uppsättning verktyg och leverantörer – anpassad för långvarigt, autonomt arbete som forskning, kodning, dataanalys och allmän uppgiftsautomatisering.

Du anger fortfarande din egen chattklient och konfigurerar bara de delar som du vill ändra. Allt annat har en lämplig standard som du kan inaktivera eller anpassa.

Internt är Agent Framework-sele en chattklientbaserad agent (Agent i Python och ChatClientAgent i C#) med en uppsättning Agent Framework-funktioner tillagda. Alla dessa funktioner är också tillgängliga som fristående funktioner i Agent Framework.

Vad utgör Agent Framework-selen

Agent Framework-harnesket samlar följande funktioner i en enda agent. Var och en är aktiverad som standard (om det inte anges som valfritt) och kan inaktiveras eller anpassas individuellt.

Capability Beskrivning
Funktionsanrop Automatisk verktygsanropsloop med en konfigurerbar iterationsgräns.
Beständig lagring av historik per tjänstanrop Chatthistoriken lagras efter varje enskilt modellanrop, vilket möjliggör återställning efter krascher och granskning under körning.
Komprimering Komprimering av kontextfönster hindrar långa knappanropsloopar från att flöda över kontextfönstret. Aktiv när en tokenbudget (eller en anpassad strategi) tillhandahålls.
Att göra-provider En beständig att göra-lista som agenten använder för att spåra planer i flera steg.
Leverantör för agentläge Spårning för planerings-, körnings- och anpassat läge som strukturerar hur agenten arbetar.
Provider för filminne Filbaserat sessionsminne för anteckningar och artefakter som bevaras mellan svängar.
Filåtkomstprovider Läs-/skrivfilverktyg som är begränsade till en arbetskatalog.
Godkännande av verktyg "Fråga inte igen" stående godkännanderegler plus heuristiskt automatiskt godkännande för säker, obevakad körning.
OpenTelemetry Inbyggd observabilitet enligt de semantiska konventionerna för generativ AI.
Webbsökning Ett värdbaserat webbsökningsverktyg har lagts till som standard.
Kompetensprovider(valfritt) Identifierar och läser in agentkunskaper progressivt från filsystemet.
Bakgrundsagenter(valfritt) Delegera parallellt arbete till underagenter i bakgrunden.
Shell-miljö(valfritt) Shell-kommandokörning plus OS/shell/working-directory-avsökning.
Looping(valfritt) Anropa agenten igen tills ett slutförandevillkor är uppfyllt.

Skapa en harness-agent

Verktyget är exponerat som klassen HarnessAgent i namnområdet Microsoft.Agents.AI (paketet Microsoft.Agents.AI.Harness). Det enklaste sättet att skapa en är från någon IChatClient som använder AsHarnessAgent tilläggsmetoden:

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

Du kan också skapa agenten direkt:

AIAgent agent = new HarnessAgent(chatClient);

Ange a HarnessAgentOptions för att tillhandahålla instruktioner och verktyg. Instruktioner på sele-nivå (HarnessAgentOptions.HarnessInstructions) beskriver allmänna riktlinjer för användning, medan uppgiftsspecifika instruktioner ska anges på ChatOptions.Instructions. HarnessAgent levereras med standardinstruktioner på harness-nivå (HarnessAgent.DefaultInstructions), men du kan åsidosätta dem med egna 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)],
    },
});

Aktivering av komprimering

Kompaktering förhindrar att långa loopar med verktygsanrop överskrider kontextfönstret. När du inte använder chatthistorik som lagras av inferenstjänsten får standard-InMemoryChatHistoryProvider också samma provider för komprimering, så att även sessionslagrad chatthistorik komprimeras. Ange både en maximal storlek för kontextfönster och en maximal utdatastorlek för att aktivera standardstrategin token-budget-aware:

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

Om du vill använda din egen strategi anger du HarnessAgentOptions.CompactionStrategy; för att inaktivera komprimering anger du DisableCompaction = true.

Anpassa och inaktivera funktioner

Varje standardfunktion har en motsvarande inaktivera-flagga på HarnessAgentOptions, så att du kan behålla den pipeline du vill ha och släppa resten:

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

Andra flaggor är DisableFileAccess, DisableAgentSkillsProvider, DisableToolAutoApprovaloch DisableOpenTelemetry. Du kan också lägga till egna kontextleverantörer via AIContextProviders och peka kompetensprovidern på anpassade platser via AgentSkillsSource.

Upprepa tills det är färdigt

Som standard körs selen en gång per anrop. Ange en eller flera LoopEvaluator instanser för att anropa agenten automatiskt tills utvärderarna bestämmer sig för att den är klar (till exempel när en slutförandemarkör visas, ett predikat uppfylls eller en AI-domare godkänner):

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

Loopen tillämpas som den yttersta agentdekoratören, så varje iteration är en fullständig, oberoende verktygsgodkänd och spårad agentkörning.

Skal- och bakgrundsagenter

Om du vill låta agenten köra gränssnittskommandon skickar du en ShellExecutor. Detta lägger till ett verktyg för skalexekvering som kräver godkännande och en komponent som injicerar information om operativsystem, skal och arbetskatalog i kontexten:

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

För att aktivera parallell delegering anger du en uppsättning bakgrundsagenter. Agenten kan delegera deluppgifter för samtidig exekvering:

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

Skapa en harness-agent

Harnessen exponeras som fabriksfunktionen create_harness_agent, som sätter samman en fullständigt konfigurerad Agent från en chattklient. Det enklaste formuläret kräver endast en klient:

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)

Instruktioner på selenivå beskriver allmänna riktlinjer för drift medan uppgiftsspecifika instruktioner finns i agent_instructions. Selen levereras med standardinstruktioner på selenivå (DEFAULT_HARNESS_INSTRUCTIONS), som du kan åsidosätta via harness_instructions. Du kan också skicka extra verktyg:

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

Aktivering av komprimering

Kompaktering förhindrar att långa loopar med verktygsanrop överskrider kontextfönstret. Ange både modellens maximala kontextfönsterstorlek och en maximal storlek på utdata för att möjliggöra de förvalda strategierna som tar hänsyn till tokenbudgeten:

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

När varken tokenparametern eller en anpassad strategi tillhandahålls inaktiveras komprimering automatiskt. Om du vill använda dina egna strategier, ange before_compaction_strategy och/eller after_compaction_strategy; för att uttryckligen inaktivera komprimering anger du disable_compaction=True.

Anpassa och inaktivera funktioner

Varje standardfunktion har ett motsvarande disable_* nyckelordsargument, så att du kan behålla de delar du vill ha och släppa resten:

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
)

Andra flaggor är disable_file_access, disable_tool_auto_approvaloch disable_compaction. Du kan rikta identifiering av färdigheter mot anpassade platser med skills_paths och lägga till egna leverantörer med context_providers.

Upprepa tills det är färdigt

Som standard körs selen en gång per anrop. Skicka ett loop_should_continue predikat för att automatiskt anropa agenten igen tills predikatet avgör att det är klart. Använd loop_next_message för att styra prompten för varje uppföljande iteration och loop_max_iterations begränsa antalet pass:

from agent_framework import create_harness_agent, todos_remaining

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

Predikatet anropas med nyckelordsargument (iteration, , last_resultsession, agentoch så vidare); todos_remaining kör agenten igen medan dess att göra-lista fortfarande har öppna objekt. Om du vill skriva egna accepterar du dessa nyckelordsargument, till exempel lambda *, last_result, **kwargs: "DONE" not in last_result.text.

Skal- och bakgrundsagenter

Om du vill låta agenten köra gränssnittskommandon skickar du en shell_executor (till exempel LocalShellTool från agent-framework-tools). Detta lägger till ett verktyg för att köra kommandon i skalet som kräver godkännande, samt en komponent som undersöker operativsystemet och skalmiljön. Anroparen äger utförarens livscykel:

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

Om du vill aktivera parallell delegering skickar du en sekvens med bakgrundsagenter. Agenten kan delegera deluppgifter för samtidig exekvering:

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

Note

Go-stöd för agent-harnessar kommer snart. Se Agent Framework Go-lagringsplatsen för den senaste statusen.

Planera och köra arbetsflöde

Agentlägesprovidern aktiverar en arbetsstil i två faser som parkopplas naturligt med att göra-listan:

  1. Planläge – interaktivt. Agenten ställer klargörande frågor, utarbetar en att göra-lista och plan och får ditt godkännande innan du utför betydande arbete.
  2. Kör läge – autonomt. Agenten arbetar sig självständigt igenom uppgifterna och rapporterar sina framsteg löpande.

Medan lägesprovidern levereras med plan- och körningslägen som standardlägen, kan dessa ersättas med andra lägen och anpassade instruktioner för varje läge om det behövs.

Ett exempel på terminal-UX

Selen ger dig en kapabel agent men föreskriver inte hur människor interagerar med den. För att demonstrera ramverket från början till slut inkluderar vi ett exempel på terminal-UX – en interaktiv konsol (TUI) som visar agentens utdata i realtid, visar dess att göra-lista och aktuella läge, visar förfrågningar om verktygsgodkännande och stöder snedstreckskommandon som /todos, /mode och /exit.

Important

Dessa konsolprojekt är exempel, inte en del av det levererade ramverket. De är avsiktligt fristående så att du kan köra dem som de är för att utforska testmiljön, eller kopiera dem till ditt eget projekt som en utgångspunkt för att bygga din egen terminalupplevelse.

Exempelkonsolen i .NET är projektet Harness.Shared.Console. Dess startpunkt är HarnessConsole.RunAgentAsync, med din agent, en platshållarprompt och en valfri HarnessConsoleOptions (observatörer, snedstreckshanterare, lägesfärger):

using Harness.Shared.Console;

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

Anpassa den med dina egna observatörer, verktygsformaterare och kommandohanterare – eller förgrena den som bas för din egen terminalupplevelse. Se .NET exempel på sele.

Python-exempelkonsolen console är paketet bredvid seleexemplen. Dess startpunkt är run_agent_async, som kör en textbaserad app:

from console import run_agent_async

await run_agent_async(agent)

Det är organiserat kring observatörer, gränssnittskomponenter och snedstreckskommandon, alla utökningsbara via ConsoleObserverbasklasserna , ToolCallFormatteroch CommandHandler (beroende på textual och rich). Kör den som den är, eller kopiera den och använd den som grund för din egen upplevelse i terminalen. Se Python exempel på sele.

Nästa steg

CodeAct

Gå djupare

  • Last updated on