Microsoft Agent Framework 에이전트 유형

유추 서비스를 기반으로 하는 간단한 에이전트

에이전트 프레임워크를 사용하면 다양한 유추 서비스를 기반으로 간단한 에이전트를 쉽게 만들 수 있습니다. 구현을 제공하는 Microsoft.Extensions.AI.IChatClient 모든 유추 서비스를 사용하여 이러한 에이전트를 빌드할 수 있습니다. Microsoft.Agents.AI.ChatClientAgent은 모든 IChatClient 구현에 대해 에이전트를 제공하는 데 사용되는 에이전트 클래스입니다.

이러한 에이전트는 다음과 같은 다양한 기능을 지원합니다.

1. 함수 호출
2. 로컬 채팅 기록 관리 또는 서비스에서 제공한 채팅 기록 관리와 다중 턴 대화
3. 사용자 지정 서비스 제공 도구(예: MCP, 코드 실행)
4. 구조적 출력

이러한 에이전트 중 하나를 만들려면 선택한 구현을 ChatClientAgentIChatClient 사용하여 구성하기만 하면 됩니다.

using Microsoft.Agents.AI;

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

많은 인기 있는 서비스의 경우 이러한 에이전트를 더욱 쉽게 만들 수 있는 도우미도 있습니다. 자세한 내용은 각 서비스에 대한 설명서를 참조하세요.

복잡한 사용자 지정 에이전트

사용자 지정 에이전트를 만들어, 이 에이전트가 IChatClient을(를) 단순히 감싸는 래퍼가 아닐 수도 있습니다. 에이전트 프레임워크는 기본 형식을 AIAgent 제공합니다. 이 기본 형식은 모든 에이전트의 핵심 추상화이며, 서브클래스를 사용하면 에이전트의 동작 및 기능을 완벽하게 제어할 수 있습니다.

자세한 내용은 사용자 지정 에이전트 에 대한 설명서를 참조하세요.

원격 에이전트에 대한 프록시

에이전트 프레임워크는 A2A와 같은 일반적인 서비스 호스팅 에이전트 프로토콜에 대한 기본 AIAgent 구현을 제공합니다. 이렇게 하면 애플리케이션에서 원격 에이전트에 쉽게 연결하고 사용할 수 있습니다.

자세한 내용은 각 에이전트 유형에 대한 설명서를 참조하세요.

Azure 및 OpenAI SDK 옵션 참조

Azure AI Foundry, Azure OpenAI 또는 OpenAI 서비스를 사용하는 경우 이러한 서비스에 연결할 수 있는 다양한 SDK 옵션이 있습니다. 경우에 따라 여러 SDK를 사용하여 동일한 서비스에 연결하거나 동일한 SDK를 사용하여 다른 서비스에 연결할 수 있습니다. 다음은 각각에 연결할 때 사용해야 하는 URL과 함께 사용할 수 있는 다양한 옵션 목록입니다. 실제 리소스 및 프로젝트 이름으로 <resource> 및 <project>를 대체해야 합니다.

1. Azure OpenAI에서 Azure AI Foundry로 업그레이드
2. OpenAI SDK를 사용하는 것이 좋습니다.
3. OpenAI SDK를 사용하여 Azure AI Foundry 모델에 액세스하는 것이 좋지만 Azure AI Foundry 모델은 OpenAI뿐만 아니라 여러 공급업체의 모델을 지원합니다. 이러한 모든 모델은 OpenAI SDK를 통해 지원됩니다.

OpenAI SDK 사용

위의 표와 같이 OpenAI SDK를 사용하여 여러 서비스에 연결할 수 있습니다. 연결하는 서비스에 따라 만들 OpenAIClient때 사용자 지정 URL을 설정해야 할 수 있습니다. 서비스에 따라 다른 인증 메커니즘을 사용할 수도 있습니다.

사용자 지정 URL이 필요한 경우(위 표 참조) OpenAIClientOptions를 통해 설정할 수 있습니다.

var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri(serviceUrl) };

클라이언트를 만들 때 API 키를 사용할 수 있습니다.

OpenAIClient client = new OpenAIClient(new ApiKeyCredential(apiKey), clientOptions);

Azure 서비스를 사용하는 경우 API 키 대신 Azure 자격 증명을 사용할 수도 있습니다.

OpenAIClient client = new OpenAIClient(new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"), clientOptions)

OpenAIClient를 만든 후에는 사용하려는 특정 서비스에 대한 하위 클라이언트를 가져온 다음, 이를 통해 AIAgent를 생성할 수 있습니다.

AIAgent agent = client
    .GetChatClient(model)
    .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

Azure OpenAI SDK 사용

이 SDK는 Azure OpenAI 및 Azure AI Foundry Models 서비스에 연결하는 데 사용할 수 있습니다. 어느 쪽이든, 를 만들 때 올바른 서비스 URL을 AzureOpenAIClient제공해야 합니다. 사용할 올바른 URL은 위의 표를 참조하세요.

AIAgent agent = new AzureOpenAIClient(
    new Uri(serviceUrl),
    new AzureCliCredential())
     .GetChatClient(deploymentName)
     .CreateAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

Azure AI 영구 에이전트 SDK 사용

이 SDK는 Azure AI Foundry Agents 서비스에서만 지원됩니다. 사용할 올바른 URL은 위의 표를 참조하세요.

var persistentAgentsClient = new PersistentAgentsClient(serviceUrl, new AzureCliCredential());
AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
    model: deploymentName,
    name: "Joker",
    instructions: "You are good at telling jokes.");

유추 서비스를 기반으로 하는 간단한 에이전트

에이전트 프레임워크를 사용하면 다양한 유추 서비스를 기반으로 간단한 에이전트를 쉽게 만들 수 있습니다. 채팅 클라이언트 구현을 제공하는 모든 유추 서비스를 사용하여 이러한 에이전트를 빌드할 수 있습니다.

이러한 에이전트는 다음과 같은 다양한 기능을 지원합니다.

1. 함수 호출
2. 로컬 채팅 기록 관리 또는 서비스에서 제공한 채팅 기록 관리와 다중 턴 대화
3. 사용자 지정 서비스 제공 도구(예: MCP, 코드 실행)
4. 구조적 출력
5. 스트리밍 응답

이러한 에이전트 중 하나를 만들려면 선택한 채팅 클라이언트 구현을 ChatAgent 사용하여 구성하기만 하면 됩니다.

from agent_framework import ChatAgent
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with (
    DefaultAzureCredential() as credential,
    ChatAgent(
        chat_client=AzureAIAgentClient(async_credential=credential),
        instructions="You are a helpful assistant"
    ) as agent
):
    response = await agent.run("Hello!")

또는 채팅 클라이언트에서 편의 메서드를 사용할 수 있습니다.

from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with DefaultAzureCredential() as credential:
    agent = AzureAIAgentClient(async_credential=credential).create_agent(
        instructions="You are a helpful assistant"
    )

자세한 예제는 아래 에이전트 관련 설명서 섹션을 참조하세요.

지원되는 에이전트 유형

함수 도구

향상된 기능을 위해 에이전트에 함수 도구를 제공할 수 있습니다.

from typing import Annotated
from pydantic import Field
from azure.identity.aio import DefaultAzureCredential
from agent_framework.azure import AzureAIAgentClient

def get_weather(location: Annotated[str, Field(description="The location to get the weather for.")]) -> str:
    """Get the weather for a given location."""
    return f"The weather in {location} is sunny with a high of 25°C."

async with (
    DefaultAzureCredential() as credential,
    AzureAIAgentClient(async_credential=credential).create_agent(
        instructions="You are a helpful weather assistant.",
        tools=get_weather
    ) as agent
):
    response = await agent.run("What's the weather in Seattle?")

함수 도구를 사용하는 전체 예제는 다음을 참조하세요.

• 함수 도구를 사용하는 Azure AI
• 함수 도구를 사용하는 Azure OpenAI
• 함수 도구를 사용하는 OpenAI

스트리밍 응답

에이전트는 일반 및 스트리밍 응답을 모두 지원합니다.

# Regular response (wait for complete result)
response = await agent.run("What's the weather like in Seattle?")
print(response.text)

# Streaming response (get results as they are generated)
async for chunk in agent.run_stream("What's the weather like in Portland?"):
    if chunk.text:
        print(chunk.text, end="", flush=True)

스트리밍 예제는 다음을 참조하세요.

• Azure AI 스트리밍 예제
• Azure OpenAI 스트리밍 예제
• OpenAI 스트리밍 예제

코드 인터프리터 도구

Azure AI 에이전트는 Python 코드를 실행하기 위한 호스트된 코드 인터프리터 도구를 지원합니다.

from agent_framework import ChatAgent, HostedCodeInterpreterTool
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential

async with (
    DefaultAzureCredential() as credential,
    ChatAgent(
        chat_client=AzureAIAgentClient(async_credential=credential),
        instructions="You are a helpful assistant that can execute Python code.",
        tools=HostedCodeInterpreterTool()
    ) as agent
):
    response = await agent.run("Calculate the factorial of 100 using Python")

코드 인터프리터 예제는 다음을 참조하세요.

• 코드 인터프리터를 사용하는 Azure AI
• 코드 인터프리터가 있는 Azure OpenAI Assistants
• 코드 인터프리터가 있는 OpenAI Assistants

사용자 지정 에이전트

채팅 클라이언트에 대한 래퍼가 아닌 완전히 사용자 지정 에이전트를 만들 수도 있습니다. 에이전트 프레임워크는 프로토콜 및 AgentProtocol 기본 클래스를 제공 BaseAgent 하며, 구현/서브클래스를 사용하면 에이전트의 동작 및 기능을 완벽하게 제어할 수 있습니다.

from agent_framework import BaseAgent, AgentRunResponse, AgentRunResponseUpdate, AgentThread, ChatMessage
from collections.abc import AsyncIterable

class CustomAgent(BaseAgent):
    async def run(
        self,
        messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
        *,
        thread: AgentThread | None = None,
        **kwargs: Any,
    ) -> AgentRunResponse:
        # Custom agent implementation
        pass

    def run_stream(
        self,
        messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
        *,
        thread: AgentThread | None = None,
        **kwargs: Any,
    ) -> AsyncIterable[AgentRunResponseUpdate]:
        # Custom streaming implementation
        pass