Agenten-Harness

Ein Agent-Framework, manchmal auch als KI-Framework bezeichnet, ist die Laufzeitstruktur, die ein Sprachmodell in einen Agenten verwandelt, der Aufgaben ausführen kann. Sie steuert Modell- und Toolaufrufe, verwaltet den Gesprächszustand und den Kontext, wendet Genehmigungsrichtlinien an und kann dafür sorgen, dass der Agent bei einer mehrstufigen Aufgabe vorankommt.

Agent Framework bietet einen meinungsvermerkten, batterienbezogenen Harness für Forschung, Codierung, Datenanalyse und andere langfristige Arbeiten. Sie stellen einen Chatclient bereit und passen nur die Funktionen an, die Ihre Anwendung benötigt.

Architecture

Die "Harness" erstellt vorhandene Agent Framework-Bausteine, anstatt eine separate Agent-Laufzeit zu definieren:

  1. Chatclient – verbindet den Agent mit einem Modell.
  2. Chat-Pipeline — fügt Funktionsaufrufe, Nachrichteninjektion, dienstaufrufbezogene Verlaufspersistenz und optionale Kompaktierung hinzu.
  3. Agent- und Kontextanbieter – Fügen Sie sitzungsbezogene Anweisungen, Tools, Arbeitsspeicher, Todo-Zustand, Betriebsmodi und optionale Funktionen hinzu.
  4. Middleware und Dekorateure – Fügen Sie Genehmigungsbehandlung, Observierbarkeit und optionale gebundene Schleifen hinzu.
  5. Anwendungsux – streamt Antworten, zeigt den Fortschritt an und sammelt Eingaben wie z. B. Toolgenehmigungen.

Das resultierende Objekt bleibt ein normaler Agent-Framework-Agent: ein HarnessAgent, das in .NET von AIAgent abgeleitet ist, ein von create_harness_agent in Python zurückgegebenes Agent oder ein anbietergestütztes harness.AgentConfig, das in Go mit *agent.Agent konfiguriert ist. Seine Sitzungen verwenden dieselben Sitzungs- und Kontextanbieter-Abstraktionen wie andere Agenten.

Fähigkeitsmatrix nutzen

Capability Verhalten des Harness Kanonische Anleitung
Funktionsaufruf Aktiviert mit einem konfigurierbaren Iterationslimit pro Anforderung. Die Konstruktoren der Go-Anbieter steuern die Schleife zum Aufruf der Tools. Funktionale Werkzeuge
Persistenz des Anrufverlaufs pro Dienst Speichert den Verlauf nach jedem Modellaufruf während einer Ausführung mit Tool-Aufrufen. Sitzungen
Komprimierung Aktiviert, wenn Tokenbeschränkungen oder eine benutzerdefinierte Strategie in .NET und Python bereitgestellt werden. Go erfordert eine explizite Provider-Komposition. Verdichtung
Todo-Nachverfolgung Standardmäßig aktiviert. Planung und Aufgaben
Agent-Modi Plan- und Ausführungsmodi sind standardmäßig aktiviert. Planung und Aufgaben
Dateispeicher und Dateizugriff Der Speicher der Sitzungsdatei ist standardmäßig aktiviert. Der Zugriff auf freigegebene Dateien ist opt-in. Kontextanbieter
Toolgenehmigung Ständige Genehmigungen und Regeln für die automatische Genehmigung sind standardmäßig aktiviert. Toolgenehmigung
OpenTelemetry Die Agent-Observability ist standardmäßig aktiviert. Beobachtbarkeit
Websuche Standardmäßig hinzugefügt, wo der ausgewählte Chatclient sie unterstützt. Websuche
Agent-Fähigkeiten In .NET und Go standardmäßig aktiviert; in Python über einen Anbieter oder Pfade aktivierbar. Agent-Fähigkeiten
Hintergrund-Agents Optionale parallele Delegierung an benannte untergeordnete Agents in .NET und Python. Kein verpackter Go-Hintergrund-Agent-Anbieter. Hintergrund-Agents
Shellausführung Besteht aus dem Shell-Paket; die Python-Factory kann es automatisch verdrahten. Shelltools
Schleifen Optionaler gebundener Erneutaufruf, der von Evaluatoren oder Prädikaten gesteuert wird. Agent-Schleifen

Hintergrund-Agent-Delegierung ist von vom Anbieter verwalteten Hintergrundantworten getrennt. Hintergrundagenten führen untergeordnete Agenten für delegierte Aufgaben aus; Hintergrundantworten fragen eine Anbieteranfrage ab oder setzen sie mithilfe eines Fortsetzungstokens fort.

Tip

Installieren Sie agent-framework-builder-python, um Anleitungen für den Coding-Agent zu erhalten, die beim Verfassen einer Python-Anwendung helfen. Diese Fähigkeit für externe Coding-Agents ist von der in der Matrix aufgeführten Laufzeit-Agentskills-Funktion getrennt.

Harness-Agent erstellen

Das Microsoft.Agents.AI.Harness-Paket stellt HarnessAgent im Namespace Microsoft.Agents.AI bereit. Erstellen Sie eines aus einem beliebigen IChatClient mit AsHarnessAgent, oder erstellen Sie 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);

Verwenden Sie HarnessAgentOptions, um Betriebsanweisungen auf Harness-Ebene, agentenspezifische Anweisungen und Feature-Optionen festzulegen:

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 liefert den Standardleitfaden für den Harness. HarnessInstructions wird vor ChatOptions.Instructions angezeigt.

Anpassen der Komposition

Standardfunktionen verfügen über spezifische Optionen, darunter DisableTodoProvider, DisableAgentModeProvider, DisableFileMemory, DisableAgentSkillsProvider, DisableWebSearch, DisableToolAutoApproval, DisableOpenTelemetry und DisableCompaction.

Hinzufügen von benutzerdefinierten Kontextanbietern mit AIContextProviders. Aktivieren Sie den Dateizugriff mit FileAccessStore, die Hintergrunddelegierung mit BackgroundAgents und Schleifen mit LoopEvaluators.

Harness-Agent erstellen

Die create_harness_agent-Factory gibt einen vollständig konfigurierten Wert Agent zurück:

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)

Legen Sie Anweisungen auf Harness-Ebene und agentspezifische Anweisungen separat fest:

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 liefert den Standardleitfaden für den Harness. harness_instructions wird vor agent_instructions angezeigt.

Anpassen der Komposition

Deaktivieren Sie die Standardeinstellungen mit Optionen wie disable_todo, disable_mode, disable_file_memory, disable_web_search, disable_tool_auto_approval und disable_compaction.

Ersetzen Sie integrierte Anbieter durch todo_provider oder mode_provider, und fügen Sie Anbieter durch context_providers. Funktionen müssen über skills_provider oder skills_paths aktiviert werden; Dateizugriff, Hintergrund-Agenten, Shell-Tools und Schleifen müssen ebenfalls aktiviert werden.

Der Dateizugriff verwendet standardmäßig den angegebenen Speicher als einen freigegebenen Arbeitsbereich. Um Dateien durch die aktive Sitzungs-ID zu isolieren, aktivieren Sie den Dateizugriff auf sitzungsbezogene Dateien:

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

Erstellen Sie für die gezielte Freigabe über ausgewählte Sitzungen hinweg FileAccessProvider(store=file_store, scope="tenant-1") direkt und fügen Sie es über context_providers hinzu. Der Gültigkeitsbereich ist ein opaker Schlüssel, der auf einen vom Anbieter verwalteten Ordner verweist, kein Pfad. Der bereichsbezogene Zugriff schlägt fehl, anstatt den freigegebenen Speicherstamm zu verwenden, wenn weder eine aktive Sitzungs-ID noch ein expliziter Bereich verfügbar sind.

Verwenden Sie tool_name_prefix, wenn ein Agent über mehrere Dateizugriffsanbieter verfügt. Das Präfix erzeugt Namen wie workspace_file_access_read und verhindert Konflikte mit Toolnamen. Verwenden Sie für präfixierte Anbieter die anbieterspezifischen Genehmigungsregelfabriken, sodass jede Regel mit den generierten Namen dieses Anbieters übereinstimmt:

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() erstellt die entsprechende Regel für Lese- und Schreibtools. Lassen Sie die Schreibgenehmigung aktiviert, es sei denn, der Speicherbereich und die Tooleingaben sind vertrauenswürdig.

Wenn der Dateizugriff aktiviert ist, verwenden Sie die Suche file_access_grep nach 1-basierten Zeilennummern, file_access_read_lines zum Überprüfen eines inklusiven Bereichs und file_access_replace_lines zum Bearbeiten ganzer Zeilen. file_access_read_lines stellt jeder Zeile ihre Nummer und einen Tabulator voran. Lassen Sie dieses Präfix weg, wenn Sie den Zeilentext als expected_line übergeben. Der erwartete Text verhindert, dass eine veraltete oder nicht übereinstimmende Zeilennummer die falsche Zeile bearbeitet.

file_access_grep verwendet reguläre Ausdrücke ohne Beachtung der Groß-/Kleinschreibung, akzeptiert Muster mit bis zu 256 Zeichen und setzt für die gesamte Suche ein Zeitlimit von 10 Sekunden. Ungültige oder überlange Muster und Suchvorgänge, die das Budget überschreiten, geben einen Fehler zurück. Verengen Sie das Verzeichnis oder Muster, bevor Sie den Vorgang wiederholen.

Important

file_access_grep gibt den Text der übereinstimmenden Zeile einschließlich ihres Zeilenabschlusses zurück. Eine benutzerdefinierte Implementierung von AgentFileStore.search() muss 1-basierte Zeilennummern zurückgeben, die im von read() zurückgegebenen Text auf dieselben Zeilen verweisen wie AgentFileStore.split_lines().

Note

create_harness_agent wird freigegeben. Hintergrund-Agenten, Dateizugriff und Schleifen bleiben experimentell, und die Shell-Tools stammen aus dem Vorabversionspaket agent-framework-tools.

Das Go-Paket agent/harness setzt Middleware, Kontextanbieter und Verlaufsstandardwerte für einen normalen anbietergestützten Agent zusammen. Rufen Sie harness.AgentConfig(harness.Config{}, agent.Config{...}) auf, behandeln Sie dessen Fehler, und übergeben Sie die zurückgegebene Konfiguration an den Anbieterkonstruktor. Es führt keine separate Agent-Typ- oder Toolausführungsschleife ein.

Harness-Agent erstellen

Das zusammengesetzte Muster konfiguriert einen Umgebungs-Agent mit Foundry-Backend:

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

Anpassen der Komposition

Das Hilfsprogramm verwendet die folgenden Standardwerte:

Component Standard für Go-Umgebung
Planung Sitzungsgestützte To-do-Tools und Plan-/Ausführungsmodi, beginnend im Planmodus
Dateispeicher Persistente Dateien unter agent-file-memory, mit einem isolierten Arbeitsordner pro Sitzung
Qualifikationen Dateigestützte Erkennung aus dem Arbeitsverzeichnis, mit Ausnahme des Speicher-Teilbaums
Websuche Eine gehostete Websuchdeklaration, sofern der Aufrufer nicht bereits eine bereitgestellt hat
Approval Middleware zur Dauergenehmigung und automatischen Genehmigung für Tools, die eine Genehmigung erfordern
History Speicherinterner Verlauf mit Persistenz pro Dienstaufruf
Nachrichteneinfügung Pro Agent agent.MessageInjector
Ablaufverfolgung Agent, Tool und Instrumentierung für unterstützte Modellaufrufe

Verwenden Sie harness.Config, um Komponenten zu deaktivieren oder ihre Konfiguration außer Kraft zu setzen. Deaktivieren Sie die gehostete Websuche, wenn der ausgewählte Dienst oder die ausgewählte Bereitstellung sie nicht unterstützt. Dateigestützte Skill-Skripts erfordern weiterhin einen explizit konfigurierten Skriptausführer.

Das Hilfsprogramm behält Aufrufer-Tools, Middleware, Kontextanbieter und einen explizit konfigurierten Verlaufsanbieter bei. Verwenden Sie DisableStoreOutput: true bei einer Bereitstellung des Foundry-Modells, wenn der lokale Verlauf die Konversation verwaltet.

Komprimierungs-, Looping- und Shelltools werden vom Go-Hilfsprogramm nicht hinzugefügt. Konfigurieren Sie sie bei Bedarf explizit. Der paketierte Hintergrund-Agent-Delegierungsanbieter, der in den anderen SDKs beschrieben wird, ist in Go nicht verfügbar.

Weitere Informationen finden Sie unter Erstellen eines Go-Harness-Agenten für die Einrichtung und im Leitfaden zur Go-Harness-Konfiguration für Standardwerte und Außerkraftsetzungen.

Beispiel für Terminal-UX

Der Harness schreibt keine Anwendungsschnittstelle vor. Das Repository enthält Beispiel-Terminalanwendungen, die die Ausgabe streamen, Todos anzeigen und den aktuellen Modus, Surface Tool-Genehmigungsaufforderungen und Befehle wie /todos, /mode und /exitbereitstellen .

Important

Bei diesen Konsolenprojekten handelt es sich um Beispiele, nicht ausgelieferte Frameworkkomponenten. Verwenden Sie sie als lauffähige Beispiele oder als Ausgangspunkt für Ihre eigene Terminalerfahrung.

Der .NET Beispieleinstiegspunkt lautetHarnessConsole.RunAgentAsync:

using Harness.Shared.Console;

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

Passen Sie das Beispiel mit Beobachtern, Tool-Formatierern, Befehls-Handlern und HarnessConsoleOptions an. Sehen Sie sich die Beispiele für .NET Harness an.

Das Python-Beispiel verwendet das auf Textual basierende Paket console neben den Harness-Beispielen:

from console import run_agent_async

await run_agent_async(agent)

Passen Sie das Beispiel mit Beobachtern, Formatierern, Befehlen und UI-Komponenten an. Sehen Sie sich die Beispiele für Python Harness an.

Das Go-Repository enthält ein Beispiel für ein Composite-Harness mit Genehmigungsverwaltung und eine separate interaktive Chat CLI-Demo. Die Chat-CLI verwendet einen schlichten Agenten; sie entspricht nicht der C#- oder Python-Harness-Konsole.

Nächste Schritte

Arbeit planen und Aufgaben nachverfolgen

Mehr erfahren

  • Zuletzt aktualisiert um