integración del marco de trabajo del agente de Microsoft

Visión general

Microsoft Agent Framework es el sucesor unificado de Kernel semántico y AutoGen. Proporciona una interfaz estándar para compilar, orquestar e implementar agentes de IA. Los paquetes de integración dedicados permiten encapsular un cliente del SDK de Copilot como agente de MAF de primera clase, intercambiable con cualquier otro proveedor de agentes del marco.

Concepto	Descripción
Microsoft Agent Framework	Marco de código abierto para la orquestación de un solo agente y multiagente en .NET y Python
Proveedor de agente	Un back-end que impulsa a un agente (Copilot, Azure OpenAI, antrópico, etc.)
Orquestador	Un componente MAF que coordina los agentes en flujos de trabajo secuenciales, simultáneos o de entrega
Protocolo A2A	Estándar de comunicación de agente a agente compatible con el marco

Nota:

Los paquetes de integración de MAF están disponibles para .NET y Python. Para TypeScript, Go, Java y Rust, usa directamente el SDK de Copilot: las API estándar del SDK ya proporcionan invocación de herramientas, streaming y agentes personalizados.

Prerrequisitos

Antes de comenzar, asegúrese de que tiene:

Un Crea tu primera aplicación con tecnología Copilot funcional en el idioma que elija
Una suscripción a GitHub Copilot (Individual, Business o Enterprise)
La CLI de Copilot instalada o disponible a través de la CLI incluida en el SDK

Instalación

Instale el SDK de Copilot junto con el paquete de integración de MAF para el lenguaje:

.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

Nota:

El SDK de Java no tiene un paquete de integración de MAF dedicado. Use el SDK de Copilot estándar directamente: proporciona llamadas a herramientas, streaming y agentes personalizados de fábrica.

<!-- 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

Encapsule el cliente del SDK de Copilot como un agente de MAF con una sola llamada de método. El agente resultante se ajusta a la interfaz estándar del marco y se puede usar en cualquier lugar en el que se espera un agente de MAF.

.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.CopilotClient;
import com.github.copilot.rpc.*;

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

Adición de herramientas personalizadas

Amplíe el agente de Copilot con herramientas de función personalizadas. Las herramientas definidas a través del SDK de Copilot estándar están disponibles automáticamente cuando el agente se ejecuta dentro de 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)

También puede usar la definición nativa de herramientas del SDK de Copilot junto con las herramientas de 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.CopilotClient;
import com.github.copilot.rpc.*;
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();
}

Flujos de trabajo de varios agentes

El principal beneficio de la integración de MAF es combinar Copilot con otros proveedores de agentes en flujos de trabajo orquestados. Use los orquestadores integrados del marco para crear canalizaciones en las que diferentes agentes controlan los distintos pasos.

Flujo de trabajo secuencial

Ejecute agentes entre sí y pase la salida de una a la siguiente:

.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.CopilotClient;
import com.github.copilot.rpc.*;

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

Flujo de trabajo simultáneo

Ejecute varios agentes en paralelo y agregue sus 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.CopilotClient;
import com.github.copilot.rpc.*;
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();

Respuestas de transmisión

Al compilar aplicaciones interactivas, transmita las respuestas del agente para mostrar la salida en tiempo real. La integración de MAF conserva las funcionalidades de streaming del SDK de 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()

También puede transmitir directamente a través del SDK de Copilot sin 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.CopilotClient;
import com.github.copilot.rpc.*;

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

Referencia de configuración

Opciones del agente de MAF

Propiedad	Tipo	Descripción
`Instructions` / `instructions`	`string`	Indicativo del sistema para el agente
`Tools` / `tools`	`AIFunction[]` / `list`	Herramientas de funciones personalizadas disponibles para el agente
`Streaming` / `streaming`	`bool`	Habilitación de respuestas de streaming
`Model` / `model`	`string`	Invalidación del modelo predeterminado

Opciones del SDK de Copilot (pasadas directamente)

Todas las opciones estándar Crea tu primera aplicación con tecnología Copilot siguen estando disponibles al crear el cliente de Copilot subyacente. El contenedor de MAF se delega en el SDK en segundo plano:

Característica del SDK	Soporte para MAF
Herramientas personalizadas (`DefineTool` / `AIFunctionFactory`)
✅ Combinado con herramientas de MAF
Servidores MCP
✅ Configurado en el cliente del SDK
Agentes personalizados / subagentes
✅ Disponible en el agente de Copilot
Sesiones infinitas
✅ Configurado en el cliente del SDK
Selección de modelos	✅ Reemplazable por agente o por llamada
Transmisión en línea
✅ Compatibilidad completa con eventos delta

procedimientos recomendados

Elección del nivel correcto de integración

Use el envoltorio MAF cuando necesite combinar Copilot con otros proveedores en flujos de trabajo orquestados. Si la aplicación solo usa Copilot, el SDK independiente es más sencillo y le proporciona control 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" });

Mantener los agentes centrados

Al compilar flujos de trabajo de varios agentes, asigne a cada agente un rol específico con instrucciones claras. Evite las responsabilidades superpuestas:

// ❌ 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." },
];

Manejo de errores a nivel de orquestación

Envolver las llamadas de agentes en el manejo de errores, especialmente en los flujos de trabajo de varios agentes donde el fallo de un agente no debe bloquear toda la canalización.

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 también

Crea tu primera aplicación con tecnología Copilot: configuración inicial del SDK de Copilot
Agentes personalizados y orquestación de subagentes: definir subagentes especializados en el SDK
Aptitudes personalizadas: módulos de solicitud reutilizables
Documentación de Microsoft Agent Framework: documentación oficial de MAF para el proveedor de Copilot
Blog: Compilación de agentes de IA con el SDK de GitHub Copilot y Microsoft Agent Framework

integración del marco de trabajo del agente de Microsoft

En este artículo