Rámec pro agenty

Vytvoření agenta Harness

Harness je k dispozici jako třída HarnessAgent v oboru názvů Microsoft.Agents.AI (balíček Microsoft.Agents.AI.Harness). Nejjednodušší způsob, jak ji vytvořit, je z libovolného IChatClient pomocí rozšiřující metody 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 můžete také vytvořit přímo:

AIAgent agent = new HarnessAgent(chatClient);

Poskytněte možnost HarnessAgentOptions, jak dodat pokyny a nástroje. Pokyny na úrovni harnessu (HarnessAgentOptions.HarnessInstructions) popisují obecné provozní zásady, zatímco pokyny specifické pro jednotlivé úkoly patří do ChatOptions.Instructions. HarnessAgent se dodává s výchozími pokyny na úrovni harnessu (HarnessAgent.DefaultInstructions), ale můžete je však nahradit vlastními pomocí 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)],
    },
});

Povolení komprimace

Kompaktace zabraňuje tomu, aby dlouhé smyčky volání nástrojů přeplnily kontextové okno. Pokud nepoužíváte historii chatu uloženou službou inference, používá výchozí InMemoryChatHistoryProvider také stejného poskytovatele komprese, aby se komprimovala i historie chatu uložená v relaci. Zadejte maximální velikost kontextového okna i maximální velikost výstupu, abyste povolili výchozí strategii podporující rozpočet tokenů:

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

Chcete-li použít vlastní strategii, nastavit HarnessAgentOptions.CompactionStrategy; vypnout komprimace, nastavit DisableCompaction = true.

Přizpůsobení a zakázání funkcí

Každá výchozí funkce má na HarnessAgentOptions odpovídající příznak pro zakázání, takže si můžete ponechat pipeline, kterou chcete, a ostatní vypustit:

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

Mezi další příznaky patří DisableFileAccess, DisableAgentSkillsProvider, DisableToolAutoApproval a DisableOpenTelemetry. Můžete také přidat vlastní zprostředkovatele kontextu prostřednictvím AIContextProviders a nasměrovat poskytovatele dovedností na vlastní místa prostřednictvím AgentSkillsSource.

Opakovat, dokud není hotovo

Ve výchozím nastavení se testovací modul spustí jednou při každém spuštění. Zadejte jednu nebo více instancí LoopEvaluator, aby se agent automaticky znovu spouštěl, dokud evaluátory nerozhodnou, že je hotovo (například když se zobrazí indikátor dokončení, je splněn predikát nebo to schválí AI rozhodčí):

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

Smyčka je použita jako nejvnější dekorátor agenta, takže každá iterace představuje úplné samostatné spuštění agenta, které je nezávisle schválené nástrojem a trasované.

Shell a agenti na pozadí

Pokud chcete, aby agent spustil příkazy prostředí, předejte příkazy ShellExecutor. Tím se přidává nástroj pro spouštění příkazů v shellu podmíněný schválením a poskytovatel, který do kontextu vkládá informace o operačním systému, shellu a pracovním adresáři:

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

Chcete-li povolit paralelní delegování, předejte sadu agentů na pozadí. Agent může předávat dílčí úlohy k souběžnému zpracování:

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

Vytvoření agenta Harness

Harness je k dispozici jako tovární funkce create_harness_agent, která z chatovacího klienta sestaví plně nakonfigurovaný objekt Agent. Nejjednodušší forma vyžaduje pouze 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)

Pokyny na úrovni harnessu popisují obecné provozní zásady, zatímco pokyny pro konkrétní úkoly patří do agent_instructions. Harness se dodává s výchozími pokyny na úrovni harnessu (DEFAULT_HARNESS_INSTRUCTIONS), které můžete přepsat pomocí harness_instructions. Můžete také předat další nástroje:

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

Povolení komprimace

Kompaktace zabraňuje tomu, aby dlouhé smyčky volání nástrojů přeplnily kontextové okno. Zadejte maximální velikost kontextového okna modelu i maximální velikost výstupu, abyste povolili výchozí strategie podporující rozpočet tokenů:

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

Pokud není k dispozici parametr tokenu ani vlastní strategie, komprimace se automaticky zakáže. Chcete-li použít vlastní strategie, předejte before_compaction_strategy a/nebo after_compaction_strategy; chcete-li kompakci výslovně vypnout, nastavte disable_compaction=True.

Přizpůsobení a zakázání funkcí

Každá výchozí funkce má odpovídající disable_* argument klíčového slova, takže můžete zachovat požadované části a zbytek vypustit:

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
)

Mezi další příznaky patří disable_file_access, disable_tool_auto_approval a disable_compaction. Zjišťování dovedností můžete pomocí skills_paths nasměrovat na vlastní umístění a pomocí context_providers přidat vlastní poskytovatele.

Opakovat, dokud není hotovo

Ve výchozím nastavení se testovací modul spustí jednou při každém spuštění. loop_should_continue Předejte predikát, který znovu vyvolá agenta automaticky, dokud se predikát nerozhodne, že se dokončí. Pomocí loop_next_message nastavíte prompt pro každou následnou iteraci a pomocí loop_max_iterations stanovíte horní limit počtu průchodů:

from agent_framework import create_harness_agent, todos_remaining

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

Predikát se vyvolá pomocí argumentů klíčových slov (iteration, last_result, session, agentatd.), todos_remaining znovu spustí agenta, zatímco jeho seznam úkolů má stále otevřené položky. Pokud chcete napsat vlastní, přijměte tyto argumenty klíčových slov , lambda *, last_result, **kwargs: "DONE" not in last_result.textnapříklad .

Shell a agenti na pozadí

Chcete-li agentovi umožnit spouštět příkazy shellu, předejte parametr shell_executor (například LocalShellTool z agent-framework-tools). Tím se přidává nástroj pro spouštění příkazů v shellu, který vyžaduje schválení, a poskytovatel, který zkoumá operační systém a prostředí shellu. Volající vlastní životní cyklus exekutoru:

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

Pokud chcete povolit paralelní delegování, předejte posloupnost agentů na pozadí. Agent může předávat dílčí úlohy k souběžnému zpracování:

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

Ukázkový konzolový projekt .NET je Harness.Shared.Console. Jeho vstupním bodem je HarnessConsole.RunAgentAsync, který přijímá vašeho agenta, zástupný prompt a volitelné HarnessConsoleOptions (pozorovatele, obslužné rutiny příkazů se lomítkem, barvy režimů):

using Harness.Shared.Console;

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

Přizpůsobte si ho vlastními observery, formátovači nástrojů a obsluhami příkazů — nebo z něj vytvořte fork jako základ pro vlastní terminálové prostředí. Podívejte se na ukázky rozhraní .NET harness.

Ukázka konzole v Pythonu je balíček console vedle ukázek harnessu. Jeho vstupním bodem je run_agent_async, který spouští aplikaci založenou na textu:

from console import run_agent_async

await run_agent_async(agent)

Je uspořádán kolem pozorovatelů, komponent uživatelského rozhraní a slash příkazů, které lze všechny rozšiřovat prostřednictvím základních tříd ConsoleObserver, ToolCallFormatter a CommandHandler (založeno na textual a rich). Spusťte ho as-isnebo ho zkopírujte jako základ pro vlastní prostředí terminálu. Podívejte se na příklady Python harness.