7단계: 에이전트 호스팅하기

Microsoft 관리형 Foundry 호스트 에이전트, 자체 호스팅 및 Durable Extension을 사용한 Durable 실행을 비교하려면 호스팅 에이전트 프레임워크 애플리케이션을 참조하세요.

ASP.NET Core에서 호스팅

에이전트 프레임워크는 AI 에이전트를 ASP.NET Core 애플리케이션에 통합할 수 있는 호스팅 라이브러리를 제공합니다. 이러한 라이브러리는 다양한 프로토콜을 통해 에이전트 등록, 구성 및 노출을 간소화합니다.

에이전트에 설명된 대로 에이전트AIAgent 프레임워크의 기본 에이전트 추상화입니다. 사용자 입력을 처리하고, 의사 결정을 내리고, 도구를 호출하고, 작업을 실행하고 응답을 생성하는 추가 작업을 수행하는 "LLM 래퍼"를 정의합니다. ASP.NET Core 애플리케이션에서 AI 에이전트를 노출하는 것은 간단하지 않습니다. 호스팅 라이브러리는 애플리케이션 서비스에서 AI 에이전트를 확인하고 사용할 수 있도록 종속성 주입 컨테이너에 AI 에이전트를 등록하여 이 문제를 해결합니다. 또한 동일한 컨테이너에서 도구 및 세션 스토리지와 같은 에이전트 종속성을 관리할 수 있습니다. 에이전트는 사용하는 프로토콜과 관계없이 애플리케이션 인프라와 함께 호스트될 수 있습니다. 마찬가지로 워크플로를 호스트하고 애플리케이션의 공통 인프라를 활용할 수 있습니다.

핵심 호스팅 라이브러리

라이브러리는 Microsoft.Agents.AI.Hosting ASP.NET Core에서 AI 에이전트를 호스팅하기 위한 기반입니다. AI 에이전트 및 워크플로를 등록하고 구성하기 위한 IHostApplicationBuilder 확장을 제공합니다. ASP.NET Core IHostApplicationBuilder 에서는 호스트된 애플리케이션 및 서비스, 구성 관리, 로깅, 수명 등에 대한 작성기를 나타내는 기본 형식입니다.

에이전트 또는 워크플로를 구성하기 전에 IChatClient을(를) 종속성 주입 컨테이너에 등록하십시오. 아래 예제에서는 이름 chat-model아래에 키가 지정된 싱글톤으로 등록됩니다.

// endpoint is your Microsoft Foundry project endpoint
// deploymentName is 'gpt-4o-mini' for example

IChatClient chatClient = new AIProjectClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetProjectOpenAIClient()
    .GetProjectResponsesClient()
    .AsIChatClient(deploymentName);
builder.Services.AddSingleton(chatClient);

Warning

DefaultAzureCredential 은 개발에 편리하지만 프로덕션 환경에서 신중하게 고려해야 합니다. 프로덕션 환경에서는 특정 자격 증명(예: ManagedIdentityCredential)을 사용하여 대기 시간 문제, 의도하지 않은 자격 증명 검색 및 대체 메커니즘의 잠재적인 보안 위험을 방지하는 것이 좋습니다.

AddAIAgent

종속성 주입을 사용하여 AI 에이전트를 등록합니다.

var pirateAgent = builder.AddAIAgent(
    "pirate",
    instructions: "You are a pirate. Speak like a pirate",
    description: "An agent that speaks like a pirate.",
    chatClientServiceKey: "chat-model");

이 AddAIAgent() 메서드는 에이전트를 구성하기 위한 확장 메서드를 제공하는 IHostedAgentBuilder를 반환합니다. 예를 들어 에이전트에 도구를 추가할 수 있습니다.

var pirateAgent = builder.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate")
    .WithAITool(new MyTool()); // MyTool is a custom type derived from AITool

세션 저장소(대화 데이터에 대한 스토리지)를 구성할 수도 있습니다.

var pirateAgent = builder.AddAIAgent("pirate", instructions: "You are a pirate. Speak like a pirate")
    .WithInMemorySessionStore();

AddWorkflow

여러 에이전트를 조정하는 워크플로를 등록합니다. 워크플로는 기본적으로 각 노드가 있고 에이전트가 서로 통신하는 "그래프"입니다 AIAgent.

이 예제에서는 두 에이전트가 순차적으로 작동합니다. 사용자 입력이 먼저 전송 agent-1되어 응답을 생성하고 보냅니다 agent-2. 그런 다음 워크플로가 최종 응답을 출력합니다. 동시 에이전트 워크플로를 만드는 메서드도 BuildConcurrent 있습니다.

builder.AddAIAgent("agent-1", instructions: "you are agent 1!");
builder.AddAIAgent("agent-2", instructions: "you are agent 2!");

var workflow = builder.AddWorkflow("my-workflow", (sp, key) =>
{
    var agent1 = sp.GetRequiredKeyedService<AIAgent>("agent-1");
    var agent2 = sp.GetRequiredKeyedService<AIAgent>("agent-2");
    return AgentWorkflowBuilder.BuildSequential(key, [agent1, agent2]);
});

워크플로를 AIAgent로 노출

워크플로와 함께 프로토콜 통합(예: A2A 또는 OpenAI)을 사용하려면 독립 실행형 에이전트로 변환합니다. 현재 워크플로는 자체적으로 유사한 통합 기능을 제공하지 않으므로 이 변환 단계가 필요합니다.

var workflowAsAgent = builder
    .AddWorkflow("science-workflow", (sp, key) => { ... })
    .AddAsAIAgent();  // Now the workflow can be used as an agent

구현 세부 정보

호스팅 라이브러리는 외부 통신 프로토콜과 에이전트 프레임워크의 내부 AIAgent 구현을 연결하는 프로토콜 어댑터 역할을 합니다. 호스팅 통합 라이브러리를 사용하는 경우, 라이브러리는 종속성 주입에서 등록된 AIAgent을 검색하고, 프로토콜별 미들웨어로 래핑하여 들어오는 요청과 나가는 응답을 변환한 뒤 AIAgent을 호출하여 요청을 처리합니다. 이 아키텍처는 에이전트 구현을 특정 프로토콜에 구애받지 않게 유지합니다.

예를 들어 A2A 프로토콜 어댑터와 함께 ASP.NET Core 호스팅 라이브러리를 사용합니다.

// Register the agent
var pirateAgent = builder.AddAIAgent("pirate",
    instructions: "You are a pirate. Speak like a pirate",
    description: "An agent that speaks like a pirate.");

// Expose via a protocol (e.g. A2A)
builder.Services.AddA2AServer();
var app = builder.Build();
app.MapA2AServer();
app.Run();

Microsoft Foundry Hosted Agents는 기본 관리형 호스팅 옵션입니다. Azure Developer CLI AI 에이전트 확장 및 Azure CLI 로그인을 포함하여 Foundry 호스트 에이전트 필수 구성 요소를 완료합니다.

시작 샘플은 서버 쪽 모델 스토리지를 사용하지 않도록 설정된 에이전트를 만들고 ResponsesHostServer를 시작합니다.

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, ResponsesHostServer
from azure.identity import DefaultAzureCredential


def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint="https://your-account.services.ai.azure.com/api/projects/your-project",
            model="gpt-6-luna",
            credential=DefaultAzureCredential(),
        ),
        instructions="You are a friendly assistant. Keep your answers brief.",
        default_options={"store": False},
    )
    ResponsesHostServer(agent=agent, history_source="agent_server").run()


if __name__ == "__main__":
    main()

하드 코딩된 프로젝트 엔드포인트 및 모델 배포 이름을 바꾼 다음 Agent Framework 리포지토리 루트에서 로컬로 PEP 723 샘플을 실행합니다.

uv run python/samples/01-get-started/07_hosting.py

전체 호스트 에이전트 프로젝트를 배포하려면 유지 관리되는 샘플의 azure.yaml로 초기화합니다.

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -t https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml --src .

에이전트 호스트를 실행하세요:

azd ai agent run

다른 터미널에서 로컬 에이전트를 실행하세요.

azd ai agent invoke --local "Hello!"

Tip

전체 시작하기 샘플 및 전체 배포 샘플을 참조하세요. 배포 지침은 Foundry Hosted Agents를 참조하세요.

A2A 프로토콜을 사용하여 호스팅

Go 포트는 a2aprovider를 통해 A2A 호스팅을 제공하며, 여기서 a2aprovider는 에이전트를 Agent-to-Agent 프로토콜과 호환되는 HTTP 핸들러로 래핑합니다.

비고

지속성 확장 호스팅은 현재 Go에서 사용할 수 없습니다. 최신 Go SDK 상태는 에이전트 프레임워크 Go 리포지토리를 참조하세요.

에이전트를 만듭니다.

import (
    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/a2aprovider"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"

    "github.com/a2aproject/a2a-go/v2/a2a"
    "github.com/a2aproject/a2a-go/v2/a2asrv"
)

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Instructions: "You are a helpful assistant.",
    Config: agent.Config{
    },
})

A2A를 통해 에이전트 공개하기:

url := "http://localhost:5000"
card := &a2a.AgentCard{
    Name:               "MyAgent",
    Description:        "A helpful assistant.",
    Version:            "1.0.0",
    DefaultInputModes:  []string{"text"},
    DefaultOutputModes: []string{"text"},
    Capabilities:       a2a.AgentCapabilities{Streaming: false},
    SupportedInterfaces: []*a2a.AgentInterface{
        a2a.NewAgentInterface(url, a2a.TransportProtocolJSONRPC),
    },
}

mux := http.NewServeMux()
requestHandler := a2asrv.NewHandler(
    a2aprovider.NewExecutor(a, a2aprovider.ExecutorConfig{}),
    a2asrv.WithExtendedAgentCard(card),
)
mux.Handle("/", a2asrv.NewJSONRPCHandler(requestHandler))
mux.Handle(a2asrv.WellKnownAgentCardPath, a2asrv.NewStaticAgentCardHandler(card))

log.Println("A2A server listening on :5000")
http.ListenAndServe(":5000", mux)

Tip

전체 실행 가능한 예제는 전체 A2A 클라이언트 서버 샘플을 참조하세요.

다음 단계

에이전트

더 자세히 살펴보기:

참고하십시오

  • 에 마지막으로 업데이트됨