Integração do Microsoft Agent Framework

          SDK do Copilot está atualmente em versão prévia pública. A funcionalidade e a disponibilidade estão sujeitas a alterações.

Use SDK do Copilot como um provedor de agente dentro do Microsoft Agent Framework (MAF) para compor fluxos de trabalho de vários agentes ao lado do Azure OpenAI, Antropic 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 SDK do Copilot cliente como um agente MAF de primeira classe , intercambiável com qualquer outro provedor de agente na estrutura.

Conceito	Descrição
Estrutura do Microsoft Agent	Estrutura de software livre para orquestração de um e vários agentes no .NET e python
Provedor de agente	Um back-end que alimenta um agente (Copilot, Azure OpenAI, Antropico etc.)
Orquestrador	Um componente MAF que coordena agentes em fluxos de trabalho sequenciais, simultâneos ou de transição
Protocolo A2A	Padrão de comunicação de agente para agente compatível com o framework

Pré-requisitos

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

• Uma configuração funcional SDK do Copilot em seu idioma de escolha. Consulte Introdução ao SDK do Copilot.
• Uma GitHub Copilot assinatura (individual, empresarial ou corporativa).

•         CLI do Copilot instalado ou disponível por meio da CLI pacotada do SDK.
  

Installation

Instale o SDK do Copilot junto com o pacote de integração do MAF.

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

Para obter exemplos no Python, consulte o microsoft-agent-framework artigo no github/copilot-sdk repositório.

Uso Básico

Embalar o SDK do Copilot cliente como um agente 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.

using GitHub.Copilot.SDK;
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);

Para obter exemplos no Python, consulte o microsoft-agent-framework artigo no github/copilot-sdk repositório.

Adicionando ferramentas personalizadas

Estenda seu Copilot agente com ferramentas funcionais personalizadas. As ferramentas definidas por meio do padrão SDK do Copilot estão automaticamente disponíveis quando o agente é executado dentro do MAF.

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

// Define a custom tool
AIFunction weatherTool = AIFunctionFactory.Create(
    (string location) => $"The weather in {location} is sunny with a high of 25°C.",
    "GetWeather",
    "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 de ferramenta nativa do SDK do Copilot juntamente com as ferramentas MAF:

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: "approved" }),
});

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

Para obter exemplos no Python, consulte o microsoft-agent-framework artigo no github/copilot-sdk repositório.

Fluxos de trabalho de vários agentes

O principal benefício da integração do MAF é compor 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:

using GitHub.Copilot.SDK;
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);

Para obter exemplos no Python, consulte o microsoft-agent-framework artigo no github/copilot-sdk repositório.

Fluxo de trabalho simultâneo

Execute vários agentes em paralelo e agrupar seus resultados.

using GitHub.Copilot.SDK;
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.

using GitHub.Copilot.SDK;
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 o MAF.

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

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

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

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

Para obter exemplos no Python, consulte o microsoft-agent-framework artigo no github/copilot-sdk repositório.

Referência de configuração

Opções de agente do MAF

Propriedade	Tipo	Descrição
Instructions	cadeia	Comando do sistema ao agente
Tools	AIFunction[] ou lista	Ferramentas de função personalizadas disponíveis para o agente
Streaming	bool	Habilitar respostas de streaming
Model	cadeia	Substituir o modelo padrão

Opções do SDK do Copilot (transmitidas)

Todas as opções padrão SessionConfig estão disponíveis ao criar o cliente subjacente Copilot . O wrapper MAF delega internamente para o SDK.

Recurso do SDK	Suporte ao MAF
Ferramentas personalizadas (DefineTool e AIFunctionFactory)	Mesclado com as ferramentas do MAF
Servidores MCP	Configurado no cliente do SDK
Agentes personalizados e sub-agentes	Disponível no agente 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 a eventos delta completos

Práticas recomendadas

Escolher o nível certo de integração

Use o wrapper MAF quando precisar compor Copilot com outros provedores em fluxos de trabalho orquestrados. Se o aplicativo usar Copilotapenas, 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: "approved" }),
});
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

Envolver chamadas de agente no tratamento de erros, especialmente em workflows com múltiplos agentes, onde 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
}

Leitura adicional

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started)
  

•         [Documentação do Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/agents/providers/github-copilot)
  

•         [Blog: Criar agentes de IA com o SDK do GitHub Copilot e o Microsoft Agent Framework](https://devblogs.microsoft.com/semantic-kernel/build-ai-agents-with-github-copilot-sdk-and-microsoft-agent-framework/)