Infraestrutura de Agente

Um arcabouço de agente, às vezes chamado de arcabouço de IA, é o arcabouço de execução que transforma um modelo de linguagem em um agente capaz de realizar tarefas. Ele coordena o modelo e as chamadas a ferramentas, gerencia o estado e o contexto da conversa, aplica políticas de aprovação e pode manter o agente avançando 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 em .NET, um Agent retornado por create_harness_agent em Python ou um *agent.Agent com suporte de provedor configurado com harness.AgentConfig em Go. 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. Os construtores de provedor Go controlam o loop de invocação de ferramentas. 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 em .NET e Python. Go requer composição explícita do provedor. 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 em .NET e Go; opt-in por meio de um provedor ou caminhos em Python. Habilidades do agente
Agentes em segundo plano Delegação paralela opcional para agentes filho nomeados em .NET e Python. Nenhum provedor de agente de plano de fundo Go empacotado. 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.

Dica

Para obter diretrizes do agente de codificação que ajudem a criar um aplicativo agente em Python, instale agent-framework-builder-python. Essa skill de agente de codificação externo é separada da capacidade Agent Skills de runtime listada na matriz.

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.

O acesso a arquivos usa o repositório fornecido como um workspace compartilhado por padrão. Para isolar arquivos pela ID da sessão ativa, habilite o acesso a arquivos com escopo de sessão:

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

Para o compartilhamento deliberado em sessões selecionadas, construa FileAccessProvider(store=file_store, scope="tenant-1") diretamente e adicione-o por meio de context_providers. O escopo é uma chave opaca que mapeia para uma pasta gerenciada pelo provedor, e não um caminho. O acesso com escopo falha ao ser fechado em vez de usar a raiz do repositório compartilhado quando nem uma ID de sessão ativa nem um escopo explícito estiverem disponíveis.

Use tool_name_prefix quando um agente tiver vários provedores de acesso a arquivos. O prefixo produz nomes como workspace_file_access_read e impede colisões de nome de ferramenta. Para provedores prefixados, use as fábricas de regras de aprovação específicas do provedor para que cada regra corresponda aos nomes gerados pelo provedor:

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() cria a regra equivalente para as ferramentas de leitura e de gravação. Mantenha a aprovação de gravação habilitada, a menos que o limite de armazenamento e as entradas da ferramenta sejam confiáveis.

Quando o acesso a arquivos estiver habilitado, use file_access_grep para localizar números de linha baseados em 1, file_access_read_lines inspecionar um intervalo inclusivo e file_access_replace_lines editar linhas inteiras. file_access_read_lines prefixa cada linha com seu número e uma guia; omita esse prefixo ao passar o texto da linha como expected_line. O texto esperado impede que um número de linha obsoleto ou incompatível edite a linha errada.

file_access_grep usa expressões regulares que não diferenciam maiúsculas de minúsculas, aceita padrões de até 256 caracteres e aplica um orçamento de 10 segundos a toda a pesquisa. Padrões inválidos ou longos e pesquisas que excedem o orçamento retornam um erro. Restringir o diretório ou o padrão antes de tentar novamente.

Important

file_access_grep retorna o texto da linha correspondente com seu terminador de linha. Uma implementação personalizada de AgentFileStore.search() deve retornar números de linha numerados a partir de 1 que se refiram às mesmas linhas que AgentFileStore.split_lines() no texto retornado por read().

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.

O pacote Go agent/harness reúne middleware, provedores de contexto e padrões de histórico para um agente normal com suporte de provedor. Chame harness.AgentConfig(harness.Config{}, agent.Config{...}), manipule seu erro e passe a configuração retornada para o construtor do provedor. Ele não introduz um tipo de agente separado ou um loop de execução de ferramentas.

Criar um agente de teste

O exemplo de composição configura um agente de harness com suporte do 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.",
        },
    )

Personalizar a composição

O assistente permite os seguintes valores padrão:

Componente Padrão do harness do Go
Planning Ferramentas de tarefas baseadas em sessão e modos de planejamento/execução, começando no modo de planejamento
Memória do arquivo Arquivos persistentes em agent-file-memory, com uma pasta de trabalho isolada por sessão
Habilidades Descoberta com suporte de arquivo do diretório de trabalho, excluindo a subárvore de memória
Pesquisa na Web Uma declaração de pesquisa na Web hospedada, a menos que o chamador já tenha fornecido uma
Approval Middleware de aprovação prévia e aprovação automática para ferramentas que exigem aprovação
History Histórico na memória com persistência por chamada de serviço
Injeção de mensagem Um agent.MessageInjector por agente
Rastreamento Instrumentação com suporte para chamadas de modelo, ferramentas e agentes

Use harness.Config para desabilitar componentes ou substituir a configuração. Desabilite a pesquisa na Web hospedada quando o serviço ou implantação selecionado não der suporte a ela. Os scripts de habilidade baseados em arquivo exigem um executor de script explicitamente configurado.

O auxiliar retém ferramentas de chamador, middleware, provedores de contexto e um provedor de histórico explicitamente configurado. Com uma implantação de modelo do Foundry, use DisableStoreOutput: true quando o histórico local controla a conversa.

As ferramentas de compactação, loop e shell não são adicionadas pelo auxiliar do Go. Configure-os explicitamente quando necessário. O provedor de delegação de agente em segundo plano empacotado descrito nos outros SDKs não está disponível no Go.

Consulte Criar um agente de harness do Go para configuração e o guia de configuração do harness do Go para padrões e substituições.

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.

O repositório Go inclui um exemplo de harness composto com tratamento de aprovação e uma demonstração da CLI de chat interativa separada. A CLI de chat usa um agente simples. Ele não é equivalente ao console do C# ou do harness do Python.

Próximas Etapas 

Planeje o trabalho e acompanhe as tarefas

Aprofunde-se

  • Última atualização em