GitHub Copilot SDK를 사용하여 AI 에이전트 구현

Completed

이 단원에서는 GitHub Copilot SDK를 사용하여 AI 에이전트를 빌드하기 위한 핵심 구현 패턴을 다룹니다. 이러한 패턴은 모든 에이전트 시나리오에 적용됩니다. 코드 예제에서는 모듈 연습에서 사용되는 플랫폼인 C# 및 .NET을 사용합니다.

GitHub Copilot SDK 클라이언트 설정

첫 번째 단계는 Copilot CLI 서버에 대한 연결을 관리하는 인스턴스를 만드는 CopilotClient 것입니다. 일반적으로 애플리케이션에서 클라이언트를 싱글톤 서비스로 등록합니다.

필수 패키지 설치

GitHub Copilot SDK 및 Microsoft.Extensions.AI 패키지(도구 정의에 사용됨)를 프로젝트에 추가합니다.

dotnet add package GitHub.Copilot.SDK
dotnet add package Microsoft.Extensions.AI

클라이언트 구성

CopilotClient를 생성하고 CopilotClientOptions로 시작 동작과 로깅을 제어합니다.

var client = new CopilotClient(new CopilotClientOptions
{
    AutoStart = true,
    LogLevel = "info"
});

이 AutoStart 옵션은 첫 번째 세션이 만들어질 때 자동으로 Copilot CLI 서버 프로세스를 시작하도록 SDK에 지시합니다. 이 LogLevel 옵션은 SDK 진단 출력의 상세도를 제어합니다.

클라이언트를 만든 후 시작합니다.

await client.StartAsync();

이 코드는 CLI 서버에 대한 연결을 설정하고 세션 생성을 위해 클라이언트를 준비합니다.

에이전트 도구 정의

도구는 에이전트가 애플리케이션의 백 엔드 서비스와 상호 작용하는 기능을 제공합니다. .NET용 GitHub Copilot SDK에서 AIFunctionFactory.Create를 Microsoft.Extensions.AI 패키지에서 사용하여 도구를 정의합니다.

도구 서비스 만들기

일반적인 패턴은 에이전트가 호출할 수 있는 모든 도구 메서드를 포함하는 전용 서비스 클래스를 만드는 것입니다. 각 메서드는 에이전트가 수행할 수 있는 하나의 작업을 나타냅니다.

public class SupportAgentTools
{
    public async Task<string> GetOrderDetailsAsync(int orderId)
    {
        // Query the database for order information
        var order = await _dbContext.Orders.FindAsync(orderId);
        return order != null
            ? $"Order {orderId}: {order.ProductName}, Status: {order.Status}"
            : "Order not found.";
    }

    public async Task<string> ProcessReturnAsync(int orderId, string reason)
    {
        // Business logic to process the return
        var order = await _dbContext.Orders.FindAsync(orderId);
        order.Status = "Return Initiated";
        await _dbContext.SaveChangesAsync();
        return $"Return initiated for order {orderId}.";
    }
}

SDK에 도구 등록

서비스 메서드를 SDK에서 사용할 수 있는 도구 정의로 변환합니다. 각 도구에는 이름, 설명 및 매개 변수 설명이 필요하므로 AI 모델은 이를 사용하는 시기와 방법을 이해합니다.

var toolService = new SupportAgentTools(dbContext);

var tools = new List<AIFunction>
{
    AIFunctionFactory.Create(
        async ([Description("The order ID number")] int orderId) =>
            await toolService.GetOrderDetailsAsync(orderId),
        "get_order_details",
        "Look up the status and details of a specific order."),

    AIFunctionFactory.Create(
        async ([Description("The order ID")] int orderId,
               [Description("The reason for the return")] string reason) =>
            await toolService.ProcessReturnAsync(orderId, reason),
        "process_return",
        "Process a return request for an order.")
};

각 AIFunctionFactory.Create 호출은 다음 세 가지 인수를 사용합니다.

  1. 각 매개 변수의 특성을 사용하여 서비스 메서드 를 래핑하는 [Description]입니다.
  2. AI 모델이 도구를 참조하는 데 사용하는 도구 이름입니다.
  3. 모델이 도구를 호출할 시기를 이해하는 데 도움이 되는 설명입니다.

매개 변수의 특성은 [Description] 중요합니다. 즉, 각 매개 변수가 나타내는 것을 AI 모델에 알려주므로 도구를 호출할 때 모델이 정확한 값을 제공하는 데 도움이 됩니다.

세션 만들기 및 구성

세션은 개별 대화 또는 작업 컨텍스트를 나타냅니다. 모델, 시스템 프롬프트, 도구 및 기타 설정을 사용하여 세션을 구성합니다.

세션 구성

세션의 동작 방식을 지정하는 데 사용합니다 SessionConfig .

var config = new SessionConfig
{
    Model = "gpt-4.1",
    SystemMessage = new SystemMessageConfig
    {
        Mode = SystemMessageMode.Replace,
        Content = @"You are a customer support agent for an e-commerce company.

CAPABILITIES:
- Look up order details
- Process returns

RULES:
- Only assist with order-related inquiries
- Always verify order details before taking action
- Be polite and professional"
    },
    Tools = tools,
    InfiniteSessions = new InfiniteSessionConfig
    {
        Enabled = false
    }
};

주요 구성 옵션:

  • 모델: 이 세션에 사용할 AI 모델을 지정합니다.
  • SystemMessage: 에이전트의 역할 및 동작을 정의합니다. 프롬프트 Mode가 기본 시스템 메시지 Replace를 교체할지 아니면 그 메시지에 추가할지 Append 여부를 결정합니다.
  • 도구: 에이전트가 사용할 수 있는 도구 정의 목록입니다.
  • InfiniteSessions: 긴 대화에 대한 자동 컨텍스트 압축을 제어합니다. 사용하도록 설정하면 BackgroundCompactionThreshold 및 BufferExhaustionThreshold을 조정하여 압축이 발생하는 시기를 제어할 수 있습니다.

세션 만들기

구성을 사용하여 클라이언트에서 세션을 만듭니다.

var session = await client.CreateSessionAsync(config);

이벤트를 사용하여 응답 처리

GitHub Copilot SDK는 통신에 이벤트 기반 모델을 사용합니다. 메시지를 보낸 후 이벤트를 구독하여 응답을 수신하고 처리가 완료된 시기를 검색합니다.

세션 이벤트 구독

session.On 메서드를 패턴 일치와 함께 사용하여 다양한 이벤트 유형을 처리합니다.

var responseBuilder = new StringBuilder();
var tcs = new TaskCompletionSource<string>();

session.On(evt =>
{
    switch (evt)
    {
        case AssistantMessageEvent msg:
            responseBuilder.Append(msg.Data.Content);
            break;

        case SessionIdleEvent:
            tcs.SetResult(responseBuilder.ToString());
            break;

        case SessionErrorEvent err:
            tcs.SetException(
                new Exception($"Agent error: {err.Data.Message}"));
            break;
    }
});

각 이벤트 유형은 다음과 같은 특정 용도로 사용됩니다.

  • AssistantMessageEvent: 에이전트 응답 텍스트의 일부를 포함합니다. 전체 응답을 작성하기 위해 이러한 메시지 조각을 누적합니다.
  • SessionIdleEvent: 에이전트가 모든 도구 호출을 포함하여 처리를 완료했음을 나타냅니다. 이 이벤트는 응답이 완료되었음을 나타냅니다.
  • SessionErrorEvent: 처리하는 동안 오류가 발생했음을 나타냅니다. 속성에 Data.Message 오류 설명이 포함되어 있습니다.

메시지 보내기 및 응답 대기

에이전트에게 사용자의 프롬프트를 보내기 위해 MessageOptions 객체와 함께 SendAsync를 사용하세요.

await session.SendAsync(new MessageOptions
{
    Prompt = "What is the status of order 12345?"
});

// Wait for the response with a timeout
var response = await tcs.Task.WaitAsync(TimeSpan.FromSeconds(30));

TaskCompletionSource 여기에 표시된 패턴을 사용하면 이벤트 기반 SDK 모델을 비동기/대기 코드와 연결할 수 있습니다. 실행되면 SessionIdleEvent 누적된 응답 텍스트를 사용하여 작업을 완료합니다.

오류 처리 모범 사례

강력한 오류 처리는 프로덕션 에이전트에 매우 중요합니다.

도구 처리기 오류

도구 핸들러를 try-catch 블록으로 감싸고, 예외를 발생시키는 대신 의미 있는 오류 메시지를 반환하세요. 도구가 오류 메시지를 반환하는 경우 AI 모델은 이를 해석하고 사용자에게 유용한 응답을 제공할 수 있습니다.

AIFunctionFactory.Create(
    async ([Description("The order ID")] int orderId) =>
    {
        try
        {
            return await toolService.GetOrderDetailsAsync(orderId);
        }
        catch (Exception ex)
        {
            return $"Error retrieving order: {ex.Message}";
        }
    },
    "get_order_details",
    "Look up the status and details of a specific order.")

세션 수준 오류 처리

에이전트 처리 중에 오류를 잡으려면 SessionErrorEvent를 사용합니다. 에이전트가 오류에 OnErrorOccurred 응답하는 방법을 제어하는 ErrorHandling 값을 반환하는 세션 후크를 구성할 수도 있습니다.

  • 다시 시도: 실패한 작업을 다시 시도합니다.
  • 건너뛰기: 실패한 결과 없이 처리를 계속합니다.
  • 중단: 처리를 중지하고 오류를 표시합니다.

타임아웃

응답을 기다리는 경우 항상 시간 제한을 설정합니다. 이전 예제에서는 에이전트에 예기치 않은 문제가 발생하는 경우 무기한 대기를 방지하는 데 사용합니다 WaitAsync(TimeSpan.FromSeconds(30)) .

시스템 프롬프트 디자인

시스템 프롬프트는 가장 중요한 구성 결정 중 하나입니다. 에이전트가 누구인지, 수행할 수 있는 작업 및 동작 방식을 정의합니다. 잘 구성된 시스템 프롬프트에는 일반적으로 다음이 포함됩니다.

  • 역할 정의: 에이전트가 나타내는 내용(예: "ContosoShop의 고객 지원 에이전트").
  • 기능: 사용할 수 있는 도구 및 수행하는 기능
  • 워크플로 지침: 에이전트가 작업에 접근하는 방법(예: "반환을 처리하기 전에 항상 주문 세부 정보 확인").
  • 규칙 및 제약 조건: 에이전트가 따라야 하는 경계(예: "주문 관련 항목만 논의" 또는 "$100 이상 환불 요청 에스컬레이션").

시스템 프롬프트를 집중적이고 구체적으로 유지합니다. 모호한 지침은 예측할 수 없는 동작으로 이어지지만 지나치게 제한적인 규칙은 에이전트를 도움이 되지 않게 만들 수 있습니다.

델타 이벤트를 사용하여 응답 스트리밍

채팅 UI와 같은 대화형 애플리케이션의 경우 전체 메시지를 기다리는 대신 토큰으로 에이전트의 응답 토큰을 스트리밍할 수 있습니다. 각 부분 토큰이 도착할 때마다 이를 캡처하는 데 AssistantMessageDeltaEvent를 사용합니다.

session.On(evt =>
{
    switch (evt)
    {
        case AssistantMessageDeltaEvent delta:
            // Render each token as it arrives
            Console.Write(delta.Data.DeltaContent);
            break;

        case SessionIdleEvent:
            Console.WriteLine();
            tcs.SetResult("Done");
            break;

        case SessionErrorEvent err:
            tcs.SetException(
                new Exception($"Agent error: {err.Data.Message}"));
            break;
    }
});

속성에는 DeltaContent 증분 텍스트 조각이 포함됩니다. 스트리밍은 모델이 전체 메시지를 생성할 때까지 기다리지 않고 응답이 형성되는 것으로 표시되기 때문에 보다 반응성이 뛰어난 환경을 제공합니다.

요약

GitHub Copilot SDK는 컨텍스트를 추론, 사용 및 유지 관리할 수 있는 AI 에이전트를 구현하기 위한 강력한 프레임워크를 제공합니다. 도구를 통해 에이전트의 기능을 정의하고, 명확한 시스템 프롬프트를 사용하여 세션을 구성하고, 이벤트로 응답을 처리하면 실제 비즈니스 가치를 제공하는 정교한 에이전트를 빌드할 수 있습니다. 강력한 오류 처리 및 신중한 프롬프트 디자인은 에이전트가 프로덕션 시나리오에서 안정적이고 효과적으로 작동하도록 하는 데 중요합니다. 다음 단원에서는 GitHub Copilot SDK를 사용하여 샘플 고객 지원 에이전트를 빌드하기 위해 이러한 구현 패턴을 적용하는 방법을 알아보세요.