Microsoft 에이전트 프레임워크 에이전트를 Foundry 호스팅 에이전트로 호스트

Microsoft Agent Framework 호스팅 패키지를 사용하여 Foundry 호스팅 에이전트에 대한 프로토콜을 통해 에이전트 프레임워크 에이전트를 노출합니다. 호스팅 패키지를 사용하면 Foundry가 호스트된 런타임, 세션, 크기 조정, ID 및 프로토콜 엔드포인트를 관리하는 동안 에이전트 논리를 코드에 유지할 수 있습니다.

이 문서에서는 최소 에이전트 프레임워크 에이전트를 만들고, 응답 또는 호출 프로토콜을 통해 노출하고, HTTP를 통해 테스트하고, Azure Developer CLI를 사용하여 Foundry에 배포합니다.

Microsoft Foundry Skill은 어댑터를 구현하고, 프로토콜을 테스트하고, 배포azd하는 데 도움이 될 수 있습니다.

사전 요구 사항

Azure 구독입니다. 체험 계정 만들기
파운드리 프로젝트.
배포된 채팅 모델(예: gpt-4.1 또는 gpt-4o.
호스팅된 에이전트를 배포하는 프로젝트의 Foundry Project Manager 역할 자세한 내용은 호스트된 에이전트 배포를 참조하세요.
Azure CLI 로그인(az login)하므로 DefaultAzureCredential 인증할 수 있습니다.

Python 3.10 이상.

.NET 10 SDK 이상.

패키지 설치

에이전트 프레임워크 및 Foundry 호스팅 패키지를 설치합니다.

pip install -U agent-framework agent-framework-foundry-hosting azure-identity python-dotenv

패키지는 agent_framework_foundry_hosting Foundry 프로토콜에 대한 호스트 서버를 제공합니다.

OpenAI 호환 ResponsesHostServer 엔드포인트의 경우 /responses입니다.
InvocationsHostServer 제네릭 /invocations 엔드포인트의 경우

에이전트 프레임워크 및 Foundry 호스팅 패키지를 프로젝트에 추가합니다.

dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Foundry.Hosting
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

호출 프로토콜의 경우 호출 서버 패키지도 추가합니다.

dotnet add package Azure.AI.AgentServer.Invocations

이러한 패키지는 Foundry 프로토콜에 대한 호스트 확장을 제공합니다.

OpenAI 호환 AddFoundryResponses 엔드포인트의 경우 MapFoundryResponses 및 /responses입니다.
제네릭 AddInvocationsServer 엔드포인트의 경우 MapInvocationsServer 및 /invocations입니다.

호스팅 프로토콜 선택

호스트된 에이전트는 하나 이상의 프로토콜을 노출할 수 있습니다. 대부분의 대화형 에이전트에 대한 응답으로 시작합니다.

Protocol	Endpoint	사용 시기
응답	`/responses`	OpenAI 호환 채팅, 스트리밍, 응답 기록 및 대화 스레딩을 원합니다.
호출	`/invocations`	사용자 지정 JSON 셰이프, 웹후크 스타일 엔드포인트 또는 비대화형 처리를 원합니다.

프로토콜 동작 및 세션에 대한 배경 정보는 호스트된 에이전트 및 호스트된 에이전트 세션 관리를 참조하세요.

환경 변수 구성

로컬 개발에 대한 프로젝트 엔드포인트 및 모델 배포 이름을 설정합니다.

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

PowerShell에서:

$env:FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

동일한 코드가 Foundry에서 호스팅된 에이전트로 실행되면 플랫폼이 런타임에 FOUNDRY_PROJECT_ENDPOINT 및 AZURE_AI_MODEL_DEPLOYMENT_NAME을 주입합니다.

응답 프로토콜

스트리밍, 응답 기록 및 대화 스레딩을 사용하여 OpenAI 호환 채팅 엔드포인트를 원하는 경우 응답 프로토콜을 사용합니다.

응답 호스트 만들기

Foundry 모델을 사용하는 최소한의 Agent Framework 에이전트가 포함된 main.py라는 이름의 파일을 만드세요.

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
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    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.",
        # The hosting infrastructure manages conversation history, so the
        # service doesn't need to store it.
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

이 코드 조각이 수행하는 작업: Foundry 모델 FoundryChatClient에서 지원되는 에이전트 프레임워크 에이전트를 만든 다음 에이전트를 ResponsesHostServer전달합니다. 호스트는 HTTP 서버를 시작하고 POST /responses를 통해 에이전트를 노출합니다. 기본적으로 서버는 포트 8088에 바인딩됩니다.

참조: Microsoft Agent Framework 설명서

로컬에서 앱을 실행합니다.

python main.py

Responses 프로토콜을 통해 Foundry 모델을 사용하는 최소 Agent Framework 에이전트가 포함된 Program.cs 파일을 만드세요.

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";

// Create the agent via the AI project client using the Responses API.
AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a friendly assistant. Keep your answers brief.",
        name: "assistant",
        description: "A simple general-purpose AI assistant");

// Host the agent as a Foundry hosted agent using the Responses API.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);

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

이 코드 조각이 수행하는 작업: Foundry 프로젝트 클라이언트에서 AIAgent를 생성하고, AddFoundryResponses로 Foundry Responses 호스트로 등록한 다음, POST /responses 엔드포인트를 MapFoundryResponses로 매핑합니다. 기본적으로 호스트는 포트 8088에서 사용됩니다.

참조: AIProjectClient | DefaultAzureCredential

로컬에서 앱을 실행합니다.

dotnet run

응답 엔드포인트 테스트

스트리밍이 아닌 응답 요청을 로컬 서버에 보냅니다.

Bash:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Give me one practical tip for testing hosted agents.","stream":false}'

PowerShell:

$body = @{
  input  = "Give me one practical tip for testing hosted agents."
  stream = $false
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri http://localhost:8088/responses `
    -Method Post `
    -Body $body `
    -ContentType "application/json"

서버는 응답 텍스트와 응답 ID를 포함하는 JSON 개체로 응답합니다. 스트리밍 응답의 경우 stream를 true(으)로 설정합니다. 호스트는 응답 API 서버에서 보낸 이벤트(예: response.created, response.output_text.delta및 response.completed)를 내보냅니다.

멀티 턴 대화

대화를 계속하려면 다음 요청의 필드에 이전 응답 ID previous_response_id 를 전달합니다.

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Can you make that more concise?","previous_response_id":"<previous-response-id>","stream":false}'

에이전트가 Foundry에서 실행되면 호스트된 에이전트 응답 엔드포인트를 통해 동일한 패턴이 작동합니다. 이후 턴에서도 동일한 호스팅된 샌드박스 파일 시스템이 필요한 경우 agent_session_id를 포함하거나 conversation ID를 사용하세요. 자세한 내용은 호스트된 에이전트 세션 관리를 참조하세요.

호출 프로토콜

호출자가 응답 API 요청 셰이프를 사용할 수 없거나 시나리오가 채팅 대화가 아닌 경우 호출 프로토콜을 사용합니다. 호출 호스트는 쿼리 매개 변수 및 응답 헤더를 agent_session_id 통해 세션 상태를 관리합니다.

호출 호스트 만들기

Responses 예제와 동일한 에이전트 설정을 사용하되, InvocationsHostServer 대신 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
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    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()


if __name__ == "__main__":
    main()

이 코드 조각이 수행하는 작업: 를 통해 에이전트 프레임워크 에이전트를 POST /invocations호스트합니다. 호스트는 쿼리 매개 변수 및 응답 헤더를 agent_session_id 통해 세션별 상태를 관리합니다.

참조: Microsoft Agent Framework 설명서

호출 프로토콜은 각 요청을 처리하기 위해 사용자가 구현하는 InvocationHandler를 사용합니다. 호출 서버 및 처리기를 등록한 다음, 엔드포인트를 매핑합니다.

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

var builder = WebApplication.CreateBuilder(args);

// Register your agent and the Invocations server services.
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

var app = builder.Build();

// Map the Invocations protocol endpoints:
//   POST /invocations              - invoke the agent
//   GET  /invocations/{id}         - get result
//   POST /invocations/{id}/cancel  - cancel
app.MapInvocationsServer();
app.Run();

이 코드 조각이 수행하는 작업: 호출 서버 서비스 및 InvocationHandler 구현을 등록한 다음, 엔드포인트를 /invocations 매핑합니다. 각 요청을 처리하는 방법을 정의하기 위해 구현 MyInvocationHandler 합니다. 전체 처리기 예제는 .NET 호출 샘플을 참조하세요.

참조: AddInvocationsServer

호출 엔드포인트 테스트

로컬 서버에 요청을 보냅니다.

curl -sS -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"My name is Alice.","stream":false}'

다중 턴 대화의 경우 응답 헤더의 agent_session_id 값을 다음 요청의 agent_session_id 쿼리 매개 변수로 다시 사용합니다.

curl -sS -X POST "http://localhost:8088/invocations?agent_session_id=<session-id>" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is my name?"}'

플랫폼은 호출 프로토콜에 대한 대화 기록을 저장하지 않습니다. 쿼리 매개 변수를 agent_session_id 사용하여 나중에 호출을 동일한 호스트된 샌드박스로 라우팅합니다.

Deploy

Azure 개발자 CLI(azd)를 사용하여 배포합니다. 흐름은 샘플 azure.yaml 파일 및 Docker를 사용하여 에이전트 컨테이너 이미지를 빌드하고 Foundry 호스팅 에이전트 런타임에 롤아웃합니다.

호스트된 에이전트 배포를 위해서는 프로젝트에서 Foundry Project Manager 역할이 필요합니다. 자세한 내용은 호스트된 에이전트 배포를 참조하세요.

Azure 개발자 CLI 확장 설치

샘플을 초기화하기 전에 AI 에이전트 확장을 설치하고 로그인합니다.

azd ext install azure.ai.agents
azd auth login

샘플의 Dockerfile에 선언된 컨테이너 이미지를 빌드하기 때문에 azd ai agent run Docker가 로컬로 실행되어야 합니다. 명령 세부 정보는 Azure 개발자 CLI 참조 참조하세요.

샘플 매니페스트에서 초기화

새 폴더를 만들고 샘플의 azure.yaml로 초기화합니다. 이러한 명령은 현재 디렉터리를 초기화하고 이 연습과 일치하도록 컨테이너 배포를 선택합니다.

mkdir my-agent-framework-agent
cd my-agent-framework-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 . --deploy-mode container

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -t https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/azure.yaml --src . --deploy-mode container

azd ai agent init의 안내를 따르세요. Python 샘플은 Foundry 프로젝트를 만들고 모델을 배포할 수 있습니다. C# 샘플에는 기존 Foundry 프로젝트 및 모델 배포가 필요합니다.

Azure 리소스 프로비전

초기화된 프로젝트에서 새 Foundry 프로젝트 및 모델 배포를 사용하는 경우 먼저 Azure 리소스를 프로비전합니다.

azd provision

이 명령은 다른 리소스 중에서 Foundry 인스턴스, 모델 배포가 있는 Foundry 프로젝트, Application Insights 인스턴스 및 호스트된 에이전트 이미지에 대한 컨테이너 레지스트리를 포함하는 리소스 그룹을 만듭니다.

컨테이너를 로컬로 실행

다음을 통해 azd에이전트 호스트를 로컬로 실행합니다.

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!"}'

Foundry에 배포

에이전트를 배포합니다.

azd deploy

배포는 에이전트를 컨테이너 이미지로 패키지하고, 프로비전된 컨테이너 레지스트리로 푸시하고, Foundry 호스팅 에이전트 런타임에 롤아웃합니다.

Foundry 호스팅 인프라는 다음을 포함하여 런타임 환경 변수를 에이전트에 삽입합니다.

FOUNDRY_PROJECT_ENDPOINT: 에이전트가 배포된 Foundry 프로젝트의 엔드포인트 URL입니다.
AZURE_AI_MODEL_DEPLOYMENT_NAME: azd ai agent init 중 선택한 모델 배포 이름입니다.
APPLICATIONINSIGHTS_CONNECTION_STRING: 프로젝트의 Application Insights 인스턴스에 대한 연결 문자열.

전체 배포 개념, 권한 및 관리 세부 정보는 호스트된 에이전트 배포 및 호스트된 에이전트 수명 주기 관리를 참조하세요.

Troubleshooting

에이전트 프레임워크를 사용하여 호스트된 에이전트를 개발하는 동안 일반적인 문제를 진단하려면 이 검사 목록을 사용합니다.

호스트된 컨테이너에서 모델에 연결할 수 없습니다.

호스트된 에이전트 버전이 포함되어 AZURE_AI_MODEL_DEPLOYMENT_NAME있고 에이전트 ID에 Foundry 프로젝트를 호출할 수 있는 권한이 있음을 확인합니다. 플랫폼 집합 FOUNDRY_PROJECT_ENDPOINT입니다. Foundry에서 실행할 때 코드에서 해당 변수를 읽어야 합니다.

대화 상태가 계속되지 않음

Responses 프로토콜의 경우, 후속 턴에서 previous_response_id 또는 conversation ID를 전달하세요.

호출 프로토콜의 경우 플랫폼은 대화 기록을 저장하지 않습니다. 쿼리 매개 변수를 agent_session_id 사용하여 나중에 호출을 동일한 호스트된 샌드박스로 라우팅합니다.

프로토콜 버전 불일치

업그레이드 후 요청이 실패하는 경우 매니페스트와 호스팅 패키지가 모두 프로토콜 버전 2.0.0을 사용하는지 확인합니다. 프로토콜 버전 1.0.0은 더 이상 지원되지 않습니다.

다음 단계

호스트된 에이전트 배포

피드백

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

2026-07-03 에 마지막으로 업데이트됨