# Microsoft 에이전트 프레임워크 통합

Copilot SDK를 Microsoft 에이전트 프레임워크 내에서 에이전트 공급자로 사용하여 Azure OpenAI, Anthropic 및 기타 공급자와 함께 다중 에이전트 워크플로를 작성합니다.

<!-- markdownlint-disable GHD046 GHD005 -->

<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->

## 개요

Microsoft 에이전트 프레임워크는 의미 체계 커널 및 AutoGen의 통합 후속 작업입니다. AI 에이전트를 빌드, 오케스트레이션 및 배포하기 위한 표준 인터페이스를 제공합니다. 전용 통합 패키지를 사용하면 Copilot SDK 클라이언트를 프레임워크의 다른 에이전트 공급자와 교환할 수 있는 일류 MAF 에이전트로 래핑할 수 있습니다.

| 개념                       | 설명                                                   |
| ------------------------ | ---------------------------------------------------- |
| **Microsoft 에이전트 프레임워크** | .NET 및 Python에서 단일 및 다중 에이전트 오케스트레이션을 위한 오픈 소스 프레임워크 |
| **에이전트 공급자**             | 에이전트를 구동하는 백 엔드(Copilot, Azure OpenAI, Anthropic 등)  |
| **조정자**                  | 순차, 동시 또는 핸드오프 워크플로에서 에이전트를 조정하는 MAF 구성 요소           |
| **A2A 프로토콜**             | 프레임워크에서 지원하는 에이전트 간 통신 표준                            |

> \[!NOTE]
> MAF 통합 패키지는 **.NET** 및 **Python** 사용할 수 있습니다. TypeScript, Go, Java 및 Rust의 경우 Copilot SDK를 직접 사용합니다. 표준 SDK API는 이미 도구 호출, 스트리밍 및 사용자 지정 에이전트를 제공합니다.

## 사전 요구 사항

시작하기 전에 다음 사항을 확인하세요.

* 선택한 언어로 작동하는 [첫 번째 Copilot 기반 앱 빌드](/ko/copilot/how-tos/copilot-sdk/getting-started)
* GitHub Copilot 구독(개인, 비즈니스 또는 엔터프라이즈)
* SDK의 번들 CLI를 통해 설치되거나 사용할 수 있는 Copilot CLI

## 설치

언어에 대한 MAF 통합 패키지와 함께 Copilot SDK를 설치합니다.

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

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

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

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

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

> \[!NOTE]
> Java SDK에는 전용 MAF 통합 패키지가 없습니다. 표준 Copilot SDK를 직접 사용합니다. 즉, 도구 호출, 스트리밍 및 사용자 지정 에이전트를 기본으로 제공합니다.

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

</div>

</div>

## 기본 사용법

단일 메서드 호출을 사용하여 Copilot SDK 클라이언트를 MAF 에이전트로 래핑합니다. 결과 에이전트는 프레임워크의 표준 인터페이스를 준수하며 MAF 에이전트가 필요한 모든 곳에서 사용할 수 있습니다.

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

<!-- docs-validate: skip -->

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

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

<!-- docs-validate: skip -->

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

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

<!-- docs-validate: skip -->

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

</div>

</div>

## 사용자 지정 도구 추가

사용자 지정 함수 도구를 사용하여 Copilot 에이전트 확장합니다. 표준 Copilot SDK를 통해 정의된 도구는 에이전트가 MAF 내에서 실행될 때 자동으로 사용할 수 있습니다.

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

<!-- docs-validate: skip -->

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

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

<!-- docs-validate: skip -->

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

</div>

</div>

MAF 도구와 함께 Copilot SDK의 네이티브 도구 정의를 사용할 수도 있습니다.

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

```typescript
import { CopilotClient, defineTool } from "@github/copilot-sdk";

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

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

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

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

```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-5.4")
        .setTools(List.of(getWeather))
        .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    ).get();

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

</div>

</div>

## 다중 에이전트 워크플로

MAF 통합의 주요 이점은 오케스트레이션된 워크플로의 다른 에이전트 공급자와 함께 Copilot 작성하는 것입니다. 프레임워크의 기본 제공 오케스트레이터를 사용하여 다른 에이전트가 다른 단계를 처리하는 파이프라인을 만듭니다.

### 순차 워크플로

에이전트를 하나씩 실행하여 출력을 다음으로 전달합니다.

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

<!-- docs-validate: skip -->

```csharp
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-5.4",
    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);
```

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

<!-- docs-validate: skip -->

```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-5.4",
        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)
```

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

<!-- docs-validate: skip -->

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

</div>

</div>

### 동시 워크플로

여러 에이전트를 병렬로 실행하고 결과를 집계합니다.

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

<!-- docs-validate: skip -->

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

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

<!-- docs-validate: skip -->

```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-5.4")
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

var perfSession = client.createSession(new SessionConfig()
    .setModel("gpt-5.4")
    .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();
```

</div>

</div>

## 스트리밍 응답

대화형 애플리케이션을 빌드할 때 에이전트 응답을 스트리밍하여 실시간 출력을 표시합니다. MAF 통합은 Copilot SDK의 스트리밍 기능을 유지합니다.

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

<!-- docs-validate: skip -->

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

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

<!-- docs-validate: skip -->

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

</div>

</div>

MAF 없이 Copilot SDK를 통해 직접 스트리밍할 수도 있습니다.

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

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

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

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

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

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

<!-- docs-validate: skip -->

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

</div>

</div>

## 구성 참조

### MAF 에이전트 옵션

| 재산                              | 유형                      | 설명                           |
| ------------------------------- | ----------------------- | ---------------------------- |
| `Instructions` / `instructions` | `string`                | 에이전트에 대한 시스템 프롬프트            |
| `Tools` / `tools`               | `AIFunction[]` / `list` | 에이전트에서 사용할 수 있는 사용자 지정 함수 도구 |
| `Streaming` / `streaming`       | `bool`                  | 스트리밍 응답 사용                   |
| `Model` / `model`               | `string`                | 기본 모델 재정의                    |

### Copilot SDK 옵션(직접 전달됨)

기본 Copilot 클라이언트를 만들 때는 모든 표준 [첫 번째 Copilot 기반 앱 빌드](/ko/copilot/how-tos/copilot-sdk/getting-started) 옵션을 계속 사용할 수 있습니다. MAF 래퍼는 내부적으로 SDK에 작업을 위임합니다.

| SDK 기능                                        | MAF 지원 |
| --------------------------------------------- | ------ |
| 사용자 지정 도구(`DefineTool` / `AIFunctionFactory`) |        |
| ✅ MAF 도구와 병합됨                                 |        |
| MCP 서버                                        |        |
| ✅ SDK 클라이언트에 구성됨                              |        |
| 사용자 지정 에이전트/하위 에이전트                           |        |
| ✅ Copilot 에이전트 내에서 사용 가능                      |        |
| 무한 세션                                         |        |
| ✅ SDK 클라이언트에 구성됨                              |        |
| 모델 선택                                         |        |
| ✅ 담당자별 또는 통화별로 재정의 가능                         |        |
| 스트리밍                                          |        |
| ✅ 전체 델타 이벤트 지원                                |        |

## 모범 사례

### 적절한 수준의 통합 선택

Copilot을 다른 공급자와 함께 오케스트레이션된 워크플로우로 구성해야 할 때 MAF 래퍼를 사용하세요. 애플리케이션에서 Copilot만 사용하는 경우 독립 실행형 SDK는 더 간단하며 모든 권한을 제공합니다.

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

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

### 에이전트가 집중하도록 유지하기

다중 에이전트 워크플로를 빌드할 때 명확한 지침이 포함된 특정 역할을 각 에이전트에 제공합니다. 겹치는 책임 방지:

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

### 오케스트레이션 수준에서 오류 처리

에이전트 호출을 오류 처리로 감싸야 하며, 특히 다중 에이전트 워크플로에서 한 에이전트의 실패가 전체 파이프라인을 차단하지 않도록 해야 합니다.

<!-- docs-validate: skip -->

```csharp
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 기반 앱 빌드](/ko/copilot/how-tos/copilot-sdk/getting-started): 초기 Copilot SDK 설정
* [사용자 정의 에이전트 및 하위 에이전트 오케스트레이션](/ko/copilot/how-tos/copilot-sdk/features/custom-agents): SDK 내에서 특수 하위 에이전트 정의
* [사용자 지정 기술](/ko/copilot/how-tos/copilot-sdk/features/skills): 재사용 가능한 프롬프트 모듈
* [Microsoft Agent Framework 설명서](https://learn.microsoft.com/en-us/agent-framework/agents/providers/github-copilot): Copilot 공급자에 대한 공식 MAF 문서
* [블로그: GitHub Copilot SDK 및 Microsoft Agent Framework를 사용하여 AI 에이전트 빌드](https://devblogs.microsoft.com/semantic-kernel/build-ai-agents-with-github-copilot-sdk-and-microsoft-agent-framework/)