Arnês de Agente

Um sistema de suporte de agentes é a infraestrutura de execução que transforma um modelo de linguagem num agente capaz de executar tarefas. Gere chamadas de modelos e ferramentas, gere o estado e o contexto da conversa, aplica políticas de aprovação e pode manter o agente a progredir numa tarefa em várias etapas.

O Agent Framework fornece um Harness opinativo, com baterias, para investigação, programação, análise de dados e outros trabalhos de longa duração. Fornece um cliente de chat e personaliza apenas as capacidades que a sua aplicação precisa.

Architecture

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

  1. Cliente de chat — liga o agente a um modelo.
  2. Pipeline de chat — adiciona invocação de funções, injeção de mensagens, persistência do histórico de chamadas por serviço e compactação opcional.
  3. Fornecedores de agentes e contexto — adicionam instruções com âmbito de sessão, ferramentas, memória, estado de trabalho, modos de operação e capacidades opcionais.
  4. Middleware e decoradores — adicionar gestão de aprovações, observabilidade e ciclos limitados opcionais.
  5. Application UX — transmite respostas, apresenta progresso e recolhe inputs como aprovações de ferramentas.

O objeto resultante mantém-se um agente normal do Agent Framework: a HarnessAgent que deriva de AIAgent em .NET, ou um Agent retornado por create_harness_agent em Python. As sessões utilizam as mesmas abstrações de sessão e de fornecedor de contexto que as de outros agentes.

Matriz de capacidade de arnês

Capability Comportamento da cablagem Orientação canónica
Invocação de função Ativado com um limite configurável de iteração por pedido. Ferramentas de funções
Persistência do histórico de chamadas por serviço Mantém o histórico após cada invocação do modelo numa execução com chamada de ferramentas. Sessões
Compactação Ativado quando são fornecidos limites de tokens ou uma estratégia personalizada. Compactação
Acompanhamento de tarefas Ativado por padrão. Planeamento e tarefas
Modos de agente Os modos de planeamento e execução estão ativados por defeito. Planeamento e tarefas
Memória de ficheiros e acesso a ficheiros A memorização de ficheiros da sessão está ativada por defeito; o acesso partilhado a ficheiros tem de ser ativado. Fornecedores de contexto
Aprovação de ferramentas As aprovações permanentes e as regras de auto-aprovação estão ativadas por defeito. Aprovação de ferramentas
OpenTelemetry A observabilidade do agente está ativada por predefinição. Observabilidade
Pesquisa na Web Adicionado por defeito onde o cliente de chat selecionado o suporta. Pesquisa na Web
Competências do Agente Ativado por predefinição no .NET; em Python, tem de ser ativado explicitamente através de um provedor ou de caminhos. Competências de Agente
Agentes em segundo plano Delegação paralela opcional para agentes filhos nomeados. Agentes de fundo
Execução do shell Composto pelo pacote shell; a fábrica Python pode ligá-lo automaticamente. Ferramentas da shell
Looping Reinvocação limitada opcional acionada por avaliadores ou predicados. Ciclo do agente

A delegação de agentes em segundo plano é distinta das respostas em segundo plano geridas pelo fornecedor. Os agentes em segundo plano executam agentes subordinados em tarefas delegadas; as respostas em segundo plano consultam ou retomam um pedido a um fornecedor utilizando um token de continuação.

Crie um agente de arnês

O pacote Microsoft.Agents.AI.Harness expõe HarnessAgent no espaço de nomes Microsoft.Agents.AI. Crie um a partir de qualquer IChatClient com AsHarnessAgent, ou constrói 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);

Utilize HarnessAgentOptions para definir orientações operacionais ao nível do harness, instruções específicas do agente e opções de funcionalidade:

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 a orientação padrão do arnês. HarnessInstructions aparece antes de ChatOptions.Instructions.

Personalize a composição

As capacidades padrão incluem opções específicas, incluindo DisableTodoProvider, DisableAgentModeProvider, DisableFileMemory, DisableAgentSkillsProvider, DisableWebSearch, DisableToolAutoApproval, DisableOpenTelemetry e DisableCompaction.

Adicionar fornecedores de contexto personalizados com AIContextProviders. Opte pelo acesso a ficheiros com FileAccessStore, pela delegação em segundo plano com BackgroundAgents e pela repetição em ciclo com LoopEvaluators.

Crie um agente de arnês

A fábrica create_harness_agent devolve um Agent totalmente configurado:

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, em separado, instruções ao nível do harness 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 a orientação padrão do arnês. harness_instructions aparece antes de agent_instructions.

Personalize a composição

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

Substitua os fornecedores incorporados por todo_provider ou mode_provider, e adicione os fornecedores por context_providers. As capacidades são opcionais através de skills_provider ou skills_paths; o acesso a ficheiros, os agentes em segundo plano, as ferramentas da shell e a execução em ciclo também são opcionais.

Observação

create_harness_agent é libertado. Os agentes em segundo plano, o acesso a ficheiros e a execução em ciclo continuam a ser experimentais, e as ferramentas da shell provêm do pacote de pré-lançamento agent-framework-tools.

Observação

Uma versão empacotada do Go Harness não se encontra atualmente disponível. Criar diretamente os pacotes Go correspondentes para agente, fornecedor de contexto, compactação e middleware. Consulte o repositório Agent Framework Go para suporte atual.

Exemplo de UX do terminal

O Harness não prescreve uma interface de aplicação. O repositório inclui aplicações de terminal de exemplo que transmitem saída em fluxo, mostram as tarefas pendentes e o modo atual, apresentam pedidos de aprovação de ferramentas e fornecem comandos como /todos, /mode e /exit.

Importante

Estes projetos de consola são exemplos, não componentes de framework enviados. Usa-os como exemplos executáveis ou como ponto de partida para a tua própria experiência terminal.

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

using Harness.Shared.Console;

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

Personalize a amostra com observadores, formatadores de ferramentas, manipuladores de comandos e HarnessConsoleOptions. Veja os exemplos do .NET Harness.

O exemplo em Python utiliza o pacote console baseado em Textual, juntamente 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 de interface. Veja os exemplos do Python Harness.

O repositório não inclui atualmente uma amostra de terminal Go Harness embalada.

Passos seguintes

Planeia o trabalho e acompanha as tarefas

Aprofunde-se

  • Last updated on