Integração com o framework de agente da Microsoft

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.

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 entrega
Protocolo A2A	Padrã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:

Um Crie seu primeiro aplicativo com tecnologia do Copilot funcional em seu idioma de escolha
Uma assinatura GitHub Copilot (Individual, Business ou Enterprise)
A CLI do Copilot instalada ou disponível por meio da CLI incluída no SDK

Installation

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

.NET

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

Python

pip install copilot-sdk agent-framework-github-copilot

Java

Observação

O SDK do Java não tem um pacote de integração MAF dedicado. Use diretamente o SDK padrão do Copilot — ele oferece chamada de ferramentas, streaming e agentes personalizados já prontos para uso.

<!-- Maven -->
<!-- Set copilot.sdk.version to the version published in java/README.md / Maven Central -->
<dependency>
    <groupId>com.github</groupId>
    <artifactId>copilot-sdk-java</artifactId>
    <version>${copilot.sdk.version}</version>
</dependency>

Uso Básico

Encapsular 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.

.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);

Python

from agent_framework.github import GitHubCopilotAgent

async def main():
    agent = GitHubCopilotAgent(
        default_options={
            "instructions": "You are a helpful coding assistant.",
        }
    )

    async with agent:
        result = await agent.run("Explain how dependency injection works in FastAPI")
        print(result)

Java

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.events.*;
import com.github.copilot.sdk.json.*;

var client = new CopilotClient();
client.start().get();

var session = client.createSession(new SessionConfig()
    .setModel("gpt-4.1")
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

var response = session.sendAndWait(new MessageOptions()
    .setPrompt("Explain how dependency injection works in Spring Boot")).get();
System.out.println(response.getData().content());

client.stop().get();

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.

.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);

Python

from agent_framework.github import GitHubCopilotAgent

def get_weather(location: str) -> str:
    """Get the current weather for a given location."""
    return f"The weather in {location} is sunny with a high of 25°C."

async def main():
    agent = GitHubCopilotAgent(
        default_options={
            "instructions": "You are a helpful assistant with access to weather data.",
        },
        tools=[get_weather],
    )

    async with agent:
        result = await agent.run("What's the weather like in Seattle?")
        print(result)

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

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?" });

Java

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.events.*;
import com.github.copilot.sdk.json.*;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

var getWeather = ToolDefinition.create(
    "GetWeather",
    "Get the current weather for a given location.",
    Map.of(
        "type", "object",
        "properties", Map.of(
            "location", Map.of("type", "string", "description", "City name")),
        "required", List.of("location")),
    invocation -> {
        var location = (String) invocation.getArguments().get("location");
        return CompletableFuture.completedFuture(
            "The weather in " + location + " is sunny, 25°C.");
    });

try (var client = new CopilotClient()) {
    client.start().get();

    var session = client.createSession(new SessionConfig()
        .setModel("gpt-4.1")
        .setTools(List.of(getWeather))
        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    ).get();

    session.sendAndWait(new MessageOptions()
        .setPrompt("What's the weather like in Seattle?")).get();
}

Fluxos de trabalho de vários agentes

O principal benefício da integração do MAF é combinar o Copilot com outros provedores 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:

.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);

Python

from agent_framework.github import GitHubCopilotAgent
from agent_framework.openai import OpenAIAgent
from agent_framework.orchestration import SequentialOrchestrator

async def main():
    # Copilot agent for code review
    reviewer = GitHubCopilotAgent(
        default_options={
            "instructions": "You review code for bugs, security issues, and best practices.",
        }
    )

    # OpenAI agent for documentation
    documentor = OpenAIAgent(
        model="gpt-4.1",
        instructions="You write clear, concise documentation for code changes.",
    )

    # Compose in a sequential pipeline
    pipeline = SequentialOrchestrator(agents=[reviewer, documentor])

    async with pipeline:
        result = await pipeline.run(
            "Review and document this PR: added retry logic to the HTTP client"
        )
        print(result)

Java

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.events.*;
import com.github.copilot.sdk.json.*;

// Java uses the standard SDK directly — no MAF orchestrator needed
var client = new CopilotClient();
client.start().get();

// Step 1: Code review session
var reviewer = client.createSession(new SessionConfig()
    .setModel("gpt-4.1")
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

var review = reviewer.sendAndWait(new MessageOptions()
    .setPrompt("Review this PR for bugs, security issues, and best practices: "
        + "added retry logic to the HTTP client")).get();

// Step 2: Documentation session using review output
var documentor = client.createSession(new SessionConfig()
    .setModel("gpt-4.1")
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

var docs = documentor.sendAndWait(new MessageOptions()
    .setPrompt("Write documentation for these changes: " + review.getData().content())).get();
System.out.println(docs.getData().content());

client.stop().get();

Fluxo de trabalho simultâneo

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

.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);

Java

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.events.*;
import com.github.copilot.sdk.json.*;
import java.util.concurrent.CompletableFuture;

// Java uses CompletableFuture for concurrent execution
var client = new CopilotClient();
client.start().get();

var securitySession = client.createSession(new SessionConfig()
    .setModel("gpt-4.1")
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

var perfSession = client.createSession(new SessionConfig()
    .setModel("gpt-4.1")
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

// Run both reviews concurrently
var securityFuture = securitySession.sendAndWait(new MessageOptions()
    .setPrompt("Focus on security vulnerabilities in this database query module"));
var perfFuture = perfSession.sendAndWait(new MessageOptions()
    .setPrompt("Focus on performance bottlenecks in this database query module"));

CompletableFuture.allOf(securityFuture, perfFuture).get();

System.out.println("Security: " + securityFuture.get().getData().content());
System.out.println("Performance: " + perfFuture.get().getData().content());

client.stop().get();

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.

.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();

Python

from agent_framework.github import GitHubCopilotAgent

async def main():
    agent = GitHubCopilotAgent(
        default_options={"streaming": True}
    )

    async with agent:
        async for chunk in agent.run_streaming("Write a quicksort in Python"):
            print(chunk, end="", flush=True)
        print()

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

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

Java

import com.github.copilot.sdk.CopilotClient;
import com.github.copilot.sdk.events.*;
import com.github.copilot.sdk.json.*;

var client = new CopilotClient();
client.start().get();

var session = client.createSession(new SessionConfig()
    .setModel("gpt-4.1")
    .setStreaming(true)
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

session.on(AssistantMessageDeltaEvent.class, event -> {
    System.out.print(event.getData().deltaContent());
});

session.sendAndWait(new MessageOptions()
    .setPrompt("Write a quicksort implementation in Java")).get();
System.out.println();

client.stop().get();

Referência de configuração

Opções de agente do MAF

Propriedade	Tipo	Descrição
`Instructions` / `instructions`	`string`	Comando do sistema ao agente
`Tools` / `tools`	`AIFunction[]` / `list`	Ferramentas de função personalizadas disponíveis para o agente
`Streaming` / `streaming`	`bool`	Habilitar respostas de streaming
`Model` / `model`	`string`	Substituir 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 ao SDK nos bastidores:

Recurso do SDK	Suporte 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

Crie seu primeiro aplicativo com tecnologia do Copilot: configuração inicial do SDK Copilot
Agentes personalizados e orquestração de subagentes: definir sub-agentes especializados no SDK
Habilidades personalizadas: módulos de prompt reutilizáveis
documentação do Microsoft Agent Framework: documentação oficial do MAF para o provedor do Copilot
Blog: Criar agentes de IA com o SDK do GitHub Copilot e o Microsoft Agent Framework

Integração com o framework de agente da Microsoft

Neste artigo