Cablaggi dell'agente

Un'infrastruttura per agenti è la struttura di supporto che trasforma un modello di linguaggio in un agente in grado di fare davvero delle cose. Un modello da solo può generare solo testo. Per consentirgli di chiamare gli strumenti, svolgere attività articolate in più passaggi, ricordare ciò che ha già fatto e continuare finché il lavoro non è completato, è necessario un runtime attorno al modello, e questo runtime è l'harness.

Un harness guida l'agente: esegue il ciclo che chiama il modello ed esegue gli strumenti che il modello richiede, gestisce la cronologia delle conversazioni e il contesto in modo che il modello rimanga entro i limiti, applichi i criteri di approvazione e di sicurezza prima dell'esecuzione delle azioni e mantiene l'agente procedendo verso il completamento dell'attività. Gli assistenti di codifica e gli agenti autonomi sono tutti basati su una forma di imbracatura, ovvero il motore avvolto intorno al modello.

Agent Framework offre un'imbracatura pronta per non dover creare questo scaffolding. Si tratta di un agente pronto all’uso, completo di tutto il necessario, che incapsula un client di chat con una pipeline agentica completa — invocazione di funzioni, gestione del contesto e un insieme selezionato di strumenti e provider — ottimizzato per attività autonome di lunga durata, come ricerca, programmazione, analisi dei dati e automazione di attività generiche.

Si fornisce ancora il proprio client di chat e si configurano solo le parti che si desidera modificare. Tutto il resto ha un valore predefinito ragionevole che è possibile disabilitare o personalizzare.

Internamente, Agent Framework harness è un agente basato su client di chat (Agent in Python e ChatClientAgent in C#) con un set di funzionalità di Agent Framework aggiunte. Tutte queste funzionalità sono disponibili anche come funzionalità autonome in Agent Framework.

Che cosa costituisce l'harness di Agent Framework

Agent Framework harness aggrega le funzionalità seguenti in un singolo agente. Ogni opzione è abilitata per impostazione predefinita (a meno che non sia specificato come facoltativo) e può essere disabilitata o personalizzata singolarmente.

Capability Description
Chiamata di funzione Ciclo di chiamata automatico degli strumenti con un limite di iterazione configurabile.
Persistenza della cronologia delle chiamate per servizio La cronologia della chat viene salvata in modo persistente dopo ciascuna chiamata al modello, consentendo il ripristino dopo un arresto anomalo e l’ispezione durante l’esecuzione.
Compattazione La compattazione della finestra di contesto impedisce che lunghi cicli di chiamate agli strumenti mandino in overflow la finestra di contesto. Attivo quando viene fornito un budget di token (o una strategia personalizzata).
Provider Todo Elenco di todo permanente usato dall'agente per tenere traccia dei piani in più passaggi.
Provider in modalità agente Pianificazione/esecuzione/modalità personalizzata che controlla il funzionamento dell'agente.
Provider di memoria file Memoria della sessione basata su file per note e artefatti che vengono mantenuti tra turni.
Provider di accesso ai file Strumenti per file di lettura e scrittura limitati a una directory di lavoro.
Approvazione degli strumenti "Non chiedere più", oltre a regole di approvazione permanente e all'approvazione automatica euristica per un'esecuzione sicura e senza supervisione.
OpenTelemetry Osservabilità integrata in linea con le convenzioni semantiche dell'IA generativa.
Ricerca Web Strumento di ricerca Web ospitato aggiunto per impostazione predefinita.
Provider di competenze(facoltativo) Individua e carica progressivamente le competenze dell'agente dal file system.
Agenti in background(facoltativo) Delegare il lavoro parallelo agli agenti secondari in background.
Ambiente shell(facoltativo) Esecuzione di comandi shell e rilevamento di sistema operativo, shell e directory di lavoro.
Ripetizione(facoltativo) Richiamare nuovamente l'agente fino a quando non viene soddisfatta una condizione di completamento.

Creazione di un agente di cablaggio

L'imbracatura è esposta come la classe HarnessAgent nello spazio dei nomi Microsoft.Agents.AI (il pacchetto Microsoft.Agents.AI.Harness). Il modo più semplice per crearne uno è a partire da un qualsiasi IChatClient usando il metodo di estensione 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);

È anche possibile costruire direttamente l'agente:

AIAgent agent = new HarnessAgent(chatClient);

Utilizzare un HarnessAgentOptions per fornire istruzioni e strumenti. Le istruzioni a livello di harness (HarnessAgentOptions.HarnessInstructions) descrivono le linee guida generali per il funzionamento, mentre le istruzioni specifiche dell'attività sono disponibili in ChatOptions.Instructions. HarnessAgent viene fornito con istruzioni predefinite a livello di harness (HarnessAgent.DefaultInstructions), ma puoi sovrascriverle con le tue tramite 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)],
    },
});

Abilitazione della compattazione

La compattazione evita che lunghi cicli di chiamate agli strumenti superino la finestra di contesto. Quando non si utilizza la cronologia chat archiviata nel servizio di inferenza, anche il valore predefinito InMemoryChatHistoryProvider viene fornito con lo stesso provider di compattazione, in modo che venga compattata anche la cronologia chat archiviata nella sessione. Specificare sia una dimensione massima della finestra di contesto sia una dimensione massima dell'output per abilitare la strategia predefinita basata sul budget di token:

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

Per usare la propria strategia, impostare HarnessAgentOptions.CompactionStrategy; per disattivare la compattazione, impostare DisableCompaction = true.

Personalizzazione e disabilitazione delle funzionalità

Ogni funzionalità predefinita ha un flag di disabilitazione corrispondente in HarnessAgentOptions, in modo da poter mantenere la pipeline desiderata ed eliminare il resto:

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

Altri flag includono DisableFileAccess, DisableAgentSkillsProvider, DisableToolAutoApprovale DisableOpenTelemetry. È anche possibile aggiungere provider di contesto personalizzati tramite AIContextProviders e puntare il provider di competenze in posizioni personalizzate tramite AgentSkillsSource.

Ripetizione fino al completamento

Per impostazione predefinita, il test harness viene eseguito una volta a ogni invocazione. Fornire una o più LoopEvaluator istanze per richiamare nuovamente l'agente automaticamente fino a quando gli analizzatori non decidono di terminare (ad esempio, quando viene visualizzato un marcatore di completamento, viene soddisfatto un predicato o un giudice di intelligenza artificiale approva):

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

Il ciclo viene applicato come decoratore più esterno di Agent, quindi ogni iterazione è un'esecuzione completa dell'agente, approvata dagli strumenti e tracciata in modo indipendente.

Shell e agenti in background

Per consentire all'agente di eseguire i comandi della shell, passare un oggetto ShellExecutor. Questo aggiunge uno strumento di esecuzione di comandi shell soggetto ad approvazione e un provider che inietta nel contesto informazioni sul sistema operativo, sulla shell e sulla directory di lavoro:

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

Per abilitare la delega parallela, passa un insieme di agenti in background. L'agente può eseguire attività secondarie per l'esecuzione simultanea:

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

Creazione di un agente di cablaggio

Il componente è esposto tramite la funzione factory create_harness_agent, che assembla un Agent completamente configurato a partire da un client di chat. Il formato più semplice richiede solo un client:

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)

Le istruzioni a livello di harness descrivono le linee guida generali per il funzionamento, mentre le istruzioni specifiche dell'attività sono disponibili in agent_instructions. L'harness viene fornito con istruzioni predefinite a livello di harness (DEFAULT_HARNESS_INSTRUCTIONS), che è possibile sovrascrivere tramite harness_instructions. È anche possibile passare strumenti aggiuntivi:

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

Abilitazione della compattazione

La compattazione evita che lunghi cicli di chiamate agli strumenti superino la finestra di contesto. Fornisci sia la dimensione massima della finestra di contesto del modello sia una dimensione massima dell'output per abilitare le strategie predefinite basate sul budget dei token:

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

Quando non viene fornito alcun parametro token né una strategia personalizzata, la compattazione viene disabilitata automaticamente. Per usare strategie personalizzate, passare before_compaction_strategy e/o after_compaction_strategy; per disattivare la compattazione in modo esplicito, impostare disable_compaction=True.

Personalizzazione e disabilitazione delle funzionalità

Ogni funzionalità predefinita ha un corrispondente argomento con parola chiave disable_*, così puoi mantenere le parti che vuoi e scartare il resto:

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
)

Altri flag includono disable_file_access, disable_tool_auto_approvale disable_compaction. È possibile puntare l'individuazione delle competenze in posizioni personalizzate con skills_paths e aggiungere provider personalizzati con context_providers.

Ripetizione fino al completamento

Per impostazione predefinita, il test harness viene eseguito una volta a ogni invocazione. Passare un loop_should_continue predicato per richiamare nuovamente l'agente automaticamente fino a quando il predicato non decide che è terminato. Usare loop_next_message per controllare il prompt di ogni iterazione successiva e loop_max_iterations per limitare il numero di passaggi:

from agent_framework import create_harness_agent, todos_remaining

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

Il predicato viene richiamato con argomenti di parola chiave (iteration, last_result, sessionagent, e così via). todos_remaining Esegue nuovamente l'agente mentre il relativo elenco di attività contiene ancora elementi aperti. Per scrivere i propri argomenti, accettare tali argomenti di parole chiave, lambda *, last_result, **kwargs: "DONE" not in last_result.textad esempio .

Shell e agenti in background

Per consentire all'agente di eseguire comandi shell, passa shell_executor (ad esempio, LocalShellTool da agent-framework-tools). Questo aggiunge uno strumento di esecuzione della shell soggetto ad approvazione e un provider che rileva l'ambiente del sistema operativo e della shell. Il chiamante gestisce il ciclo di vita dell'executor:

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

Per abilitare la delega parallela, fornire una sequenza di agenti in background. L'agente può eseguire attività secondarie per l'esecuzione simultanea:

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

Annotazioni

Il supporto per i cablaggi degli agenti sarà presto disponibile. Vedere il repository di Agent Framework Go per lo stato più aggiornato.

Pianificare ed eseguire il flusso di lavoro

Il fornitore della modalità agente consente uno stile di lavoro in due fasi che si abbina naturalmente all'elenco delle attività:

  1. Modalità pianificazione — interattiva. L'agente pone domande chiare, crea un elenco di todo e un piano e ottiene l'approvazione prima di svolgere un lavoro significativo.
  2. Modalità di esecuzione : autonoma. L'agente porta avanti le attività in modo indipendente, riportando i progressi man mano che procede.

Anche se il provider di modalità include modalità di pianificazione ed esecuzione come modalità predefinite, queste possono essere sostituite con altre modalità e istruzioni personalizzate per ogni modalità, se necessario.

Esperienza utente del terminale di esempio

L'imbracatura ti dà un agente in grado, ma non prescrive come le persone interagiscono con esso. Per illustrare l'interfaccia end-to-end di harness, è inclusa un'esperienza utente terminale di esempio, una console interattiva (TUI) che trasmette l'output dell'agente, mostra l'elenco di todo e la modalità corrente, espone i prompt di approvazione degli strumenti e supporta comandi barra come /todos, /modee ./exit

Importante

Questi progetti console sono esempi, non fanno parte del framework fornito. Sono intenzionalmente indipendenti in modo da poterli eseguire as-is per esplorare l'imbracatura o copiarli nel proprio progetto come punto di partenza per creare un'esperienza terminale personalizzata.

Il progetto Harness.Shared.Console è la console di esempio .NET. Il punto di ingresso è HarnessConsole.RunAgentAsync, che accetta il tuo agente, un prompt segnaposto e un HarnessConsoleOptions facoltativo (osservatori, gestori dei comandi slash, colori delle modalità):

using Harness.Shared.Console;

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

Personalizzalo con i tuoi osservatori, formattatori degli strumenti e gestori di comandi, oppure fanne un fork come base per la tua esperienza terminale. Vedere gli esempi di .NET harness.

La console di esempio di Python si trova nel pacchetto console, accanto agli esempi dell'harness. Il punto di ingresso è run_agent_async, che esegue un'app basata su Textual:

from console import run_agent_async

await run_agent_async(agent)

È organizzato intorno a osservatori, componenti dell'interfaccia utente e comandi barra, tutti estendibili tramite le ConsoleObserverclassi base , ToolCallFormattere CommandHandler (dipende da textual e rich). Eseguilo così com'è oppure copialo come base per la tua esperienza nel terminale. Vedere gli esempi di Python harness.

Passaggi successivi

CodeAct

Approfondimento

  • Last updated on