Microsoft Agent 框架集成

在 Microsoft Agent Framework（MAF）中使用 Copilot SDK 作为代理提供者，以便与 Azure OpenAI、Anthropic 等其他提供商一起编排多代理工作流。

概览

Microsoft Agent Framework 是 Semantic Kernel 和 AutoGen 的统一后继者。它提供了构建、编排和部署 AI 代理的标准接口。专用的集成包可将 Copilot SDK 客户端包装为一等的 MAF 代理——可与框架中的任何其他代理提供者互换使用。

概念	描述
Microsoft Agent 框架	.NET 与 Python 中用于单代理和多代理编排的开源框架
代理提供者	为代理提供动力的后端（Copilot、Azure OpenAI、Anthropic 等）
编排器	在顺序、并发或交接工作流中协调代理的 MAF 组件
A2A 协议	框架支持的代理间通信标准

先决条件

在开始之前，请确认您已具备以下条件

• 您所使用语言的 Copilot SDK 已正确配置。参见 Copilot SDK 入门指南。
• GitHub Copilot 订阅（个人版、商业版或企业版）。
• 已安装 Copilot CLI 或可通过 SDK 附带的 CLI 访问。

安装

同时安装 Copilot SDK 与 MAF 集成包

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

Python 示例请参阅 microsoft-agent-framework，该文章位于 github/copilot-sdk 仓库。

基本用法

将 Copilot SDK 客户端包装为 MAF 代理，只需一次方法调用。得到的代理遵循框架的标准接口，可在任何需要 MAF 代理的地方使用。

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

Python 示例请参阅 microsoft-agent-framework，该文章位于 github/copilot-sdk 仓库。

添加自定义工具

为您的 Copilot 代理扩展自定义函数工具。通过标准 Copilot SDK 定义的工具在代理运行于 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);

您也可以在 MAF 工具的同时使用 Copilot SDK 原生的工具定义。

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

Python 示例请参阅 microsoft-agent-framework，该文章位于 github/copilot-sdk 仓库。

多代理工作流

MAF 集成的主要优势在于能够在编排工作流中将 Copilot 与其他代理提供者组合使用。利用框架内置的编排器，可创建让不同代理负责不同步骤的流水线。

顺序工作流

依次运行代理，将前一个代理的输出传递给下一个代理

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

Python 示例请参阅 microsoft-agent-framework，该文章位于 github/copilot-sdk 仓库。

并发工作流

并行运行多个代理并聚合它们的结果

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

流式响应

在构建交互式应用时，流式传输代理响应以实时展示输出。MAF 集成保留了 Copilot SDK 的流式能力。

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

您也可以在不使用 MAF 的情况下直接通过 Copilot SDK 进行流式传输

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

Python 示例请参阅 microsoft-agent-framework，该文章位于 github/copilot-sdk 仓库。

配置参考

MAF 代理选项

属性	类型	描述
说明	string	代理的系统提示
工具	AIFunction[] 或列表	对代理可用的自定义函数工具
流式传输	bool	启用流式响应
模型	string	覆写默认模型

Copilot SDK 选项（向下传递）

创建底层 Copilot 客户端时，所有标准的 SessionConfig 选项均可用。MAF 包装器在内部委托给 SDK。

SDK 功能	MAF 支持
自定义工具（DefineTool 与 AIFunctionFactory）	与 MAF 工具合并
MCP 服务器	在 SDK 客户端上配置
自定义代理与子代理	在 Copilot 代理内部可用
无限会话	在 SDK 客户端上配置
模型选择	可在每个代理或每次调用时覆写
流式传输	完整的增量事件支持

最佳实践

选择合适的集成层级

当需要在编排工作流中将 Copilot 与其他提供者组合使用时，请使用 MAF 包装器。如果您的应用仅使用 Copilot，独立的 SDK 更加简洁并提供完整的控制权。

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

让代理保持专注

在构建多代理工作流时，为每个代理分配明确的角色和指令，避免职责重叠。

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

在编排层处理错误

对代理调用进行错误处理，尤其是多代理工作流中，单个代理的失败不应阻塞整个流水线。

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
}

延伸阅读

• Copilot SDK 入门指南
• Microsoft Agent Framework 文档
• 博客：使用 GitHub Copilot SDK 与 Microsoft Agent Framework 构建 AI 代理