Wykorzystanie agentów

Tworzenie agenta testowego

Uprzęża jest uwidoczniona jako HarnessAgent klasa w Microsoft.Agents.AI przestrzeni nazw (pakiet).Microsoft.Agents.AI.Harness Najprostszym sposobem na utworzenie go jest użycie metody rozszerzającej IChatClient z dowolnego AsHarnessAgent:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// chatClient is any IChatClient implementation (Foundry, Azure OpenAI, OpenAI, Anthropic, ...).
AIAgent agent = chatClient.AsHarnessAgent();

AgentResponse response = await agent.RunAsync("Plan a weekend trip to Seattle.");
Console.WriteLine(response.Text);

Agenta można również utworzyć bezpośrednio:

AIAgent agent = new HarnessAgent(chatClient);

Dodaj HarnessAgentOptions, aby udostępnić instrukcje i narzędzia. Instrukcje na poziomie harnessu (HarnessAgentOptions.HarnessInstructions) zawierają ogólne wytyczne operacyjne, natomiast instrukcje dotyczące konkretnych zadań znajdują się w ChatOptions.Instructions. HarnessAgent zawiera domyślne instrukcje na poziomie harnessu (HarnessAgent.DefaultInstructions), ale możesz je zastąpić własnymi za pośrednictwem HarnessAgentOptions.HarnessInstructions.

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    Name = "research-agent",
    ChatOptions = new ChatOptions
    {
        Instructions = "You are a research assistant focused on academic sources.",
        Tools = [AIFunctionFactory.Create(GetStockPrice)],
    },
});

Włączanie kompaktowania

Kompaktowanie uniemożliwia przepełnienie okna kontekstowego przez długie pętle wywoływania narzędzi. Jeśli nie używasz historii czatu przechowywanej w usłudze inferencji, domyślnie do InMemoryChatHistoryProvider również przypisywany jest ten sam dostawca kompaktowania, dzięki czemu historia czatu przechowywana w sesji także jest kompaktowana. Podaj zarówno maksymalny rozmiar okna kontekstowego, jak i maksymalny rozmiar danych wyjściowych, aby włączyć domyślną strategię rozpoznawania budżetu tokenu:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    MaxContextWindowTokens = 128_000,
    MaxOutputTokens = 16_384,
});

Aby użyć własnej strategii, ustaw wartość HarnessAgentOptions.CompactionStrategy; aby wyłączyć kompaktowanie, ustaw wartość DisableCompaction = true.

Dostosowywanie i wyłączanie funkcji

Każda domyślna funkcja ma odpowiadającą jej flagę wyłączenia w HarnessAgentOptions, dzięki czemu możesz zachować wybrany potok i wyłączyć pozostałe:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    HarnessInstructions = "Custom operating guidelines here.",
    DisableTodoProvider = true,      // No todo list
    DisableAgentModeProvider = true, // No plan/execute modes
    DisableWebSearch = true,         // No hosted web search tool
    DisableFileMemory = true,        // No file-based session memory
});

Inne flagi to DisableFileAccess, DisableAgentSkillsProvider, DisableToolAutoApproval i DisableOpenTelemetry. Możesz również dodać własnych dostawców kontekstu za pomocą AIContextProviders i skierować dostawcę umiejętności do niestandardowych lokalizacji za pomocą AgentSkillsSource.

Zapętlanie aż do zakończenia

Domyślnie uprzęża jest uruchamiana raz na wywołanie. Podaj co najmniej jedną instancję LoopEvaluator, aby agent był automatycznie ponownie wywoływany, dopóki ewaluatorzy nie zdecydują, że działanie zostało zakończone (na przykład gdy pojawi się znacznik ukończenia, predykat zostanie spełniony lub sędzia AI to zatwierdzi):

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    LoopEvaluators = [new CompletionMarkerLoopEvaluator("DONE")],
});

Pętla jest używana jako najbardziej zewnętrzny dekorator agenta, więc każda iteracja stanowi pełne, niezależnie zatwierdzone przez narzędzia i śledzone uruchomienie agenta.

Agenty powłoki systemowej i działające w tle

Aby umożliwić agentowi uruchamianie poleceń powłoki, przekaż element ShellExecutor. Spowoduje to dodanie narzędzia do wykonywania powłoki z bramą zatwierdzenia i dostawcy, który wprowadza informacje o systemie operacyjnym, powłoce i katalogu roboczego do kontekstu:

using Microsoft.Agents.AI.Tools.Shell;

// A shell confined to a working directory. Commands require approval by default;
// the deny-list is a UX pre-filter, not a security boundary.
await using var shell = new LocalShellExecutor(new LocalShellExecutorOptions
{
    WorkingDirectory = workingDir,
    ConfineWorkingDirectory = true,
    Policy = new ShellPolicy(denyList: [@"\brm\s+-rf\b", @"\bsudo\b"]),
});

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    ShellExecutor = shell,
});

Aby włączyć delegowanie równoległe, przekaż zbiór agentów działających w tle. Agent może delegować podzadania do współbieżnego wykonania:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    BackgroundAgents = [webSearchAgent, codeAgent],
});

Tworzenie agenta testowego

Uprzęża jest uwidaczniona jako create_harness_agent funkcja fabryczna, która tworzy w pełni skonfigurowaną Agent z poziomu klienta czatu. Najprostszy formularz wymaga tylko klienta:

from agent_framework import create_harness_agent
from agent_framework.openai import OpenAIChatClient

agent = create_harness_agent(
    OpenAIChatClient(model="gpt-4o"),
)

session = agent.create_session()
response = await agent.run("Plan a weekend trip to Seattle.", session=session)
print(response.text)

Instrukcje na poziomie harnessu opisują ogólne wytyczne dotyczące działania, a instrukcje dotyczące konkretnych zadań znajdują się w agent_instructions. Uprzęże są dostarczane z domyślnymi instrukcjami na poziomie uprzęży (DEFAULT_HARNESS_INSTRUCTIONS), które można zastąpić za pomocą polecenia harness_instructions. Możesz również przekazać dodatkowe narzędzia:

agent = create_harness_agent(
    client=client,
    name="research-agent",
    agent_instructions="You are a research assistant focused on academic sources.",
    tools=get_stock_price,
)

Włączanie kompaktowania

Kompaktowanie uniemożliwia przepełnienie okna kontekstowego przez długie pętle wywoływania narzędzi. Podaj maksymalny rozmiar okna kontekstowego modelu i maksymalny rozmiar danych wyjściowych, aby włączyć domyślne strategie obsługujące budżet tokenów:

agent = create_harness_agent(
    client=client,
    max_context_window_tokens=128_000,
    max_output_tokens=16_384,
)

Jeśli nie podano parametru tokenu ani niestandardowej strategii, kompaktowanie jest automatycznie wyłączone. Aby użyć własnych strategii, przekaż before_compaction_strategy i/lub after_compaction_strategy; aby jawnie wyłączyć kompaktowanie, ustaw wartość disable_compaction=True.

Dostosowywanie i wyłączanie funkcji

Każda funkcja domyślna ma odpowiedni disable_* argument słowa kluczowego, dzięki czemu można zachować odpowiednie części i usunąć pozostałe:

agent = create_harness_agent(
    client=client,
    harness_instructions="Custom operating guidelines here.",
    disable_todo=True,         # No todo list
    disable_mode=True,         # No plan/execute modes
    disable_web_search=True,   # No hosted web search tool
    disable_file_memory=True,  # No file-based session memory
)

Inne flagi to disable_file_access, disable_tool_auto_approval i disable_compaction. Możesz skierować odkrywanie umiejętności do lokalizacji niestandardowych za pomocą skills_paths i dodać własnych dostawców za pomocą context_providers.

Zapętlanie aż do zakończenia

Domyślnie uprzęża jest uruchamiana raz na wywołanie. Przekaż predykat loop_should_continue, aby automatycznie ponawiać wywołanie agenta, dopóki predykat nie uzna, że zakończono. Użyj loop_next_message, aby sterować monitem w każdej kolejnej iteracji, a loop_max_iterations, aby ograniczyć liczbę przebiegów:

from agent_framework import create_harness_agent, todos_remaining

agent = create_harness_agent(
    client=client,
    loop_should_continue=todos_remaining(),
    loop_max_iterations=10,
)

Predykat jest wywoływany z argumentami słów kluczowych (iteration, last_result, session, agenti tak dalej); todos_remaining uruchamia ponownie agenta, podczas gdy lista zadań do wykonania nadal zawiera otwarte elementy. Aby napisać własne, zaakceptuj te argumenty słowa kluczowego — na przykład lambda *, last_result, **kwargs: "DONE" not in last_result.text.

Agenty powłoki systemowej i działające w tle

Aby umożliwić agentowi uruchamianie poleceń powłoki, przekaż element shell_executor (na przykład LocalShellTool z pliku agent-framework-tools). Dodaje to narzędzie do wykonywania poleceń powłoki wymagające zatwierdzenia oraz dostawcę, który sprawdza środowisko systemu operacyjnego oraz powłoki. Wywołujący odpowiada za cykl życia executora:

from agent_framework_tools.shell import LocalShellTool, ShellPolicy

# A shell confined to a working directory. Commands require approval by default;
# the deny-list is a UX pre-filter, not a security boundary.
async with LocalShellTool(
    workdir="./working",
    confine_workdir=True,
    policy=ShellPolicy(denylist=[r"\brm\s+-rf\b", r"\bsudo\b"]),
) as shell:
    agent = create_harness_agent(
        client=client,
        shell_executor=shell,
    )

Aby włączyć delegowanie równoległe, przekaż sekwencję agentów działających w tle. Agent może delegować podzadania do współbieżnego wykonania:

agent = create_harness_agent(
    client=client,
    background_agents=[web_search_agent, code_agent],
)

Przykładową konsolą platformy .NET jest projekt Harness.Shared.Console. Jego punktem wejścia jest HarnessConsole.RunAgentAsync, przyjmujące agenta, symbol zastępczy monitu oraz opcjonalne HarnessConsoleOptions (obserwatorzy, obsługa poleceń z ukośnikiem, kolory trybu):

using Harness.Shared.Console;

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

Dostosuj go za pomocą własnych obserwatorów, formaterów narzędzi i modułów obsługi poleceń — albo utwórz jego fork jako bazę dla własnego środowiska terminalowego. Zobacz przykłady .NET uprzęży.

Przykładowa konsola języka Python to pakiet console znajdujący się obok przykładów harness. Jego punktem wejścia jest run_agent_async, który uruchamia aplikację opartą na tekście:

from console import run_agent_async

await run_agent_async(agent)

Całość jest zorganizowana wokół obserwatorów, komponentów interfejsu użytkownika i komend slash, a wszystko to można rozszerzać za pomocą klas bazowych ConsoleObserver, ToolCallFormatter i CommandHandler (zależy od textual i rich). Uruchom go w obecnej postaci albo skopiuj jako bazę dla własnego środowiska terminala. Zobacz przykłady harness dla języka Python.