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 zwykłym agentem Agent Framework: elementem HarnessAgent, który dziedziczy po AIAgent w środowisku .NET, lub obiektem Agent zwracanym przez create_harness_agent w Pythonie. 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ń. 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 są dostarczane limity tokenów lub strategia niestandardowa. 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; w Pythonie wymaga włączenia za pośrednictwem dostawcy lub ścieżek. Umiejętności agenta
Agenty działające w tle Opcjonalne delegowanie równoległych zadań do nazwanych agentów podrzędnych. 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.

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.

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.

Uwaga / Notatka

Pakietowa wersja Go Harness nie jest obecnie dostępna. Utwórz bezpośrednio odpowiednie pakiety agenta języka Go, dostawcy kontekstu, kompaktowania i oprogramowania pośredniczącego. Aby uzyskać bieżącą pomoc techniczną, zobacz repozytorium Agent Framework Go .

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 nie zawiera obecnie spakowanego przykładu terminalu Go Harness.

Następne kroki

Zaplanuj pracę i śledź zadania

Głębiej

  • Last updated on