Wykorzystanie agenta

Wykorzystanie agenta, nazywane czasem wykorzystaniem sztucznej inteligencji, to szkielet środowiska uruchomieniowego, który zamienia model językowy w agenta, który może wykonywać pracę. Steruje wywołaniami modelu i narzędzi, zarządza stanem rozmowy i kontekstem, egzekwuje zasady zatwierdzania oraz może podtrzymywać postęp agenta w realizacji wieloetapowego zadania.

Agent Framework zapewnia kompleksowe środowisko o predefiniowanych założeniach do badań, programowania, analizy danych i innych długotrwałych zadań. Udostępniasz klienta czatu i dostosowujesz tylko możliwości wymagane przez aplikację.

Architecture

Harness wykorzystuje istniejące elementy składowe frameworka Agent Framework, zamiast definiować oddzielne środowisko uruchomieniowe agenta:

  1. Klient czatu — łączy agenta z modelem.
  2. Potok konwersacji — dodaje wywoływanie funkcji, wstrzykiwanie komunikatów, utrwalanie historii dla każdego wywołania usługi oraz opcjonalne kompaktowanie.
  3. Dostawcy agenta i kontekstu — dodaj instrukcje dotyczące sesji, narzędzia, pamięć, stan wykonania, tryby operacyjne i opcjonalne możliwości.
  4. Middleware i dekoratory — dodaj obsługę akceptacji, obserwowalność oraz opcjonalne pętle o ograniczonej liczbie iteracji.
  5. Interfejs użytkownika aplikacji — przesyła strumieniowo odpowiedzi, wyświetla postęp i zbiera dane wejściowe, takie jak zatwierdzenia narzędzi.

Wynikowy obiekt pozostaje normalnym agentem Agent Framework: obiektem HarnessAgent, który dziedziczy z AIAgent w .NET, obiektem Agent zwracanym przez create_harness_agent w Pythonie lub obiektem *agent.Agent opartym na dostawcy, skonfigurowanym za pomocą harness.AgentConfig w Go. Jego sesje korzystają z tych samych abstrakcji sesji i dostawcy kontekstu, co inni agenci.

Macierz możliwości wykorzystania

Capability Zachowanie uprzęży Wskazówki kanoniczne
Wywołanie funkcji Włączone z konfigurowalnym limitem iteracji dla poszczególnych żądań. Konstruktory dostawcy języka Go odpowiadają za pętlę wywoływania narzędzi. Narzędzia funkcji
Utrwalanie historii dla każdego wywołania usługi Utrwala historię po każdym wywołaniu modelu w przebiegu wywoływania narzędzi. Sesje
Kompakcja Włączone, gdy w .NET i Python określono limity tokenów lub niestandardową strategię. Go wymaga jawnej kompozycji providerów. Zagęszczanie
Śledzenie zadań Włączone domyślnie. Planowanie i zadania
Tryby agenta Tryby planowania i wykonywania są domyślnie włączone. Planowanie i zadania
Pamięć plików i dostęp do plików Pamięć plików sesji jest domyślnie włączona; dostęp do współdzielonych plików jest opcjonalny. Dostawcy kontekstu
Zatwierdzanie narzędzi Zatwierdzenia stałe i reguły automatycznego zatwierdzania są domyślnie włączone. Zatwierdzanie narzędzi
OpenTelemetry Możliwość obserwowania agenta jest domyślnie włączona. Obserwowalność
Wyszukiwanie w Internecie Dodano domyślnie, gdzie wybrany klient czatu go obsługuje. Wyszukiwanie w Internecie
Umiejętności agenta Domyślnie włączone w .NET i w języku Go; wymaga włączenia przez dostawcę lub ścieżki w Pythonie. Umiejętności agenta
Agenty działające w tle Opcjonalne delegowanie równoległe do nazwanych agentów podrzędnych w .NET i Python. Brak dostarczanego w pakiecie dostawcy agenta w tle języka Go. Agenci w tle
Wykonywanie poleceń w powłoce Składa się z pakietu powłoki; fabryka Python może automatycznie go podłączać. Narzędzia powłoki
Zapętlanie Opcjonalne ograniczone ponowne wywołanie sterowane przez ewaluatory lub predykaty. Zapętlenie agenta

Delegowanie agenta w tle jest czymś odrębnym od zarządzanych przez dostawcę odpowiedzi w tle. Agenty działające w tle uruchamiają agenty podrzędne do realizacji delegowanych zadań; odpowiedzi działające w tle sondują lub wznawiają pojedyncze żądanie do dostawcy przy użyciu tokenu kontynuacji.

Tip

Aby uzyskać wskazówki dotyczące agenta kodującego, które pomagają utworzyć aplikację testową w Pythonie, zainstaluj program agent-framework-builder-python. Ta zewnętrzna umiejętność kodowania agenta jest odrębna od funkcji Agent Skills w środowisku uruchomieniowym wymienionej w macierzy.

Utwórz agenta Harness

Pakiet Microsoft.Agents.AI.Harness udostępnia HarnessAgent w przestrzeni nazw Microsoft.Agents.AI. Utwórz taki element z dowolnego IChatClient za pomocą AsHarnessAgent albo utwórz bezpośrednio HarnessAgent:

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

Użyj HarnessAgentOptions, aby ustawić wskazówki operacyjne na poziomie harnessu, instrukcje dla konkretnego agenta i opcje funkcji:

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 dostarcza domyślne wskazówki dotyczące uprzęży. HarnessInstructions jest wyświetlany przed ChatOptions.Instructions.

Dostosowywanie kompozycji

Domyślne funkcje obejmują określone opcje, w tym DisableTodoProvider, DisableAgentModeProvider, DisableFileMemory, DisableAgentSkillsProvider, DisableWebSearch, DisableToolAutoApproval, DisableOpenTelemetry i DisableCompaction.

Dodaj niestandardowych dostawców kontekstu za pomocą polecenia AIContextProviders. Włącz dostęp do plików za pomocą FileAccessStore, delegowanie w tle za pomocą BackgroundAgents oraz zapętlanie za pomocą LoopEvaluators.

Utwórz agenta Harness

Metoda wytwórcza create_harness_agent zwraca w pełni skonfigurowany obiekt 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)

Ustaw oddzielnie instrukcje na poziomie harnessu i instrukcje specyficzne dla agenta:

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 dostarcza domyślne wskazówki dotyczące uprzęży. harness_instructions jest wyświetlany przed agent_instructions.

Dostosowywanie kompozycji

Wyłącz wartości domyślne przy użyciu opcji, takich jak disable_todo, , disable_modedisable_file_memory, disable_web_search, disable_tool_auto_approval, i disable_compaction.

Zastąp wbudowanych dostawców za pomocą todo_provider lub mode_provider, a nowych dostawców dodaj za pomocą context_providers. Umiejętności są opcjonalnie włączane za pośrednictwem skills_provider lub skills_paths; dostęp do plików, agenci działający w tle, narzędzia powłoki i zapętlanie również wymagają włączenia.

Dostęp do plików domyślnie używa dostarczonego magazynu jako jednego udostępnionego obszaru roboczego. Aby odizolować pliki według aktywnego identyfikatora sesji, włącz dostęp do plików w zakresie sesji:

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

Aby celowo udostępnić między wybranymi sesjami, skonstruuj element FileAccessProvider(store=file_store, scope="tenant-1") bezpośrednio i dodaj go przez context_providers. Zakres jest nieprzezroczystym kluczem, który odpowiada folderowi zarządzanemu przez dostawcę, a nie ścieżce. Dostęp w określonym zakresie jest blokowany zamiast użycia katalogu głównego współdzielonego magazynu, gdy nie ma ani aktywnego identyfikatora sesji, ani jawnie określonego zakresu.

Użyj tool_name_prefix , gdy jeden agent ma wielu dostawców dostępu do plików. Prefiks tworzy nazwy, takie jak workspace_file_access_read i zapobiega kolizjom nazw narzędzi. W przypadku dostawców z prefiksami należy użyć fabryk reguł zatwierdzania specyficznych dla dostawcy, aby każda reguła odpowiadała wygenerowanym przez dostawcę nazwam:

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() Tworzy równoważną regułę dla narzędzi do odczytu i zapisu. Zachowaj włączone zatwierdzanie zapisu, chyba że granica pamięci masowej i dane wejściowe narzędzia są zaufane.

Po włączeniu dostępu do plików użyj polecenia file_access_grep , aby znaleźć numery wierszy oparte na 1, file_access_read_lines aby sprawdzić zakres inkluzywny i file_access_replace_lines edytować całe wiersze. file_access_read_lines poprzedza każdy wiersz jego numerem i tabulatorem; pomiń ten prefiks podczas przekazywania tekstu wiersza jako expected_line. Oczekiwany tekst zapobiega edytowaniu niewłaściwego wiersza przez nieaktualny lub niezgodny numer wiersza.

file_access_grep używa wyrażeń regularnych bez uwzględniania wielkości liter, akceptuje wzorce do 256 znaków i stosuje 10-sekundowy budżet do całego wyszukiwania. Nieprawidłowe lub zbyt długie wzorce i wyszukiwania, które przekraczają limit, powodują błąd. Przed ponowieniem próby zawęź katalog lub wzorzec.

Important

file_access_grep Zwraca tekst dopasowanego wiersza wraz z terminatorem wiersza. Niestandardowa implementacja AgentFileStore.search() musi zwracać numery wierszy liczone od 1, które wskazują te same wiersze co AgentFileStore.split_lines() w tekście zwracanym przez read().

Uwaga / Notatka

create_harness_agent jest zwalniany. Agenty działające w tle, dostęp do plików i zapętlanie pozostają funkcjami eksperymentalnymi, a narzędzia powłoki systemowej pochodzą z pakietu w wersji przedpremierowej agent-framework-tools.

Pakiet Go agent/harness zestawia oprogramowanie pośredniczące, providery kontekstu i domyślne ustawienia historii dla zwykłego agenta opartego na providerze. Wywołaj metodę harness.AgentConfig(harness.Config{}, agent.Config{...}), obsłuż błąd i przekaż zwróconą konfigurację do konstruktora dostawcy. Nie wprowadza oddzielnego typu agenta ani pętli wykonywania narzędzi.

Utwórz agenta Harness

Złożony przykład konfiguruje agenta harness opartego na systemie Foundry:

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

Dostosowywanie kompozycji

Narzędzie pomocnicze włącza następujące wartości domyślne:

Component Domyślna uprząż Go
Planning Narzędzia listy zadań oparte na sesji i tryby planowania/wykonywania, uruchamiane w trybie planowania
Pamięć plikowa Trwałe pliki w obszarze agent-file-memory, z izolowanym folderem roboczym na sesję
Skills Odnajdywanie oparte na plikach z katalogu roboczego z wyłączeniem poddrzewa pamięci
Wyszukiwanie w Internecie Hostowana deklaracja wyszukiwania w sieci Web, chyba że obiekt wywołujący już podał jedną deklarację
Approval Stałe zatwierdzanie i automatyczne zatwierdzanie oprogramowanie pośredniczące dla narzędzi, które wymagają zatwierdzenia
History Historia w pamięci z trwałością dla każdego wywołania usługi
Wstrzykiwanie komunikatów A na jednego agenta agent.MessageInjector
Śledzenie Instrumentacja agenta, narzędzia i obsługiwanych wywołań modeli

Użyj harness.Config, aby wyłączyć składniki lub zastąpić ich konfigurację. Wyłącz hostowane wyszukiwanie w Internecie, gdy wybrana usługa lub wdrożenie nie obsługuje go. Skrypty skill oparte na plikach wymagają jawnie skonfigurowanego modułu uruchamiającego skrypty.

Pomocnik zachowuje narzędzia wywołującego, oprogramowanie pośredniczące, dostawców kontekstu i jawnie skonfigurowanego dostawcę historii. W przypadku wdrożenia modelu Foundry użyj metody DisableStoreOutput: true, gdy lokalna historia zarządza konwersacją.

Kompaktowanie, zapętlanie i narzędzia powłoki nie są dodawane przez pomocnika języka Go. Skonfiguruj je jawnie w razie potrzeby. Wbudowany dostawca delegowania agenta działającego w tle opisany w innych zestawach SDK nie jest dostępny w języku Go.

Zobacz Tworzenie agenta uprzęży Go, aby uzyskać informacje o konfiguracji, oraz przewodnik konfiguracji uprzęży Go, aby uzyskać informacje o ustawieniach domyślnych i przesłonięciach.

Przykładowy interfejs użytkownika terminalu

Harness nie narzuca interfejsu aplikacji. Repozytorium obejmuje przykładowe aplikacje terminalowe, które strumieniowo wyświetlają dane wyjściowe, pokazują listę zadań i bieżący tryb, wyświetlają monity o akceptację użycia narzędzi oraz udostępniają polecenia, takie jak /todos, /mode i /exit.

Important

Te projekty konsoli są przykładami, a nie dostarczanymi składnikami platformy. Użyj ich jako przykładów możliwych do uruchomienia lub jako punktu wyjścia dla własnego środowiska terminalu.

Przykładowy punkt wejścia .NET to HarnessConsole.RunAgentAsync:

using Harness.Shared.Console;

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

Dostosuj przykład za pomocą obserwatorów, formatatorów narzędzi, procedur obsługi poleceń i HarnessConsoleOptions. Zapoznaj się z przykładami .NET Harness.

Przykład w Pythonie używa pakietu opartego na Textual console obok przykładów Harness:

from console import run_agent_async

await run_agent_async(agent)

Dostosuj przykład za pomocą obserwatorów, formaterów, poleceń i składników interfejsu użytkownika. Zapoznaj się z przykładami Python Harness.

Repozytorium Go zawiera przykład złożonej uprzęży testowej z obsługą zatwierdzania i osobnym demo interaktywnego czatu w CLI. Interfejs wiersza polecenia czatu używa prostego agenta; nie jest to odpowiednik konsoli C# ani Harness for Python.

Następne kroki

Zaplanuj pracę i śledź zadania

Głębiej

  • Ostatnia aktualizacja o