에이전트 파이프라인 아키텍처

Microsoft Agent Framework의 에이전트는 계층화된 파이프라인 아키텍처를 사용하여 요청을 처리합니다. 이 아키텍처를 이해하면 적절한 계층에서 미들웨어, 컨텍스트 공급자 또는 클라이언트 수준 수정을 추가하여 에이전트 동작을 사용자 지정할 수 있습니다.

챗클라이언트에이전트 파이프라인

C# 에이전트 파이프라인 아키텍처

세 개의 주요 계층으로 구성된 파이프라인을 ChatClientAgent 빌드합니다.

에이전트 미들웨어 - 로깅, 유효성 검사 또는 변환을 위해 .Use() 에이전트를 래핑하는 선택적 데코레이터
컨텍스트 계층 - 채팅 기록 관리(ChatHistoryProvider) 및 추가 컨텍스트 삽입(AIContextProviders)
채팅 클라이언트 계층 - LLM 통신을 처리하는 선택적 미들웨어 데코레이터가 포함된 IChatClient

호출 RunAsync()할 때 요청은 각 계층을 순서대로 통과합니다.

에이전트 파이프라인

Python 에이전트 파이프라인 아키텍처

클래스는 Agent 다음 두 가지 주요 구성 요소를 사용하여 클래스 컴퍼지션을 통해 파이프라인을 빌드합니다.

에이전트 (외부 구성 요소):

에이전트 미들웨어 + 원격 분석 - AgentMiddlewareLayer 및 AgentTelemetryLayer 클래스는 미들웨어 호출 및 OpenTelemetry 계측을 처리합니다.
RawAgent - 컨텍스트 공급자를 호출하는 핵심 에이전트 논리
컨텍스트 공급자 - 통합 context_providers 목록은 기록 및 추가 컨텍스트를 관리합니다.

ChatClient (분리 및 교환 가능한 구성 요소):

채팅 미들웨어 + 원격 분석 - 선택적 미들웨어 체인 및 계측 계층
FunctionInvocation - 도구 호출 루프를 처리하며, 각 도구 호출에 대해 함수 미들웨어와 원격 분석을 호출합니다.
RawChatClient - LLM과 통신하는 공급자별 구현(Azure OpenAI, OpenAI, Anthropic 등)

호출 run()할 때 요청은 에이전트 계층을 통과한 다음 LLM 통신을 위한 ChatClient 파이프라인으로 이동합니다.

에이전트 미들웨어 계층

에이전트 미들웨어는 에이전트의 실행 메서드에 대한 모든 호출을 가로채 입력 및 출력을 검사하거나 수정할 수 있도록 합니다.

에이전트 작성기 패턴을 사용하여 미들웨어를 추가합니다.

var middlewareAgent = originalAgent
    .AsBuilder()
    .Use(runFunc: MyAgentMiddleware, runStreamingFunc: MyStreamingMiddleware)
    .Build();

에이전트 미들웨어로 사용하여 MessageAIContextProvider 요청에 추가 메시지를 삽입할 수도 있습니다. 이 작업은 ChatClientAgent뿐만 아니라 모든 에이전트 유형에서 작동합니다.

var contextAgent = originalAgent
    .AsBuilder()
    .UseAIContextProviders(new MyMessageContextProvider())
    .Build();

이 계층은 컨텍스트 확인 및 채팅 클라이언트 호출을 포함하여 전체 에이전트 실행을 래핑합니다. 이는 이러한 데코레이터를 특정 ChatClientAgent뿐만 아니라 모든 유형의 에이전트, 예를 들어 A2AAgent 또는 GitHubCopilotAgent와 함께 사용할 수 있다는 점에서 이점이 있습니다. 이는 또한 이 수준의 데코레이터가 데코레이팅 중인 에이전트에 대해 반드시 가정할 수 없다는 것을 의미합니다. 즉, 일반적인 기능을 사용자 지정하거나 영향을 주는 것으로 제한됩니다.

에이전트를 만들 때 미들웨어를 추가합니다.

from agent_framework import Agent

agent = Agent(
    client=my_client,
    instructions="You are helpful.",
    middleware=[my_middleware_func],
)

클래스 Agent는 AgentMiddlewareLayer를 상속하며, 이는 핵심 에이전트 논리에 위임하기 전에 미들웨어 호출을 처리합니다. 또한, AgentTelemetryLayer로부터 상속되어 구성된 OpenTelemetry 백엔드로 스팬, 이벤트 및 메트릭을 전달하는 역할을 수행합니다. 이 두 계층은 모두 구성되지 않은 경우 아무 것도 수행하지 않습니다.

자세한 미들웨어 및 관찰 패턴은 에이전트 미들웨어 및 관찰 가능성을 참조하세요.

컨텍스트 계층

컨텍스트 계층은 각 LLM 호출 전에 실행되어 전체 메시지 기록을 빌드하고 추가 컨텍스트를 삽입합니다.

ChatClientAgent 에는 두 가지 고유한 공급자 유형이 있습니다.

ChatHistoryProvider (단일) - 대화 기록 스토리지 및 검색 관리
AIContextProviders (목록) - 추억, 검색된 문서 또는 동적 지침과 같은 추가 컨텍스트를 삽입합니다.

var agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
{
    ChatHistoryProvider = new InMemoryChatHistoryProvider(),
    AIContextProviders = [new MyMemoryProvider(), new MyRagProvider()],
});

에이전트는 각 공급자의 InvokingAsync() 출력이 다음 공급자에게 입력으로 전달된 채 채팅 클라이언트에 메시지를 보내기 전에 각 공급자의 메서드를 호출합니다.

이 클래스는 Agent 기록 공급자와 컨텍스트 공급자를 모두 포함할 수 있는 통합 context_providers 목록을 사용합니다.

from agent_framework import Agent, InMemoryHistoryProvider

agent = Agent(
    client=my_client,
    context_providers=[
        InMemoryHistoryProvider(),
        MyMemoryProvider(),
        MyRagProvider(),
    ],
)

자세한 컨텍스트 공급자 패턴은 컨텍스트 공급자를 참조하세요.

채팅 클라이언트 계층

채팅 클라이언트 계층은 LLM 서비스와의 실제 통신을 처리합니다.

ChatClientAgent IChatClient 는 추가 미들웨어로 데코레이팅할 수 있는 인스턴스를 사용합니다.

var chatClient = new AzureOpenAIClient(endpoint, credential)
    .GetChatClient(deploymentName)
    .AsIChatClient()
    .AsBuilder()
    .Use(CustomChatClientMiddleware)
    .Build();

var agent = new ChatClientAgent(chatClient, instructions: "You are helpful.");

채팅 클라이언트 미들웨어로 사용하여 AIContextProvider 클라이언트 수준에서 메시지, 도구 및 지침을 보강할 수도 있습니다. 실행 중인 AIAgent 컨텍스트 내에서 사용해야 합니다.

var chatClient = new AzureOpenAIClient(endpoint, credential)
    .GetChatClient(deploymentName)
    .AsIChatClient()
    .AsBuilder()
    .UseAIContextProviders(new MyContextProvider())
    .Build();

var agent = new ChatClientAgent(chatClient, instructions: "You are helpful.");

기본적으로 ChatClientAgent 제공된 채팅 클라이언트를 함수 호출 지원으로 래핑합니다. 기본 래핑을 건너뛰려면 옵션에서 UseProvidedChatClientAsIs = true을(를) 설정하세요.

클래스는 Agent 구현하는 모든 클라이언트를 허용합니다 SupportsChatGetResponse. ChatClient 파이프라인은 미들웨어, 원격 분석, 함수 호출 및 공급자별 통신을 처리합니다.

from agent_framework import Agent
from agent_framework.azure import AzureOpenAIResponsesClient

client = AzureOpenAIResponsesClient(
    credential=credential,
    project_endpoint=endpoint,
    deployment_name=model,
)

agent = Agent(client=client, instructions="You are helpful.")

ChatClient 내에서는 RawChatClient 서로 다른 LLM 서비스와 통신하기 위한 공급자별 논리를 구현합니다.

실행 흐름

에이전트를 호출하면 요청이 파이프라인을 통해 흐릅니다.

에이전트 미들웨어 실행(구성된 경우)
ChatHistoryProvider 가 요청 메시지 목록에 대화 기록을 로드합니다.
AIContextProviders가 요청에 메시지, 도구 또는 지침을 추가합니다.
IChatClient 미들웨어 가 실행됩니다(데코레이팅된 경우).
IChatClient 가 LLM에 요청을 보냅니다.
응답은 동일한 계층을 통해 다시 흐릅니다.
ChatHistoryProvider 및 AIContextProviders 에 새 메시지 알림이 표시됩니다.

에이전트 파이프라인:

에이전트 미들웨어 + 원격 분석은 중간웨어를 (구성된 경우) 실행하고 스팬을 기록합니다.
RawAgent 는 컨텍스트 공급자를 호출하여 기록을 로드하고 컨텍스트를 추가합니다.
요청이 ChatClient에 전달됩니다.

ChatClient 파이프라인:

채팅 미들웨어 + 원격 분석 실행(구성된 경우)
FunctionInvocation 은 LLM에 요청을 보내고 도구 호출 루프를 처리합니다.
- 각 도구 호출에 대해 함수 미들웨어 + 원격 분석 이 실행됩니다.
RawChatClient 는 공급자별 LLM 통신을 처리합니다.
응답은 동일한 계층을 통해 다시 흐릅니다.
컨텍스트 공급자는 스토리지에 대한 새 메시지 알림을 받습니다.

메모

특수 에이전트는 여기에 설명된 파이프라인과 다르게 작동할 수 있습니다.

기타 에이전트 유형

모든 에이전트가 전체 ChatClientAgent 파이프라인을 사용하는 것은 아닙니다. 에이전트A2AAgent, GitHubCopilotAgent, CopilotStudioAgent는 로컬 IChatClient 대신 원격 서비스와 통신합니다. 그러나 여전히 에이전트 수준 미들웨어를 지원합니다.

다른 유형의 에이전트 파이프라인

이러한 에이전트는 파생 AIAgent되므로 동일한 에이전트 미들웨어 패턴을 사용할 수 있습니다.

// Agent middleware works with any AIAgent
var a2aAgent = originalA2AAgent
    .AsBuilder()
    .Use(runFunc: LoggingMiddleware)
    .UseAIContextProviders(new MyMessageContextProvider())
    .Build();

// Same pattern works for GitHubCopilotAgent
var copilotAgent = originalCopilotAgent
    .AsBuilder()
    .Use(runFunc: AuditMiddleware)
    .Build();

메모

이러한 에이전트는 IChatClient 기능을 사용하지 않으므로 채팅 클라이언트 미들웨어를 추가할 수 없습니다.

다음 단계

멀티모달

미들웨어 - 에이전트에 공용 동작을 추가합니다
컨텍스트 공급자 - 기록 및 컨텍스트 삽입에 대한 자세한 패턴
에이전트 실행 - 에이전트 를 호출하는 방법

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-03-13