Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Uma estrutura de agente, por vezes também designada estrutura de IA, é a infraestrutura de execução que transforma um modelo de linguagem num agente capaz de executar tarefas. Isso controla as chamadas ao modelo e às ferramentas, gere o estado da conversa e o contexto, aplica políticas de aprovação e pode manter o agente a avançar ao longo de uma tarefa com 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:
- Cliente de chat — liga o agente a um modelo.
- 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.
- 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.
- Middleware e decoradores — adicionar gestão de aprovações, observabilidade e ciclos limitados opcionais.
- 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: um HarnessAgent que deriva de AIAgent em .NET, um Agent devolvido por create_harness_agent em Python, ou um *agent.Agent suportado por fornecedor configurado com harness.AgentConfig em Go. 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. Os construtores do Go provider são responsáveis pelo ciclo de invocação da ferramenta. | 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 os limites dos tokens ou uma estratégia personalizada são fornecidos em .NET e Python. Go requer uma composição explícita de providers. | 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 defeito em .NET e Go; opt-in através de um provider ou caminhos em Python. | Competências de Agente |
| Agentes em segundo plano | Delegação paralela opcional a agentes filhos nomeados em .NET e Python. Não existe fornecedor empacotado de agente Go em segundo plano. | 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.
Tip
Para orientações sobre agentes de codificação que ajudam a compor uma aplicação de harness em Python, instale agent-framework-builder-python.
Esta Skill de agente de codificação externa é separada da capacidade Skills de Agente em tempo de execução listada na matriz.
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.
O acesso a ficheiros utiliza o armazenamento fornecido como um único espaço de trabalho partilhado por defeito. Para isolar ficheiros pelo ID ativo da sessão, ative o acesso a ficheiros com âmbito 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 partilhar intencionalmente entre sessões selecionadas, construa FileAccessProvider(store=file_store, scope="tenant-1") diretamente e adicione-o através de context_providers. O scope é uma chave opaca que corresponde a uma pasta gerida pelo fornecedor, não a um caminho. O acesso com escopo falha ao fechar em vez de usar a raiz do armazenamento partilhado quando nem um ID de sessão ativo nem um âmbito explícito estão disponíveis.
Utilize tool_name_prefix quando um agente tem múltiplos fornecedores de acesso a ficheiros. O prefixo produz nomes como workspace_file_access_read e evita conflitos de nomes de ferramentas. Para fornecedores prefixados, utilize as fábricas de regras de aprovação específicas de cada fornecedor para que cada regra corresponda aos nomes gerados por esse fornecedor:
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 tanto para ferramentas de leitura como de escrita. Mantenha a aprovação de escrita ativada, a menos que o limite de armazenamento e as entradas da ferramenta sejam confiáveis.
Quando o acesso ao ficheiro estiver ativado, utilize file_access_grep para encontrar números de linha a partir de 1, file_access_read_lines para inspecionar um intervalo inclusivo e file_access_replace_lines para editar linhas inteiras.
file_access_read_lines prefixa cada linha com o seu número e uma tabulação; 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 utiliza expressões regulares insensíveis a maiúsculas, aceita padrões até 256 caracteres e aplica um orçamento de 10 segundos a toda a pesquisa. Padrões e consultas inválidos, ou demasiado longos e que excedam o orçamento, geram um erro. Estreite o diretório ou padrão antes de tentar novamente.
Importante
file_access_grep devolve o texto da linha correspondente, incluindo o respetivo terminador de linha. Uma implementação personalizada AgentFileStore.search() deve devolver números de linha baseados em 1 que endereçam as mesmas linhas que AgentFileStore.split_lines() sobre o texto devolvido por read().
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.
O pacote Go agent/harness reúne middleware, fornecedores de contexto e predefinições do histórico para um agente padrão suportado por fornecedor. Chame harness.AgentConfig(harness.Config{}, agent.Config{...}), trate o seu erro e passe a configuração devolvida ao construtor do fornecedor. Não introduz um tipo de agente separado ou um ciclo de execução de ferramenta.
Crie um agente de arnês
A amostra composta configura um harness agent suportado pela 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.",
},
)
Personalize a composição
O assistente ativa as seguintes predefinições:
| Component | Harness predefinido do Go |
|---|---|
| Planning | Ferramentas de tarefa apoiadas por sessões e modos de planear/executar, começando no modo de planear |
| Memória de ficheiro | Ficheiros persistentes em agent-file-memory, com uma pasta de trabalho isolada por sessão |
| Competências | Descoberta apoiada em ficheiros a partir do diretório de trabalho, excluindo a subárvore de memória |
| Pesquisa na Web | Uma declaração de pesquisa web alojada, a menos que o chamador já a tenha fornecido |
| Approval | Middleware de aprovação prévia e auto-aprovação para ferramentas que requerem aprovação |
| History | Histórico em memória com persistência por chamada de serviço |
| Injeção de mensagens | Por agente agent.MessageInjector |
| Rastreamento | Instrumentação de chamadas de agente, ferramenta e modelo suportado |
Utilize harness.Config para desativar componentes ou sobrepor a sua configuração. Desative a pesquisa web alojada quando o serviço ou implementação selecionado não a suportar. Os scripts de competência baseados em ficheiro requerem um executor de scripts explicitamente configurado.
O helper mantém ferramentas do chamador, middleware, fornecedores de contexto e um fornecedor de histórico explicitamente configurado. Numa implementação de modelos Foundry, use DisableStoreOutput: true quando o histórico local controla a conversa.
As ferramentas de compactação, looping e shell não são adicionadas pelo Go helper. Configure-os explicitamente quando necessário. O fornecedor de delegação de agentes de fundo empacotado descrito nos outros SDKs não está disponível no Go.
Veja Criar um agente harness Go para configuração e o guia de configuração do harness Go para predefinições e substituições.
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 Go inclui um exemplo de harness composto com gestão de aprovações e uma demonstração interativa de CLI por chat separada. A CLI do chat usa um agente simples; não é o equivalente da consola Harness de C# ou Python.