파운드리 호스팅 에이전트

Microsoft Foundry 에이전트 서비스의 호스트 에이전트를 사용하면 에이전트 프레임워크 에이전트를 컨테이너화된 애플리케이션으로 Microsoft 관리형 인프라에 배포할 수 있습니다. 플랫폼은 스케일링, 세션 상태 지속성, 보안 및 수명 주기 관리를 처리하므로 에이전트의 논리에 집중할 수 있습니다.

에이전트 프레임워크 호스팅 통합을 사용하면 Agent 또는 워크플로를 minimal한 코드로 Foundry Responses 또는 Invocations 프로토콜을 통해 노출할 수 있습니다.

호스트된 에이전트를 사용하는 경우

원하는 경우 Foundry 호스팅 에이전트를 선택합니다.

• 관리형 인프라 - 컨테이너, 웹 서버 또는 크기 조정 규칙을 직접 구성할 필요가 없습니다.
• 기본 제공 세션 관리 - 플랫폼은 $HOME 턴 및 유휴 기간에 걸쳐 파일을 유지 및 업로드합니다.
• 전용 에이전트 ID - 배포된 모든 에이전트는 모델, 도구 및 다운스트림 서비스에 대한 보안 액세스를 위해 자체 Entra ID를 가져옵니다.
• OpenAI 호환 엔드포인트 - 클라이언트는 응답 프로토콜을 통해 OpenAI 호환 SDK를 사용하여 에이전트와 상호 작용할 수 있습니다.

메모

Foundry 호스팅 에이전트는 현재 미리 보기로 제공됩니다. 최신 가용성, 제한 및 가격은 Foundry 호스팅 에이전트 설명서를 참조하세요.

필수 조건

• Azure 구독
• Azure AI 에이전트 확장을 사용하는 개발자 CLI(azd): azd ext install azure.ai.agents

로컬 테스트의 경우 다음이 필요합니다.

• 모델 배포가 있는 Microsoft Foundry 프로젝트(예: gpt-4o)
• Azure CLI 설치 및 인증(az login)

• .NET 10 SDK 이상

호스팅 NuGet 패키지를 설치합니다.

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
dotnet add package Azure.AI.Projects --prerelease

• Python 3.10 이상

호스팅 Python 패키지를 설치합니다.

pip install agent-framework agent-framework-foundry-hosting

응답 프로토콜

응답 프로토콜은 대부분의 에이전트에 권장되는 시작점입니다. OpenAI 호환 /responses 엔드포인트를 노출하고 플랫폼은 대화 기록, 스트리밍 및 세션 수명 주기를 자동으로 관리합니다.

using Azure.AI.AgentServer.Core;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

var projectEndpoint = new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));
var deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";

AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a helpful AI assistant.",
        name: "my-agent");

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

var app = builder.Build();
app.Run();

Foundry AgentHost.CreateBuilder 호스팅 환경에 대해 미리 구성된 애플리케이션 호스트를 만듭니다. AddFoundryResponses 는 에이전트를 응답 프로토콜 처리기에 등록하고 MapFoundryResponses HTTP 엔드포인트를 /responses 매핑합니다.

import os

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

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a helpful AI assistant.",
    default_options={"store": False},
)

server = ResponsesHostServer(agent)
server.run()

에이전트 ResponsesHostServer 를 래핑하고 Foundry 응답 프로토콜을 통해 노출합니다. 호스팅 인프라가 대화 기록을 자동으로 관리하므로, default_options의 store를 False으로 설정하면 기록이 중복되는 것을 방지할 수 있습니다.

호출 프로토콜

호출 프로토콜을 사용하면 HTTP 요청 및 응답을 완전히 제어할 수 있습니다. OpenAI와 호환되지 않는 사용자 지정 페이로드, 비대화 처리 또는 스트리밍 프로토콜이 필요할 때 사용합니다.

C#의 호출 프로토콜을 사용하면 들어오는 요청을 처리하는 사용자 지정 InvocationHandler 을 구현합니다.

using Azure.AI.AgentServer.Core;
using Azure.AI.AgentServer.Invocations;
using Microsoft.Agents.AI;

var builder = AgentHost.CreateBuilder(args);

builder.Services.AddSingleton<AIAgent, MyAgent>();
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

builder.RegisterProtocol("invocations", endpoints => endpoints.MapInvocationsServer());

var app = builder.Build();
app.Run();

메서드는 AddInvocationsServer 호출 프로토콜 서비스를 등록합니다. 에이전트가 각 요청을 처리하는 방법을 정의하기 위해 구현 InvocationHandler 합니다.

간단한 설정의 경우 패키지에서 InvocationsHostServer 사용합니다agent_framework_foundry_hosting. 이 도구는 에이전트를 ResponsesHostServer와 유사하게 래핑하고, 세션을 자동으로 관리하여 처리합니다.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import InvocationsHostServer
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

server = InvocationsHostServer(agent)
server.run()

요청 처리를 완전히 제어하려면 패키지에서 InvocationAgentServerHost 직접 사용하고 azure.ai.agentserver.invocations 고유한 호출 처리기를 구현합니다.

import os
from collections.abc import AsyncGenerator

from agent_framework import Agent, AgentSession
from agent_framework.foundry import FoundryChatClient
from azure.ai.agentserver.invocations import InvocationAgentServerHost
from azure.identity import DefaultAzureCredential
from starlette.requests import Request
from starlette.responses import JSONResponse, Response, StreamingResponse

_sessions: dict[str, AgentSession] = {}

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=DefaultAzureCredential(),
)

agent = Agent(
    client=client,
    instructions="You are a friendly assistant. Keep your answers brief.",
    default_options={"store": False},
)

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    """Handle streaming multi-turn chat."""
    data = await request.json()
    session_id = request.state.session_id
    stream = data.get("stream", False)
    user_message = data.get("message", None)

    if user_message is None:
        return Response(content="Missing 'message' in request", status_code=400)

    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))

    if stream:

        async def stream_response() -> AsyncGenerator[str]:
            async for update in agent.run(user_message, session=session, stream=True):
                yield update.text

        return StreamingResponse(
            stream_response(),
            media_type="text/event-stream",
            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
        )

    response = await agent.run([user_message], session=session, stream=stream)
    return JSONResponse({"response": response.text})


if __name__ == "__main__":
    app.run()

경고

사용자 지정 처리기 예제의 메모리 내 세션 저장소는 다시 시작할 때 손실됩니다. 프로덕션 환경에서 지속성 스토리지(예: Cosmos DB)를 사용합니다.

Tip

호스트된 에이전트 프로젝트의 예제는 Python 샘플 또는 C# 샘플을 참조하세요. 또는 명령을 azd ai agent init 사용하여 호스트된 새 에이전트 프로젝트를 처음부터 스캐폴드합니다. 단계별 지침 은 이 빠른 시작 가이드 를 참조하세요.

로컬로 실행

Azure 개발자 CLI(azd)는 호스트된 에이전트를 로컬로 실행하고 테스트하는 가장 쉬운 방법을 제공합니다.

프로젝트를 초기화하기

새 폴더를 만들고 샘플 매니페스트에서 초기화합니다.

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -m <path-to-agent.manifest.yaml>

Tip

매니페스트는 로컬 YAML 파일의 경로이거나 원격 매니페스트의 URL일 수 있습니다.

환경 변수 설정

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="<your-model-deployment>"

에이전트 호스트 실행

azd ai agent run

에이전트 호스트가 http://localhost:8088에서 시작됩니다.

에이전트 호출

azd ai agent invoke --local "Hello!"

또는 다음을 사용합니다.curl

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello!"}'

또는 PowerShell에서 다음을 수행합니다.

(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Hello!"}').Content

Foundry에 배포하기

에이전트를 로컬로 확인했으면 Microsoft Foundry에 배포합니다.

1. 리소스 프로비전 (Foundry 프로젝트가 아직 없는 경우):

   azd provision
   

   Foundry 인스턴스, 프로젝트, 모델 배포, Application Insights 및 컨테이너 레지스트리를 사용하여 리소스 그룹을 만듭니다.

2. 에이전트를 배포합니다.

   azd deploy
   

   이렇게 하면 에이전트를 컨테이너 이미지로 패키지하고, Azure Container Registry 푸시하고, Foundry 에이전트 서비스에 배포합니다.

Foundry 호스팅 인프라는 런타임에 에이전트 컨테이너에 다음 환경 변수를 자동으로 삽입합니다.

변수	Description
FOUNDRY_PROJECT_ENDPOINT	Foundry 프로젝트의 엔드포인트 URL입니다.
AZURE_AI_MODEL_DEPLOYMENT_NAME	모델 배포 이름(azd ai agent init에서 구성됨)입니다.
APPLICATIONINSIGHTS_CONNECTION_STRING	Application Insights를 통한 원격 분석을 위한 연결 문자열.

배포되면 에이전트는 전용 Foundry 엔드포인트를 통해 액세스할 수 있으며 Foundry 포털에서 테스트할 수도 있습니다.

다음 단계

호스트된 에이전트 개념

• Foundry SDK를 사용하여 호스트된 에이전트 배포
• 호스트된 에이전트 관리
• Azure Functions(지속성) 호스팅
• A2A 호스팅
• Python 샘플
• C# 샘플