Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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:
- Chatclient – verbindet den Agent mit einem Modell.
- Chat-Pipeline — fügt Funktionsaufrufe, Nachrichteninjektion, dienstaufrufbezogene Verlaufspersistenz und optionale Kompaktierung hinzu.
- Agent- und Kontextanbieter – Fügen Sie sitzungsbezogene Anweisungen, Tools, Arbeitsspeicher, Todo-Zustand, Betriebsmodi und optionale Funktionen hinzu.
- Middleware und Dekorateure – Fügen Sie Genehmigungsbehandlung, Observierbarkeit und optionale gebundene Schleifen hinzu.
- 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, oder ein in Python von create_harness_agent zurückgegebenes Agent. 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. | 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 bereitgestellt werden. | 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 | Standardmäßig in .NET aktiviert; in Python muss dies explizit über einen Anbieter oder über Pfade aktiviert werden. | Agent-Fähigkeiten |
| Hintergrund-Agents | Optionale parallele Delegierung an benannte untergeordnete Agents. | 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.
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.
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.
Note
Ein verpacktes Go Harness ist derzeit nicht verfügbar. Verfassen Sie die entsprechenden Go-Agent-, Kontextanbieter-, Komprimierungs- und Middlewarepakete direkt. Aktuelle Unterstützung finden Sie im Agent Framework Go-Repository .
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 Repository enthält derzeit kein verpacktes Go Harness-Terminalbeispiel.