Rámec pro agenty

Agentní rámec, někdy označovaný jako rámec AI, je běhová infrastruktura, která promění jazykový model v agenta schopného vykonávat úkoly. Řídí volání modelu a nástrojů, spravuje stav a kontext konverzace, uplatňuje schvalovací zásady a může udržovat agenta v postupu při plnění vícekrokového úkolu.

Agent Framework nabízí komplexně vybavené prostředí s jasně danými konvencemi pro výzkum, programování, analýzu dat a další dlouhotrvající úlohy. Poskytnete chatovacího klienta a přizpůsobíte jenom možnosti, které vaše aplikace potřebuje.

Architecture

Harness skládá existující stavební prvky Agent Framework namísto definování samostatného běhového prostředí agenta:

  1. Chatovací klient – připojí agenta k modelu.
  2. Kanál konverzace — přidává vyvolání funkce, vkládání zpráv, trvalé uchovávání historie pro každé volání služby a volitelnou kompakci.
  3. Poskytovatelé agentů a kontextů – přidejte pokyny, nástroje, paměť, stav úkolů, provozní režimy a volitelné možnosti.
  4. Middleware a dekorátory — přidat zpracování schvalování, observabilitu a volitelné omezené opakování.
  5. UX aplikace – streamuje odpovědi, zobrazuje průběh a shromažďuje vstupy, jako jsou schválení nástrojů.

Výsledný objekt zůstává normálním agentem Agent Framework: agent HarnessAgent, který je odvozený z AIAgent v .NET, Agent vrácený funkcí create_harness_agent v Pythonu nebo agent *agent.Agent podporovaný poskytovatelem, nakonfigurovaný pomocí harness.AgentConfig v Go. Jeho relace používají stejné abstrakce session a context provider jako ostatní agenti.

Matice možností využití

Schopnost Chování při využití Kanonické pokyny
Vyvolání funkce Povoleno s konfigurovatelným limitem iterace pro jednotlivé požadavky. Konstruktory zprostředkovatele Go řídí smyčku vyvolání nástrojů. Nástroje funkcí
Uchovávání historie pro jednotlivá volání služby Uchovává historii po každém volání modelu během běhu s voláním nástrojů. Zasedání
Stlačení Povoleno, když jsou v .NET a Python zadány limity tokenů nebo vlastní strategie. Go vyžaduje explicitní skládání providerů. Komprese
Sledování úkolů Ve výchozím nastavení povolena. Plánování a úkoly
Režimy agenta Režimy plánování a spouštění jsou ve výchozím nastavení povolené. Plánování a úkoly
Paměť souborů a přístup k souborům Paměť pro soubory relace je ve výchozím nastavení povolená; sdílený přístup k souborům je třeba povolit. Zprostředkovatelé kontextu
Schválení nástroje Ve výchozím nastavení jsou povolená stojící schválení a pravidla automatického schvalování. Schválení nástroje
OpenTelemetry Pozorovatelnost agenta je ve výchozím nastavení povolená. Pozorovatelnost
Vyhledávání na webu Ve výchozím nastavení přidáno tam, kde to vybraný chatovací klient podporuje. Vyhledávání na webu
Dovednosti agenta Ve výchozím nastavení je povoleno v .NET a Go; volitelně prostřednictvím poskytovatele nebo cest v Pythonu. Dovednosti agenta
Agenti na pozadí Volitelné paralelní delegování na pojmenované podřízené agenty v .NET a Python. Není k dispozici žádný balíčkovaný poskytovatel agenta na pozadí pro Go. Agenti na pozadí
Spouštění prostředí Je složen z balíčku shellu; factory v Pythonu jej může automaticky propojit. Nástroje prostředí
Smyčkování Volitelné vázané opětovné vyvolání řízené vyhodnocovači nebo predikáty. Smyčka agenta

Delegování agenta na pozadí je oddělené od odpovědí na pozadí spravovaných poskytovatelem. Agenti na pozadí spouštějí podřízené agenty pro delegované úlohy; odpovědi zpracovávané na pozadí zjišťují stav nebo obnovují jeden požadavek poskytovatele pomocí tokenu pro pokračování.

Tip

Pokud chcete získat pokyny pro programovacího agenta, které vám pomohou vytvořit testovací aplikaci v Pythonu, nainstalujte agent-framework-builder-python. Tato dovednost externího programovacího agenta je oddělena od funkce Agent Skills v runtime uvedené v matici.

Vytvořte agenta Harness

Balíček Microsoft.Agents.AI.Harness zpřístupňuje HarnessAgent v oboru názvů Microsoft.Agents.AI. Vytvořte ho z libovolného IChatClient objektu pomocí AsHarnessAgentpříkazu , nebo přímo zkonstruujte 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);

Pomocí HarnessAgentOptions nastavíte provozní pokyny na úrovni harnessu, pokyny specifické pro agenta a volby funkcí:

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 poskytuje výchozí pokyny k postroji. HarnessInstructions zobrazí se před ChatOptions.Instructions.

Přizpůsobení složení

Výchozí funkce mají konkrétní možnosti, včetně DisableTodoProvider, DisableAgentModeProvider, DisableFileMemory, DisableAgentSkillsProvider, DisableWebSearch, DisableToolAutoApproval, DisableOpenTelemetry a DisableCompaction.

Přidejte vlastní poskytovatele kontextu pomocí AIContextProviders. Povolte přístup k souborům pomocí FileAccessStore, delegování na pozadí pomocí BackgroundAgents a opakování pomocí LoopEvaluators.

Vytvořte agenta Harness

Továrna create_harness_agent vrátí plně nakonfigurovanou 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)

Nastavte pokyny na úrovni harnessu a pokyny specifické pro agenta samostatně:

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 poskytuje výchozí pokyny k postroji. harness_instructions zobrazí se před agent_instructions.

Přizpůsobení složení

Zakažte výchozí nastavení pomocí možností, jako jsou disable_todo, disable_mode, disable_file_memory, disable_web_search, disable_tool_auto_approval a disable_compaction.

Nahraďte integrované poskytovatele pomocí todo_provider nebo mode_provider a přidejte poskytovatele pomocí context_providers. Funkce jsou volitelné pomocí skills_provider nebo skills_paths; přístup k souborům, agenti běžící na pozadí, nástroje příkazového řádku a smyčky jsou rovněž volitelné.

Přístup k souborům ve výchozím nastavení používá zadané úložiště jako jeden sdílený pracovní prostor. Chcete-li izolovat soubory podle ID aktivní relace, povolte přístup k souborům omezený na relaci:

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

Pro cílené sdílení mezi vybranými relacemi vytvořte FileAccessProvider(store=file_store, scope="tenant-1") přímo a přidejte jej prostřednictvím context_providers. Obor je neprůhlený klíč, který se mapuje na složku spravovanou poskytovatelem, nikoli cestu. Omezený přístup skončí uzavřením přístupu namísto použití kořenového adresáře sdíleného úložiště, pokud není k dispozici ID aktivní relace ani explicitní rozsah.

Používá se tool_name_prefix , pokud má jeden agent více zprostředkovatelů přístupu k souborům. Předpona vytváří názvy, například workspace_file_access_read a zabraňuje kolizím názvů nástrojů. Pro providerů s předponou použijte faktorie pro pravidla schválení specifické pro providera, aby každé pravidlo odpovídalo názvům vygenerovaným tímto providerem:

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() vytvoří ekvivalentní pravidlo pro nástroje pro čtení i zápis. Ponechte schválení zápisu povolené, pokud hranice úložiště a vstupy nástrojů nejsou důvěryhodné.

Pokud je povolen přístup k souborům, použijte file_access_grep k vyhledání 1řádkových čísel, file_access_read_lines ke kontrole inkluzivního rozsahu a file_access_replace_lines k úpravě celých řádků. file_access_read_lines uvozuje každý řádek jeho číslem a tabulátorem; tuto předponu vynechejte při předávání textu řádku jako expected_line. Očekávaný text zabrání tomu, aby zastaralé nebo neodpovídající číslo řádku upravilo nesprávný řádek.

file_access_grep používá regulární výrazy nerozlišující malá a velká písmena, podporuje vzory o délce až 256 znaků a na celé vyhledávání uplatňuje časový limit 10 sekund. Neplatné nebo příliš dlouhé vzory a vyhledávání, které překračují limit, vrátí chybu. Před opakováním zužte adresář nebo vzor.

Důležité

file_access_grep vrátí odpovídající text řádku s ukončovacím znakem řádku. Vlastní implementace AgentFileStore.search() musí vracet čísla řádků číslovaná od 1, která odkazují na stejné řádky jako AgentFileStore.split_lines() v textu vráceném funkcí read().

Poznámka:

create_harness_agent je vydáno. Agenti běžící na pozadí, přístup k souborům a smyčky zůstávají experimentální a nástroje příkazového řádku pocházejí z předběžného balíčku agent-framework-tools.

Balíček Go agent/harness sdružuje middleware, zprostředkovatele kontextu a výchozí nastavení historie pro normálního agenta využívajícího provider. Zavolejte harness.AgentConfig(harness.Config{}, agent.Config{...}), zpracujte jeho chybu a předejte vrácenou konfiguraci konstruktoru zprostředkovatele. Nezavádí samostatný typ agenta ani smyčku spouštění nástrojů.

Vytvořte agenta Harness

Složený příklad konfiguruje agenta Harness založeného na 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.",
        },
    )

Přizpůsobení složení

Pomocník umožňuje následující výchozí hodnoty:

Component Výchozí harness Go
Planning Nástroje úkolů vázané na relaci a režimy plánování/provádění, spouštěné v režimu plánování
Souborová paměť Trvalé soubory v části agent-file-memory, s izolovanou pracovní složkou pro každou relaci
Dovednosti Zjišťování založené na souborech z pracovního adresáře s výjimkou podstromu paměti
Vyhledávání na webu Deklarace hostovaného webového vyhledávání, ledaže ji volající již zadal
Approval Middleware pro trvalé schválení a automatické schválení pro nástroje, které vyžadují schválení
History Historie v paměti s persistencí pro každé volání služby
Vkládání zpráv Na agenta agent.MessageInjector
Tracing Agent, nástroj a podporovaná instrumentace volání modelů

Slouží harness.Config k zakázání komponent nebo přepsání jejich konfigurace. Zakažte hostované vyhledávání na webu, pokud vybraná služba nebo nasazení tuto funkci nepodporuje. Skripty dovedností založené na souborech vyžadují explicitně nakonfigurovaný spouštěč skriptů.

Pomocná rutina uchovává nástroje volajícího, middleware, zprostředkovatele kontextu a explicitně nakonfigurovaného poskytovatele historie. Při nasazení modelu Foundry použijte DisableStoreOutput: true, když konverzaci spravuje místní historie.

Pomocná rutina Go nepřidá komprimaci, zacyklení a nástroje shellu. V případě potřeby je nakonfigurujte explicitně. Přibalený poskytovatel delegování pro agenta na pozadí popsaný v ostatních sadách SDK není v Go k dispozici.

Informace o nastavení najdete v tématu Vytvoření agenta harness pro Go a informace o výchozích nastaveních a přepsání hodnot v Průvodce konfigurací harness pro Go.

Ukázková uživatelská prostředí terminálu

Harness nepředepisuje aplikační rozhraní. Repozitář obsahuje ukázkové terminálové aplikace, které streamují výstup, zobrazují úkoly a aktuální režim, zobrazují výzvy ke schválení nástrojů a poskytují příkazy, jako jsou /todos, /mode a /exit.

Důležité

Tyto konzolové projekty jsou ukázky, nikoli dodávané součásti frameworku. Používejte je jako spustitelné příklady nebo jako výchozí bod pro vlastní prostředí terminálu.

Vstupním bodem ukázky .NET je HarnessConsole.RunAgentAsync:

using Harness.Shared.Console;

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

Přizpůsobte si ukázkovou aplikaci pomocí observerů, formátovačů nástrojů, obsluh příkazů a HarnessConsoleOptions. Podívejte se na ukázky .NET Harness.

Ukázka v Pythonu používá balíček console založený na frameworku Textual vedle ukázek Harness:

from console import run_agent_async

await run_agent_async(agent)

Přizpůsobte si ukázku pomocí pozorovatelů, formátovacích prvků, příkazů a součástí uživatelského rozhraní. Podívejte se na ukázky pro Python Harness.

Úložiště Go zahrnuje ukázku kompozitního harnessu se zpracováním schválení a samostatnou ukázku interaktivního chatovacího rozhraní příkazového řádku. Rozhraní příkazového řádku chatu používá jednoduchého agenta; nejedná se o ekvivalent konzole C# Harness nebo Python Harness.

Další kroky

Plánujte práci a sledujte úkoly

Zjistit více

  • Poslední aktualizace v