파운드리 호스팅 에이전트

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

에이전트 프레임워크 호스팅 통합을 사용하면 최소한의 코드로 AgentWorkflow.as_agent()로 래핑된 워크플로를 포함한 항목을 Foundry Responses 또는 Invocations 프로토콜을 통해 노출할 수 있습니다.

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

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

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

비고

Python agent-framework-foundry-hosting 통합은 사전 출시 상태입니다. 관리되는 호스팅 서비스인 Microsoft Foundry Hosted Agents를 일반적으로 사용할 수 있습니다.

필수 조건

• 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 이상

시험판 호스팅 패키지, Foundry 클라이언트 및 Azure 인증 패키지를 설치합니다.

pip install --pre agent-framework-foundry agent-framework-foundry-hosting azure-identity

Foundry에서 플랫폼은 호출자의 사용자 컨텍스트 및 호출 컨텍스트를 제공합니다. 호스팅 인프라는 이를 사용하여 사용자별 상태를 격리하고 요청 컨텍스트를 Foundry 서비스에 전달합니다. 로컬 실행은 해당 플랫폼 컨텍스트를 수신하지 않으므로 애플리케이션은 필요할 때 자체 ID 및 상태 제어를 제공해야 합니다.

응답 프로토콜

응답 프로토콜은 대부분의 에이전트에 권장되는 시작점입니다. 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.",
)

server = ResponsesHostServer(agent)
server.run()

ResponsesHostServer는 에이전트를 래핑하고 Foundry 응답 프로토콜을 통해 노출합니다. 비 워크플로 에이전트의 경우 기본값 history_source="agent_server" 은 구성된 에이전트 서버 응답 공급자를 모델의 기록 원본으로 사용합니다. 호스트는 클라이언트가 기본적으로 기록을 저장하는 경우 다운스트림 모델 서비스가 두 번째 복사본을 유지하지 못하도록 합니다.

load_messages=True가 있는 HistoryProvider와 기본 기록 소스를 결합하지 마세요. 또는 다운스트림 서비스 연속 옵션을 설정 conversation_idprevious_response_idconversation 하지 마세요. 호스트는 중복 기록을 방지하기 위해 이러한 구성을 거부합니다.

에이전트의 기록 공급자 또는 다운스트림 모델 서비스가 대화 기록을 관리해야 하는 경우에 사용합니다 ResponsesHostServer(agent, history_source="agent") . 이 모드는 에이전트 서버의 현재 요청 입력만 전달하고 에이전트의 기록 및 서비스 스토리지 동작을 유지합니다. 사용자 지정 SupportsAgentRun 구현은 이 모드를 사용해야 합니다. 매개 변수는 store 별도의 상태로 유지됩니다. 두 모드에서 응답 API 입력 및 출력을 유지하는 응답 공급자를 선택합니다.

호스트는 제공된 에이전트를 소유하며 호스팅 관련 컨텍스트 공급자를 추가할 수 있습니다. 에이전트를 다른 호스트와 함께 다시 사용하거나 호스트 생성 후 직접 호출하지 마세요.

상태 저장 및 장시간 실행되는 대화 처리

ResponsesHostServer 는 기본적으로 Foundry 지원 저장소를 구성합니다. 워크플로가 아닌 에이전트의 경우, AgentSessionStoreProvider는 FoundryAgentSessionStore를 제공합니다. 워크플로 에이전트의 경우, CheckpointStoreProvider는 FoundryCheckpointStore를 제공합니다. FunctionApprovalStoreProvider는 보류 중인 승인에 대한 FoundryFunctionApprovalStore를 제공합니다. 이러한 저장소는 호스트되는 경우 Foundry 상태 저장소를 사용하고 로컬로 실행할 때 로컬 에이전트 서버 상태를 사용합니다.

history_source="agent"를 사용하면 구성된 세션 저장소는 InMemoryHistoryProvider에서 전달되는 공급자 상태(여기에는 AgentSession의 메시지도 포함됨)를 유지합니다.

스토리지를 사용자 지정하려면 StoreProvider를 agent_session_store_provider 또는 function_approval_store_provider에 전달하세요. ContextScopedStoreProvider를 checkpoint_store_provider에 전달합니다. 예를 들어, 자체 비워크플로 에이전트 세션 저장소를 사용하려면 SessionStore 및 StoreProvider[SessionStore]를 구현합니다.

ResponsesHostServer에서 ResponsesServerOptions를 가져와 azure.ai.agentserver.responses 매개변수를 통해 options에 전달합니다. 사용 가능한 장기 실행 대화 옵션은 에이전트 유형에 따라 달라집니다.

Capability	에이전트 유형	요구 사항 및 동작
복원력 있는 배경 응답	워크플로만	ResponsesServerOptions(resilient_background=True)을 설정합니다. 및 와 함께 Responses 요청을 보냅니다. 다시 시작한 후 호스트는 최신 지속성 워크플로 검사점을 다시 시작하거나 검사점이 없는 경우 원래 입력을 재생합니다. 호스트가 관리하므로 워크플로에서 검사점 스토리지를 구성하지 마세요. 마지막 영구 체크포인트 이후의 작업이 반복될 수 있으므로 외부 부작용이 멱등성을 갖도록 하세요.
조종 가능한 대화	비 워크플로 전용	ResponsesServerOptions(steerable_conversations=True)을 설정하고 store=true을 사용하여 Responses 요청을 보냅니다. 동일한 conversation 값을 재사용하여 턴을 단일 선형 체인에 유지합니다. 또는 바로 앞에 previous_response_id 보내고 해결된 agent_session_id항목을 유지합니다. 호스트는 포크를 발생시킬 수 있는 오래된 이전 블록을 거부합니다.

ResponsesHostServer는 비워크플로 에이전트에 대해 복원력 있는 백그라운드 응답을 사용하도록 설정하거나 워크플로 에이전트에 대해 조정 가능한 대화를 사용하도록 설정하면 RuntimeError를 발생시킵니다. 전체 구현은 사용자 지정 스토리지, 복원력 있는 장기 실행 워크플로 및 조종 가능한 장기 실행 에이전트 샘플을 참조하세요.

OAuth 동의 요청 처리

Foundry에서 호스팅되는 MCP 도구에 사용자 동의가 필요한 경우, ResponsesHostServer는 oauth_consent_request 출력 항목이 포함된 불완전한 응답을 반환합니다. consent_link 사용자에게 표시한 다음, 사용자가 동의를 완료한 후처럼 previous_response_id 불완전한 응답의 ID를 계속 사용합니다. 호스트는 이 재시도에 대한 에이전트 세션을 유지하고 절대 HTTPS 동의 링크만 노출합니다.

호출 프로토콜

호출 프로토콜을 사용하면 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()

Warning

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

전체 Invocations 배포에 대해서는 Foundry에서 호스팅되는 Telegram 샘플을 참조하세요. 호스트된 에이전트 웹후크 앞에 API Management를 배치하고 지속적인 대화 기록에 관리 ID, Key Vault 및 Cosmos DB를 사용합니다.

비고

Foundry 호스팅 에이전트에 대한 Go 지원이 곧 제공될 예정입니다. 최신 상태는 에이전트 프레임워크 Go 리포지토리 를 참조하세요.

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 호스팅 인프라는 런타임에 에이전트 컨테이너에 다음 환경 변수를 자동으로 삽입합니다.

Variable	설명
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# 샘플