Skip to main content

Integração com o framework de agente da Microsoft

Use o SDK Copilot como um provedor de agente dentro do Microsoft Agent Framework (MAF) para compor fluxos de trabalho de vários agentes juntamente com Azure OpenAI, Anthropic e outros provedores.

Visão geral

O Microsoft Agent Framework é o sucessor unificado do Kernel Semântico e do AutoGen. Ele fornece uma interface padrão para criar, orquestrar e implantar agentes de IA. Os pacotes de integração dedicados permitem encapsular um cliente do SDK Copilot como um agente MAF de primeira classe, intercambiável com qualquer outro provedor de agente na estrutura.

ConceitoDescrição
Estrutura do Microsoft AgentEstrutura de software livre para orquestração de um e vários agentes no .NET e python
Provedor de agenteUm back-end que alimenta um agente (Copilot, Azure OpenAI, Antropico etc.)
OrquestradorUm componente MAF que coordena agentes em fluxos de trabalho sequenciais, simultâneos ou de entrega
Protocolo A2APadrão de comunicação de agente para agente compatível com o framework

Observação

Os pacotes de integração do MAF estão disponíveis para .NET e Python. Para TypeScript, Go, Java e Rust, use diretamente o SDK do Copilot — as APIs padrão do SDK já oferecem chamada de ferramentas, streaming e agentes personalizados.

Pré-requisitos

Antes de começar, verifique se você tem:

Installation

Instale o SDK do Copilot junto com o pacote de integração do MAF para seu idioma:

Idiomas de código navigation

.NET
dotnet add package GitHub.Copilot.SDK
dotnet add package Microsoft.Agents.AI.GitHub.Copilot --prerelease

Uso Básico

Empacotar o cliente do SDK Copilot como um agente do MAF com uma única chamada de método. O agente resultante está em conformidade com a interface padrão da estrutura e pode ser usado em qualquer lugar que um agente MAF seja esperado.

Idiomas de código navigation

.NET
using GitHub.Copilot;
using Microsoft.Agents.AI;

await using var copilotClient = new CopilotClient();
await copilotClient.StartAsync();

// Wrap as a MAF agent
AIAgent agent = copilotClient.AsAIAgent();

// Use the standard MAF interface
string response = await agent.RunAsync("Explain how dependency injection works in ASP.NET Core");
Console.WriteLine(response);

Adicionando ferramentas personalizadas

Estenda o agente do Copilot com ferramentas de função personalizadas. As ferramentas definidas por meio do SDK padrão do Copilot ficam automaticamente disponíveis quando o agente é executado dentro do MAF.

Idiomas de código navigation

.NET
using GitHub.Copilot;
using Microsoft.Extensions.AI;
using Microsoft.Agents.AI;

// Define a custom tool
AIFunction weatherTool = CopilotTool.DefineTool(
    (string location) => $"The weather in {location} is sunny with a high of 25°C.",
    factoryOptions: new AIFunctionFactoryOptions
    {
        Name = "GetWeather",
        Description = "Get the current weather for a given location.",
    }
);

await using var copilotClient = new CopilotClient();
await copilotClient.StartAsync();

// Create agent with tools
AIAgent agent = copilotClient.AsAIAgent(new AIAgentOptions
{
    Tools = new[] { weatherTool },
});

string response = await agent.RunAsync("What's the weather like in Seattle?");
Console.WriteLine(response);

Você também pode usar a definição nativa de ferramenta do Copilot SDK em conjunto com as ferramentas do MAF:

Idiomas de código navigation

TypeScript
import { CopilotClient, DefineTool } from "@github/copilot-sdk";

const getWeather = DefineTool({
    name: "GetWeather",
    description: "Get the current weather for a given location.",
    parameters: { location: { type: "string", description: "City name" } },
    execute: async ({ location }) => `The weather in ${location} is sunny, 25°C.`,
});

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-4.1",
    tools: [getWeather],
    onPermissionRequest: async () => ({ kind: "approve-once" }),
});

await session.sendAndWait({ prompt: "What's the weather like in Seattle?" });

Fluxos de trabalho de vários agentes

O principal benefício da integração do MAF é compor o Copilot em conjunto com outros fornecedores de agentes em fluxos de trabalho orquestrados. Use os orquestradores internos do framework para criar pipelines em que diferentes agentes são responsáveis por etapas distintas.

Fluxo de trabalho sequencial

Execute agentes um após o outro, passando a saída de um para o outro:

Idiomas de código navigation

.NET
using GitHub.Copilot;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Orchestration;

await using var copilotClient = new CopilotClient();
await copilotClient.StartAsync();

// Copilot agent for code review
AIAgent reviewer = copilotClient.AsAIAgent(new AIAgentOptions
{
    Instructions = "You review code for bugs, security issues, and best practices. Be thorough.",
});

// Azure OpenAI agent for generating documentation
AIAgent documentor = AIAgent.FromOpenAI(new OpenAIAgentOptions
{
    Model = "gpt-4.1",
    Instructions = "You write clear, concise documentation for code changes.",
});

// Compose in a sequential pipeline
var pipeline = new SequentialOrchestrator(new[] { reviewer, documentor });

string result = await pipeline.RunAsync(
    "Review and document this pull request: added retry logic to the HTTP client"
);
Console.WriteLine(result);

Fluxo de trabalho simultâneo

Execute vários agentes em paralelo e agrupe seus resultados:

Idiomas de código navigation

.NET
using GitHub.Copilot;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Orchestration;

await using var copilotClient = new CopilotClient();
await copilotClient.StartAsync();

AIAgent securityReviewer = copilotClient.AsAIAgent(new AIAgentOptions
{
    Instructions = "Focus exclusively on security vulnerabilities and risks.",
});

AIAgent performanceReviewer = copilotClient.AsAIAgent(new AIAgentOptions
{
    Instructions = "Focus exclusively on performance bottlenecks and optimization opportunities.",
});

// Run both reviews concurrently
var concurrent = new ConcurrentOrchestrator(new[] { securityReviewer, performanceReviewer });

string combinedResult = await concurrent.RunAsync(
    "Analyze this database query module for issues"
);
Console.WriteLine(combinedResult);

Respostas em streaming

Ao criar aplicativos interativos, transmita respostas do agente para mostrar a saída em tempo real. A integração do MAF preserva os recursos de streaming do SDK do Copilot.

Idiomas de código navigation

.NET
using GitHub.Copilot;
using Microsoft.Agents.AI;

await using var copilotClient = new CopilotClient();
await copilotClient.StartAsync();

AIAgent agent = copilotClient.AsAIAgent(new AIAgentOptions
{
    Streaming = true,
});

await foreach (var chunk in agent.RunStreamingAsync("Write a quicksort implementation in C#"))
{
    Console.Write(chunk);
}
Console.WriteLine();

Você também pode transmitir diretamente pelo SDK do Copilot sem maf:

Idiomas de código navigation

TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-4.1",
    streaming: true,
    onPermissionRequest: async () => ({ kind: "approve-once" }),
});

session.on("assistant.message_delta", (event) => {
    process.stdout.write(event.data.delta ?? "");
});

await session.sendAndWait({ prompt: "Write a quicksort implementation in TypeScript" });

Referência de configuração

Opções de agente do MAF

PropriedadeTipoDescrição
Instructions / instructionsstringComando do sistema ao agente
Tools / toolsAIFunction[] / listFerramentas de função personalizadas disponíveis para o agente
Streaming / streamingboolHabilitar respostas de streaming
Model / modelstringSubstituir o modelo padrão

Opções do SDK do Copilot (transmitidas)

Todas as opções de Crie seu primeiro aplicativo com tecnologia do Copilot padrão ainda estão disponíveis ao criar o cliente Copilot subjacente. O wrapper MAF delega internamente para o SDK:

Recurso do SDKSuporte do MAF
Ferramentas personalizadas (DefineTool / AIFunctionFactory)
✅ Integrado às ferramentas MAF
Servidores MCP
✅ Configurado no cliente do SDK
Agentes personalizados / sub-agentes personalizados
✅ Disponível no agente do Copilot
Sessões infinitas
✅ Configurado no cliente do SDK
Seleção de modelo✅ Substituível por agente ou por chamada
Transmissão ao vivo
✅ Suporte completo a eventos delta

Práticas recomendadas

Escolher o nível certo de integração

Use o encapsulador MAF quando você precisar combinar o Copilot com outros provedores em fluxos de trabalho orquestrados. Se o aplicativo usar apenas Copilot, o SDK autônomo será mais simples e fornecerá controle total:

// Standalone SDK — full control, simpler setup
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-4.1",
    onPermissionRequest: async () => ({ kind: "approve-once" }),
});
const response = await session.sendAndWait({ prompt: "Explain this code" });

Manter os agentes focados

Ao criar fluxos de trabalho de vários agentes, dê a cada agente uma função específica com instruções claras. Evite a sobreposição de responsabilidades:

// ❌ Too vague — overlapping roles
const agents = [
    { instructions: "Help with code" },
    { instructions: "Assist with programming" },
];

// ✅ Focused — clear separation of concerns
const agents = [
    { instructions: "Review code for security vulnerabilities. Flag SQL injection, XSS, and auth issues." },
    { instructions: "Optimize code performance. Focus on algorithmic complexity and memory usage." },
];

Lidar com erros no nível de orquestração

Empacote chamadas de agente no tratamento de erros, especialmente em fluxos de trabalho multiagentes, em que a falha de um agente não deve bloquear todo o pipeline:

try
{
    string result = await pipeline.RunAsync("Analyze this module");
    Console.WriteLine(result);
}
catch (AgentException ex)
{
    Console.Error.WriteLine($"Agent {ex.AgentName} failed: {ex.Message}");
    // Fall back to single-agent mode or retry
}

Consulte também