Kommentar
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
Ett agentramverk, som ibland kallas ett AI-ramverk, är det ramverk vid körning som förvandlar en språkmodell till en agent som kan utföra uppgifter. Den driver modell- och verktygsanrop, hanterar konversationstillstånd och kontext, tillämpar godkännandeprinciper och kan hålla agenten igång med en uppgift med flera steg.
Agent Framework tillhandahåller en åsiktsbaserad, batteribaserad sele för forskning, kodning, dataanalys och annat långvarigt arbete. Du tillhandahåller en chattklient och anpassar endast de funktioner som programmet behöver.
Architecture
Harness sätter samman befintliga byggblock i Agent Framework i stället för att definiera en separat agentkörningsmiljö:
- Chattklient – ansluter agenten till en modell.
- Chat pipeline — lägger till funktionsanrop, meddelandeinjektion, beständig lagring av historik per tjänstanrop och valfri kompaktering.
- Agent- och kontextleverantörer — lägg till sessionsspecifika instruktioner, verktyg, minne, att göra-status, driftlägen och valfria funktioner.
- Mellanprogramvara och dekoratörer – lägg till hantering av godkännanden, observabilitet och valfria begränsade loopar.
- Program-UX – strömmar svar, visar förlopp och samlar in indata, till exempel godkännanden av verktyg.
Det resulterande objektet är fortfarande en normal Agent Framework-agent: en HarnessAgent som härleds från AIAgent i .NET, en Agent som returneras av create_harness_agent i Python eller en provider-backad konfigurerad *agent.Agent med harness.AgentConfig i Go. Sessionerna använder samma sessions- och kontextproviderabstraktioner som andra agenter.
Kapacitetsmatris för utnyttja
| Capability | Selens beteende | Kanonisk vägledning |
|---|---|---|
| Funktionsanrop | Aktiverad med en konfigurerbar iterationsgräns per begäran. Konstruktorer för Go-providers ansvarar för verktygsanropsloopen. | Funktionsverktyg |
| Historiklagring per tjänstanrop | Bevarar historiken efter varje modellanrop i en verktygsanropskörning. | Sessioner |
| Kompaktering | Aktiverad när tokenbegränsningar eller en anpassad strategi anges i .NET och Python. Go kräver uttrycklig sammansättning av providers. | Komprimering |
| Uppgiftsspårning | Aktiverad som standard. | Planering och att göra-punkter |
| Agentlägen | Planera och köra lägen är aktiverade som standard. | Planering och att göra-punkter |
| Minnes- och filåtkomst | Minne för sessionsfiler är aktiverat som standard; delad filåtkomst är valfritt. | Kontextprovidrar |
| Godkännande av verktyg | Stående godkännanden och regler för automatiskt godkännande är aktiverade som standard. | Godkännande av verktyg |
| OpenTelemetry | Agentobservabilitet är aktiverat som standard. | Observerbarhet |
| Webbsökning | Har lagts till som standard där den valda chattklienten stöder den. | Webbsökning |
| Agentkunskaper | Aktiverad som standard i .NET och Go; aktivera via en provider eller sökvägar i Python. | Agentkunskaper |
| Bakgrundsagenter | Valfri parallell delegering till namngivna underordnade agenter i .NET och Python. Ingen paketerad provider för Go-bakgrundsagent. | Bakgrundsagenter |
| Shell-körning | Sammansatt av shell-paketet; Python-fabriken kan koppla ihop den automatiskt. | Shell-verktyg |
| Looping | Valfri avgränsad återanropning styrd av utvärderare eller predikat. | Agentlooping |
Bakgrundsagentdelegering är separat från providerhanterade bakgrundssvar. Bakgrundsagenter kör underagenter för delegerade uppgifter; bakgrundssvar avsöker eller återupptar en leverantörsbegäran med hjälp av en fortsättningstoken.
Tip
Installera agent-framework-builder-python för vägledning för kodningsagenter som hjälper dig att skapa en Python-harness-applikation.
Den här externa färdigheten för kodningsagenter är skild från körningsfunktionen Agent Skills som anges i matrisen.
Skapa en seleagent
Paketet Microsoft.Agents.AI.Harness exponerar HarnessAgent i namnområdet Microsoft.Agents.AI. Skapa en från valfri IChatClient med AsHarnessAgent, eller skapa HarnessAgent direkt:
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);
Använd HarnessAgentOptions för att ange driftvägledning på selenivå, agentspecifika instruktioner och funktionsalternativ:
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 tillhandahåller standardriktlinjerna för sele.
HarnessInstructions visas före ChatOptions.Instructions.
Anpassa sammansättningen
Standardfunktionerna har målalternativ, inklusive DisableTodoProvider, DisableAgentModeProvider, DisableFileMemory, DisableAgentSkillsProvider, DisableWebSearch, DisableToolAutoApproval, DisableOpenTelemetryoch DisableCompaction.
Lägg till anpassade kontextprovidrar med AIContextProviders. Anmäl dig till filåtkomst med FileAccessStore, bakgrundsdelegering med BackgroundAgentsoch loopning med LoopEvaluators.
Skapa en seleagent
create_harness_agent-fabriken returnerar en fullständigt konfigurerad 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)
Ange selenivå och agentspecifika instruktioner separat:
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 tillhandahåller standardriktlinjerna för sele.
harness_instructions visas före agent_instructions.
Anpassa sammansättningen
Inaktivera standardvärden med alternativ som disable_todo, disable_mode, disable_file_memory, disable_web_search, disable_tool_auto_approvaloch disable_compaction.
Ersätt inbyggda leverantörer med todo_provider eller mode_provideroch lägg till providers med context_providers. Kompetenser är valbara via skills_provider eller skills_paths; filåtkomst, bakgrundsagenter, skalverktyg och loopar är också valbara.
Filåtkomst använder som standard den angivna lagringen som en gemensam arbetsyta. Om du vill isolera filer efter det aktiva sessions-ID:t aktiverar du filåtkomst med sessionsomfattning:
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,
)
Om du vill dela mellan valda sessioner skapar du FileAccessProvider(store=file_store, scope="tenant-1") direkt och lägger till den via context_providers. Scopet är en ogenomskinlig nyckel som mappar till en leverantörshanterad mapp, inte en sökväg. Omfångsbegränsad åtkomst nekas i stället för att använda roten för den delade lagringen när varken ett aktivt sessions-ID eller ett explicit omfång är tillgängligt.
Använd tool_name_prefix när en agent har flera filåtkomstproviders. Prefixet genererar namn som workspace_file_access_read och förhindrar kollisioner med verktygsnamn. För prefixprovidrar använder du de providerspecifika godkännanderegelfabrikerna så att varje regel matchar providerns genererade namn:
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() skapar motsvarande regel för både läs- och skrivverktyg. Behåll skrivgodkännande aktiverat såvida inte lagringsgränsen och verktygsindata är betrodda.
När filåtkomst är aktiverat använder du file_access_grep för att hitta 1-baserade radnummer, file_access_read_lines för att inspektera ett inkluderande intervall och file_access_replace_lines för att redigera hela rader.
file_access_read_lines prefixerar varje rad med sitt nummer och ett tabbtecken; utelämna det prefixet när radtexten skickas som expected_line. Den förväntade texten förhindrar att ett inaktuellt eller felaktigt radnummer redigerar fel rad.
file_access_grep använder skiftlägesokänsliga reguljära uttryck, accepterar mönster på upp till 256 tecken och tillämpar en budget på 10 sekunder för hela sökningen. Ogiltiga eller överlånga mönster och sökningar som överskrider budgeten returnerar ett fel. Begränsa katalogen eller mönstret innan du försöker igen.
Important
file_access_grep returnerar matchande radtext med radavslutaren. En anpassad implementering av AgentFileStore.search() måste returnera 1-baserade radnummer som hänvisar till samma rader som AgentFileStore.split_lines() i texten som returneras av read().
Anmärkning
create_harness_agent har släppts. Bakgrundsagenter, filåtkomst och loopning är fortfarande experimentella, och shell-verktygen kommer från förhandsversionspaketet agent-framework-tools .
Go-paketet agent/harness monterar middleware, kontextprovidrar och historik som standard för en normal providerbaserad agent. Anropa harness.AgentConfig(harness.Config{}, agent.Config{...}), hantera dess fel och skicka den returnerade konfigurationen till providerkonstruktorn. Det introducerar inte någon separat agenttyp eller en loop för verktygskörning.
Skapa en seleagent
Det sammansatta exemplet konfigurerar en Foundry-baserad harness-agent:
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.",
},
)
Anpassa sammansättningen
Hjälpprogrammet aktiverar följande standardvärden:
| Component | Go-harness standard |
|---|---|
| Planning | sessionsbaserade verktyg för att göra-listor och planerings-/körlägen, med början i planläge |
| Filminne | Beständiga filer under agent-file-memory, med en isolerad arbetsmapp per session |
| Kompetenser | Filbaserad upptäckt från arbetskatalogen, exklusive minnesunderträdet |
| Webbsökning | En värdbaserad webbsökningsdeklaration, såvida inte anroparen redan har angett en |
| Approval | Mellanprogram för stående godkännande och automatiskt godkännande för verktyg som kräver godkännande |
| History | Historik i minnet med beständighet för varje tjänstanrop |
| Meddelandeinjektion | Per agent agent.MessageInjector |
| Spårning | Agenter, verktyg och instrumentering för modellanrop som stöds |
Använd harness.Config för att inaktivera komponenter eller åsidosätta deras konfiguration. Inaktivera värdbaserad webbsökning när den valda tjänsten eller distribution inte stöder den. Filbaserade skill-skript kräver en uttryckligen konfigurerad skriptmotor.
Hjälpfunktionen behåller verktyg för anroparen, mellanprogram, kontextproviders och en explicit konfigurerad historikprovider. Med en foundry-modelldistribution använder du DisableStoreOutput: true när lokal historik styr konversationen.
Komprimerings-, loopnings- och skalverktyg läggs inte till av Go-hjälpen. Konfigurera dem uttryckligen när det behövs. Den paketerade delegeringsprovidern för bakgrundsagenten som beskrivs i de andra SDK:erna är inte tillgänglig i Go.
Se Skapa en Go harness-agent för installation och konfigurationsguiden för Go harness för standardinställningar och åsidosättningar.
Exempel på terminal-UX
Harness stipulerar inget applikationsgränssnitt. Lagringsplatsen innehåller exempelterminalprogram som strömmar utdata, visar todos och det aktuella läget, frågor om godkännande av ytverktyg och tillhandahåller kommandon som /todos, /modeoch /exit.
Important
Dessa konsolprojekt är exempel, inte levererade ramverkskomponenter. Använd dem som körbara exempel eller som utgångspunkt för din egen terminalupplevelse.
.NET-kodexemplets startpunkt är HarnessConsole.RunAgentAsync:
using Harness.Shared.Console;
await HarnessConsole.RunAgentAsync(
agent,
userPrompt: "Ask me anything to get started.");
Anpassa exemplet med observatörer, verktygsformaterare, kommandohanterare och HarnessConsoleOptions. Se .NET Harness-exempel.
Python-exemplet använder det Textual-baserade console-paketet vid sidan av Harness-exemplen:
from console import run_agent_async
await run_agent_async(agent)
Anpassa exemplet med observatörer, formaterare, kommandon och gränssnittskomponenter. Se Python Harness-exemplen.
Go-repositoryt innehåller ett exempel på sammansatt harness med godkännandehantering och en separat interaktiv CLI-demo för chatt. Chatt-CLI använder en enkel agent; det är inte en motsvarighet till C#- eller Python Harness-konsolen.