Etapa 6: Arcabouço do Agente

Uma estrutura envolve um cliente de chat com o arcabouço de que um agente precisa para executar tarefas longas e de várias etapas – modos de planejamento/execução, uma lista de tarefas para orientar o planejamento, compactação de contexto, memória em arquivos, acesso a arquivos e aprovação de ferramentas com a opção não perguntar novamente. Em vez de montar esses componentes por conta própria, você cria uma estrutura de agentes e já recebe tudo pronto.

Crie uma estrutura de agentes de qualquer IChatClient com o método de extensão AsHarnessAgent. Como um orquestrador executa tarefas de forma interativa em várias etapas, normalmente você o controla por meio de um loop de conversa: mantenha um AgentSession para que o estado do orquestrador (plano, tarefas pendentes e histórico) persista entre os turnos, leia a próxima instrução do usuário e transmita a saída do agente à medida que ela for sendo gerada.

using System;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// chatClient is any IChatClient implementation (Foundry, Azure OpenAI, OpenAI, Anthropic, ...).
AIAgent agent = chatClient.AsHarnessAgent();

// A session carries the harness state (plan, todos, history) across turns.
AgentSession session = await agent.CreateSessionAsync();

Console.WriteLine("Harness agent ready. Type 'exit' to quit.");
while (true)
{
    Console.Write("> ");
    string? input = Console.ReadLine();
    if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
    {
        break;
    }

    // Stream this turn's output as the harness plans and works through the request.
    await foreach (var update in agent.RunStreamingAsync(input, session))
    {
        Console.Write(update);
    }

    Console.WriteLine();
}

A estrutura cuida do planejamento, do acompanhamento de tarefas e da persistência do histórico para você ao longo de toda a conversa. Para obter um console com todos os recursos – com solicitações de aprovação de ferramentas, renderização de listas de tarefas/modos e comandos com barra – consulte a experiência do usuário no terminal de exemplo.

Tip

Consulte os exemplos de harness do .NET com aplicativos completos e executáveis.

O exemplo completo cria um cliente de chat do Microsoft Foundry, encapsula-o com create_harness_agent e reutiliza uma sessão ao longo de duas interações. O arcabouço adiciona planejamento, acompanhamento de tarefas e compactação, enquanto o exemplo desabilita a memória de arquivos e a pesquisa na Web para manter o foco.

import asyncio

from agent_framework import create_harness_agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential


async def main() -> None:
    agent = create_harness_agent(
        client=FoundryChatClient(
            project_endpoint="https://your-account.services.ai.azure.com/api/projects/your-project",
            model="gpt-6-luna",
            credential=AzureCliCredential(),
        ),
        agent_instructions="Help users plan and complete multi-step tasks.",
        disable_file_memory=True,
        disable_web_search=True,
    )
    session = agent.create_session()

    print(await agent.run("Plan a weekend trip to Seattle.", session=session))
    print(await agent.run("Turn that plan into a checklist.", session=session))


if __name__ == "__main__":
    asyncio.run(main())

A sessão compartilhada preserva o estado do harness em ambas as chamadas. Para obter um console completo - com prompts de aprovação de ferramentas, to-do e renderização de modo e comandos de barra - consulte o exemplo de UX do terminal.

Tip

Veja o exemplo completo de primeiros passos. Para obter mais padrões, consulte os exemplos de harness do Python.

Tip

A agent-framework-builder-python habilidade do agente de codificação pode orientar a composição do harness e as opções de pacote. Ele é separado das habilidades do agente de runtime, que continuam sendo um recurso opcional do harness em Python.

Prerequisites

  • Acesse 1.26 ou posterior.
  • Um check-out local do repositório Agent Framework Go.
  • Um ponto de extremidade de projeto do Foundry e uma implantação de modelo, configurados por meio de FOUNDRY_PROJECT_ENDPOINT e FOUNDRY_MODEL.
  • Uma credencial do Azure com suporte por DefaultAzureCredential, como um login no CLI do Azure com az login.

Configurar o harness Go

O pacote agent/harness configura um agente comum mantido por um provedor. Passe o resultado para o construtor do provedor harness.AgentConfig:

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.",
        },
    )

Os padrões incluem todos, modos de plano e execução, memória de arquivo isolada por sessão, habilidades, pesquisa na Web hospedada, middleware de aprovação de ferramentas e instrumentação OpenTelemetry. O auxiliar também habilita a persistência do histórico de chamadas por serviço e a injeção de mensagem.

Este exemplo de Foundry define DisableStoreOutput: true para que o histórico local controle a conversa. Defina harness.Config em DisableWebSearch se o provedor ou a implantação selecionado não der suporte à pesquisa na Web hospedada.

Execute o exemplo completo da raiz do repositório Go:

go run .\examples\02-agents\harness\step04_composite_harness

O exemplo reutiliza uma sessão em duas voltas, manipula solicitações de aprovação de ferramentas e abre uma sessão separada para demonstrar o isolamento de memória. A memória de arquivo persiste em agent-file-memory no diretório de trabalho.

Compactação e looping são opcionais em vez de serem padrões do Go harness. Para limites de configuração e de componentes, consulte Agent Harness.

Tip

Consulte o exemplo completo de composite harness e o guia de configuração do Go harness.

Próximas Etapas 

Etapa 7: Hospedar seu agente

Vá mais fundo:

  • Última atualização em