Infraestrutura de Agente

Um arcabouço de agente é o arcabouço de execução que transforma um modelo de linguagem em um agente capaz de realizar tarefas. Ele aciona o modelo e as chamadas de ferramentas, gerencia o estado e o contexto da conversa, aplica políticas de aprovação e pode fazer o agente avançar ao longo de uma tarefa de várias etapas.

O Agent Framework fornece uma estrutura dogmática incluída em baterias para pesquisa, codificação, análise de dados e outros trabalhos de longa execução. Você fornece um cliente de chat e personaliza apenas os recursos de que seu aplicativo precisa.

Architecture

O Harness compõe os blocos de construção existentes do Agent Framework em vez de definir um runtime de agente separado:

  1. Cliente de chat – conecta o agente a um modelo.
  2. Pipeline de chat – adiciona invocação de função, injeção de mensagem, persistência de histórico de chamadas por serviço e compactação opcional.
  3. Provedores de agente e contexto – adicione instruções, ferramentas, memória, estado todo, modos operacionais e recursos opcionais no escopo da sessão.
  4. Middleware e decoradores – adicione tratamento de aprovação, observabilidade e loops limitados opcionais.
  5. UX do aplicativo — transmite respostas, exibe progresso e coleta entradas, como aprovações de ferramentas.

O objeto resultante continua sendo um agente normal do Agent Framework: um HarnessAgent que deriva de AIAgent .NET ou um Agent retornado por create_harness_agent Python. Suas sessões usam as mesmas abstrações de sessão e de provedor de contexto usadas por outros agentes.

Matriz de funcionalidade do Harness

Capability Comportamento do harness Diretrizes canônicas
Invocação de função Habilitado com um limite de iteração configurável por solicitação. Ferramentas de função
Persistência do histórico de chamadas por serviço Mantém o histórico de forma persistente após cada chamada ao modelo em uma execução com chamada de ferramentas. Sessões
Compactação Habilitado quando os limites de token ou uma estratégia personalizada são fornecidos. Compactação
Rastreamento todo Habilitado por padrão. Planejamento e tarefas
Modos de agente Os modos de plano e execução são habilitados por padrão. Planejamento e tarefas
Memória do arquivo e acesso a arquivos A memória do arquivo de sessão está habilitada por padrão; O acesso a arquivos compartilhados é opt-in. Provedores de contexto
Aprovação da ferramenta As aprovações permanentes e as regras de aprovação automática são habilitadas por padrão. Aprovação da ferramenta
OpenTelemetry A observabilidade do agente é habilitada por padrão. Observabilidade
Pesquisa na Web Adicionado por padrão em que o cliente de chat selecionado dá suporte a ele. Pesquisa na Web
Habilidades do Agente Habilitado por padrão no .NET; em Python, ativado por meio de um provedor ou de caminhos. Habilidades do agente
Agentes em segundo plano Delegação paralela opcional para agentes filhos nomeados. Agentes em segundo plano
Execução do shell Composto do pacote de shell; a fábrica de Python pode conectá-la automaticamente. Ferramentas do Shell
Loop Reinvocação limitada opcional orientada por avaliadores ou predicados. Looping de agente

A delegação de agente em segundo plano é separada das respostas em segundo plano gerenciadas pelo provedor. Os agentes em segundo plano executam agentes secundários para tarefas delegadas; as respostas em segundo plano sondam ou retomam uma solicitação a um provedor usando um token de continuação.

Criar um agente de teste

O pacote Microsoft.Agents.AI.Harness expõe HarnessAgent no namespace Microsoft.Agents.AI. Crie um a partir de qualquer IChatClient com AsHarnessAgent, ou construa HarnessAgent diretamente:

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

Use HarnessAgentOptions para definir orientações operacionais no nível da estrutura, instruções específicas do agente e opções de recurso:

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 fornece as orientações da estrutura padrão. HarnessInstructions aparece antes ChatOptions.Instructions.

Personalizar a composição

Os recursos padrão têm opções específicas, incluindo DisableTodoProvider, DisableAgentModeProvider, DisableFileMemory, DisableAgentSkillsProvider, DisableWebSearch, DisableToolAutoApproval, DisableOpenTelemetry e DisableCompaction.

Adicionar provedores de contexto personalizados com AIContextProviders. Ative o acesso a arquivos com FileAccessStore, a delegação em segundo plano com BackgroundAgents e o loop com LoopEvaluators.

Criar um agente de teste

A fábrica create_harness_agent retorna um(a) Agent totalmente configurado(a):

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)

Defina separadamente instruções no nível da estrutura e instruções específicas do agente:

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 fornece as orientações da estrutura padrão. harness_instructions aparece antes agent_instructions.

Personalizar a composição

Desative os padrões com opções como disable_todo, disable_mode, disable_file_memory, disable_web_search, disable_tool_auto_approval e disable_compaction.

Substitua provedores internos por todo_provider ou mode_provider, e adicione provedores com context_providers. As habilidades dependem de adesão por meio de skills_provider ou skills_paths; o acesso a arquivos, agentes em segundo plano, ferramentas de shell e execução em loop também dependem de adesão.

Note

create_harness_agent foi lançado. Os agentes em segundo plano, o acesso a arquivos e a execução em loop permanecem experimentais, e as ferramentas de shell vêm do pacote de pré-lançamento agent-framework-tools.

Note

No momento, não há um Go Harness pré-empacotado disponível. Criar diretamente os pacotes correspondentes de agente Go, provedor de contexto, compactação e middleware. Consulte o repositório Agent Framework Go para obter suporte atual.

Experiência do usuário de terminal de exemplo

O Harness não prescreve uma interface de aplicativo. O repositório inclui aplicativos de terminal de exemplo que transmitem a saída em tempo real, exibem tarefas pendentes e o modo atual, apresentam prompts de aprovação de ferramentas e fornecem comandos como /todos, /mode e /exit.

Important

Esses projetos de console são exemplos, não componentes de estrutura fornecidos. Use-os como exemplos executáveis ou como ponto de partida para sua própria experiência de terminal.

O ponto de entrada de exemplo do .NET é HarnessConsole.RunAgentAsync:

using Harness.Shared.Console;

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

Personalize o exemplo com observadores, formatadores de ferramenta, manipuladores de comandos e HarnessConsoleOptions. Veja os exemplos do .NET Harness.

O exemplo em Python usa o pacote console baseado em Textual, junto com os exemplos do Harness:

from console import run_agent_async

await run_agent_async(agent)

Personalize o exemplo com observadores, formatadores, comandos e componentes da interface do usuário. Veja os exemplos do Python Harness.

No momento, o repositório não inclui um exemplo de terminal do Go Harness empacotado.

Próximas Etapas 

Planeje o trabalho e acompanhe as tarefas

Aprofunde-se

  • Last updated on