Ügynök használata

Harness-ügynök létrehozása

A hám osztályként jelenik meg a HarnessAgentMicrosoft.Agents.AI névtérben (a Microsoft.Agents.AI.Harness csomagban). A legegyszerűbb módja, hogy bármely IChatClient elemből létrehozzon egyet, a(z) AsHarnessAgent bővítménymetódus használata:

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

Az ügynököt közvetlenül is létrehozhatja:

AIAgent agent = new HarnessAgent(chatClient);

Adjon meg egy HarnessAgentOptions elemet utasítások és eszközök biztosításához. A keretrendszerszintű utasítások (HarnessAgentOptions.HarnessInstructions) általános működési irányelveket írnak le, míg a feladatspecifikus utasítások a(z) ChatOptions.Instructions elemre kerülnek. A(z) HarnessAgent alapértelmezés szerint tesztkeret-szintű utasításokkal (HarnessAgent.DefaultInstructions) érkezik, de ezeket a(z) HarnessAgentOptions.HarnessInstructions használatával felülírhatja a sajátjaival.

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

Tömörítés engedélyezése

A tömörítés megakadályozza, hogy a hosszú eszközhívási ciklusok túllépjék a kontextusablak méretét. Ha nem a következtetési szolgáltatásban tárolt csevegési előzményeket használja, az alapértelmezett InMemoryChatHistoryProvider is ugyanazt a tömörítési szolgáltatót kapja, így a munkamenetben tárolt csevegési előzmények is tömörítésre kerülnek. Adja meg a környezetablak maximális méretét és a maximális kimeneti méretet az alapértelmezett token-budget-aware stratégia engedélyezéséhez:

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

Saját stratégiája használatához állítsa ezt: HarnessAgentOptions.CompactionStrategy; a tömörítés kikapcsolásához állítsa ezt: DisableCompaction = true.

Funkciók testreszabása és letiltása

Minden alapértelmezett képesség rendelkezik egy megfelelő letiltási jelzővel HarnessAgentOptions, így megtarthatja a kívánt folyamatot, és elvetheti a többit:

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

Egyéb jelzők közé tartozik a DisableFileAccess, a DisableAgentSkillsProvider, a DisableToolAutoApproval, valamint a DisableOpenTelemetry. Saját környezetszolgáltatókat is hozzáadhat a AIContextProviders használatával, és a képességszolgáltatót egyéni helyekre állíthatja be a AgentSkillsSource használatával.

Ismétlés, amíg kész nem lesz

Alapértelmezés szerint a heveder hívásonként egyszer fut. Adjon meg egy vagy több LoopEvaluator példányt az ügynök automatikus újrahívásához, amíg az értékelők el nem döntenek arról, hogy befejeződött (például amikor megjelenik egy befejezési jelölő, egy predikátum teljesül, vagy egy AI-bíró jóváhagyja):

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

A ciklus a legkülső Agent-dekorátorként van alkalmazva, így minden iteráció egy teljes, önálló, az eszközök által jóváhagyott és nyomon követett ügynökfuttatás.

Rendszerhéj- és háttérügynökök

Ahhoz, hogy az ügynök shellparancsokat futtathasson, adjon át egy ShellExecutor. Ez hozzáad egy jóváhagyáshoz kötött shell-végrehajtó eszközt, valamint egy szolgáltatót, amely az operációs rendszerre, a shellre és a munkakönyvtárra vonatkozó információkat a kontextusba illeszti:

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

A párhuzamos delegálás engedélyezéséhez adja át a háttérügynökök egy készletét. Az ügynök az egyidejű végrehajtáshoz le tudja adnia az altevékenységeket:

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

Harness-ügynök létrehozása

A harness a create_harness_agent gyári függvényként érhető el, amely egy csevegőkliensből egy teljesen konfigurált Agent-et állít össze. A legegyszerűbb űrlaphoz csak ügyfél szükséges:

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)

A keretrendszerszintű utasítások az általános működési irányelveket írják le, míg a feladatspecifikus utasítások a(z) agent_instructions elembe kerülnek. A harness alapértelmezés szerint harnessszintű utasításokat tartalmaz (DEFAULT_HARNESS_INSTRUCTIONS), amelyeket a(z) harness_instructions használatával felülírhatja. További eszközöket is átadhat:

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

Tömörítés engedélyezése

A tömörítés megakadályozza, hogy a hosszú eszközhívási ciklusok túllépjék a kontextusablak méretét. Adja meg a modell maximális környezeti ablakméretét és a maximális kimeneti méretet az alapértelmezett token-budget-aware stratégiák engedélyezéséhez:

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

Ha sem a tokenparaméter, sem az egyéni stratégia nincs megadva, a tömörítés automatikusan le lesz tiltva. Saját stratégiák használatához adja át a(z) before_compaction_strategy és/vagy after_compaction_strategy értéket; a tömörítés kifejezett kikapcsolásához állítsa be a(z) disable_compaction=True értéket.

Funkciók testreszabása és letiltása

Minden alapértelmezett képességhez tartozik egy megfelelő disable_* kulcsszóargumentum, így megtarthatja a kívánt részeket, és elvetheti a többit:

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
)

Más jelölők közé tartozik a disable_file_access, disable_tool_auto_approvalés disable_compactiona . A képességfelderítést a skills_paths használatával egyéni helyekre irányíthatja, és a context_providers használatával hozzáadhatja saját szolgáltatóit.

Ismétlés, amíg kész nem lesz

Alapértelmezés szerint a heveder hívásonként egyszer fut. Adjon át egy loop_should_continue predikátumot az ügynök automatikus újrahívásához, amíg a predikátum el nem dönti, hogy befejeződött-e. A loop_next_message használatával szabályozhatja az egyes további iterációkhoz tartozó utasítást, a loop_max_iterations használatával pedig korlátozhatja a lefutások számát:

from agent_framework import create_harness_agent, todos_remaining

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

A predikátum kulcsszóargumentumokkal (iteration, last_result, session, agent és így tovább) hívódik meg; todos_remaining újra futtatja az ügynököt, miközben a teendőlistáján még vannak nyitott elemek. Ha sajátot ír, fogadja el ezeket a kulcsszó-argumentumokat – például lambda *, last_result, **kwargs: "DONE" not in last_result.text.

Rendszerhéj- és háttérügynökök

Ha lehetővé szeretné tenni az ügynök számára a rendszerhéjparancsok futtatását, adjon meg egy shell_executor (például LocalShellTool innen származó agent-framework-tools) parancsot. Ez hozzáad egy jóváhagyáshoz kötött parancsértelmező-végrehajtó eszközt, valamint egy olyan szolgáltatót, amely felméri az operációs rendszert és a parancsértelmező környezetet. A hívó felel a végrehajtó életciklusáért:

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

A párhuzamos delegálás engedélyezéséhez adja át a háttérügynökök listáját. Az ügynök az egyidejű végrehajtáshoz le tudja adnia az altevékenységeket:

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

A .NET konzolos mintaprojekt a Harness.Shared.Console projekt. A belépési pontja a HarnessConsole.RunAgentAsync, amely az ügynököt, egy helyőrző promptot és egy opcionális HarnessConsoleOptions paramétert fogad el (megfigyelők, perjelparancs-kezelők, üzemmódszínek):

using Harness.Shared.Console;

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

Testre szabhatja saját megfigyelőivel, eszközformázóival és parancskezelőivel – vagy elágazásként saját terminálélményének alapjaként. Tekintse meg a .NET harness mintákat.

A Python-mintakonzol a harnessminták melletti console csomag. A belépési pontja run_agent_async, amely egy Textual-alapú alkalmazást futtat:

from console import run_agent_async

await run_agent_async(agent)

Megfigyelők, felhasználói felület-összetevők és perjelparancsok köré épül, amelyek mind bővíthetők a ConsoleObserver, ToolCallFormatter és CommandHandler alaposztályokon keresztül (a textual és rich elemektől függ). Futtassa változtatás nélkül, vagy másolja le a saját terminálélménye alapjául. Tekintse meg a Python-mintapéldákat.