호스트된 에이전트 배포

이 문서에서는 Python SDK 또는 REST API를 사용하여 컨테이너화된 에이전트를 Foundry 에이전트 서비스에 배포하는 방법을 보여 줍니다. 사용자 고유의 애플리케이션 또는 서비스에서 직접 에이전트 배포를 관리하려는 경우 이러한 방법을 사용합니다.

처음으로 배포하거나 가장 빠른 경로를 원하는 경우 빠른 시작: 호스트된 에이전트를 만들고 배포 합니다. 빠른 시작에서는 빌드, 푸시, 버전 관리 및 RBAC 구성을 자동으로 처리하는 Azure 개발자 CLI(azd) 또는 VS 코드 확장 사용합니다.

배포 수명 주기

호스트된 모든 에이전트 배포는 다음 시퀀스를 따릅니다.

1. 빌드 및 푸시 - 에이전트 코드를 컨테이너 이미지에 패키지하고 Azure Container Registry 푸시합니다.
2. 에이전트 버전 만들기 - Foundry 에이전트 서비스에 이미지를 등록합니다. 플랫폼은 인프라를 프로비전하고 전용 Entra 에이전트 ID를 만듭니다.
3. 상태 폴링 - 버전 상태가 도달할 active때까지 기다립니다.
4. 호출 - 에이전트의 전용 엔드포인트에 요청을 보냅니다.

필수 구성 요소

• Microsoft Foundry 프로젝트.
• 지원되는 프레임워크를 사용하는 에이전트 코드입니다.
• 로컬 컨테이너 개발을 위해 설치된 Docker Desktop입니다.
• Azure CLI 버전 2.80 이상

필요한 권한

호스트된 에이전트를 만들고 배포하려면 project 범위에서 Azure AI Project Manager 필요합니다. 이 역할에는 에이전트를 만들기 위한 데이터 평면 권한과 Azure AI 사용자 역할을 플랫폼에서 만든 에이전트 ID에 할당하는 기능이 모두 포함됩니다. 에이전트 ID는 런타임에 모델 및 아티팩트 액세스하려면 프로젝트에서 Azure AI 사용자가 필요합니다.

VS Code 확장을 사용하는 azd 경우 도구는 다음을 포함하여 대부분의 RBAC 할당을 자동으로 처리합니다.

• 프로젝트 관리 ID(이미지 끌어오기)를 위한 컨테이너 레지스트리 리포지토리 리더
• 플랫폼에서 만든 에이전트 ID(런타임 모델 및 도구 액세스)에 대한 Azure AI 사용자

자세한 내용은 인증 및 권한 부여를 참조하세요.

컨테이너 요구 사항

컨테이너 이미지는 호스트된 에이전트 플랫폼에서 실행하려면 다음 요구 사항을 충족해야 합니다.

프로토콜 라이브러리

호스트된 에이전트는 프로토콜 라이브러리를 통해 Foundry 게이트웨이와 통신합니다. 에이전트의 상호 작용 패턴과 일치하는 프로토콜을 선택합니다.

단일 컨테이너는 파일, SDK 호출 또는 REST API 요청에서 에이전트를 만들 때 둘 다 선언하고 두 라이브러리를 모두 가져와agent.yaml 노출할 수 있습니다. Microsoft 에이전트 프레임워크, LangChain, 또는 사용자 지정 코드를 포함하여 기존 프레임워크 내에서 프로토콜 라이브러리를 사용하세요.

응답 프로토콜 라이브러리

응답 프로토콜에 대한 Python 및 .NET 라이브러리는 Azure AI 응답 API를 구현합니다. 패키지를 가져오고 인터페이스를 구현합니다 IResponseHandler . 라이브러리는 라우팅, SSE(서버 전송 이벤트), 백그라운드 실행, 취소, 캐싱 및 응답 수명 주기 관리를 사용하여 스트리밍을 처리합니다.

IResponseHandler

IResponseHandler 는 구현하는 핵심 추상화입니다. 라이브러리는 들어오는 각 요청에 대해 CreateAsync를 호출하고, SSE를 통해 클라이언트에 IAsyncEnumerable<ResponseStreamEvent>를 반환하여 전송합니다.

public class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request,
            createText: async ct =>
            {
                var input = await context.GetInputTextAsync(cancellationToken: ct);
                return $"Echo: {input}";
            });
    }
}

ResponseEventStream

ResponseEventStream는 sequenceNumberoutputIndexcontentIndexitemId자동으로 전체 Response 수명 주기를 관리합니다. 각 yield return 이벤트는 SSE 이벤트에 일대일로 매핑되므로 이 상태를 직접 추적할 필요가 없습니다.

스트리밍 및 백그라운드 모드

• 스트리밍 모드 (기본값): SSE 이벤트는 연결된 클라이언트에 실시간으로 전달됩니다.
• 백그라운드 모드: 처리기는 연결된 SSE 클라이언트 없이 완료될 때 실행됩니다. 이벤트는 버퍼링되어 GET /responses/{id}를 통해 재생할 수 있도록 제공됩니다.

응답 수명 주기

라이브러리는 전체 응답 수명 주기를 단계별로 조정합니다: created → in_progress → completed (또는 failed 또는 cancelled). 또한 라이브러리는 취소, 오류 처리 및 터미널 이벤트 보장을 자동으로 관리합니다.

스레드 안전성

통해 AddResponsesServer() 등록된 모든 서비스 인스턴스는 스레드로부터 안전합니다. 처리기 인스턴스는 요청별로 범위가 지정됩니다.

자세한 처리기 구현 지침은 핸들러 구현 가이드 참조하세요. 실행 가능한 예제는 사용 프로토콜 샘플 참조하세요.

헬스 엔드포인트

프로토콜 라이브러리는 플랫폼 상태 검사를 위한 엔드포인트를 /readiness 자동으로 노출합니다. 직접 구현할 필요가 없습니다.

포트

컨테이너는 포트 8088 에서 로컬로 트래픽을 제공합니다. 프로덕션 환경에서 Foundry 게이트웨이는 라우팅을 처리합니다. 컨테이너는 공용 포트를 노출할 필요가 없습니다.

플랫폼 삽입 환경 변수

호스트된 에이전트 플랫폼은 런타임에 컨테이너에 환경 변수를 자동으로 삽입합니다. 코드는 agent.yaml 또는 environment_variables에 이를 선언하지 않고 읽을 수 있습니다. FOUNDRY_* 접두사는 플랫폼용으로 예약되어 있습니다.

플랫폼이 삽입한 변수를 agent.yaml 에서 재선언하지 마십시오 — 이들은 자동으로 설정됩니다.

자신이 선언한 변수(예: MODEL_DEPLOYMENT_NAME, MCP 엔드포인트 또는 도구 상자)는 agent.yaml 섹션이나 SDK environment_variables 호출의 create_version 섹션에 포함됩니다.

에이전트를 로컬 환경에서 패키징하고 테스트하세요.

Foundry에 배포하기 전에 프로토콜 라이브러리를 사용하여 에이전트가 로컬로 작동하는지 확인합니다. 컨테이너는 프로덕션에서와 동일한 엔드포인트를 로컬로 제공합니다.

응답 프로토콜 테스트

POST http://localhost:8088/responses
Content-Type: application/json

{
    "input": "Where is Seattle?",
    "stream": false
}

호출 프로토콜 테스트

POST http://localhost:8088/invocations
Content-Type: application/json

{
    "message": "Hello!"
}

Azure 개발자 CLI 또는 VS Code를 사용하여 배포

Azure 개발자 CLI(azd) 및 VS Code 확장은 전체 배포 수명 주기를 자동화합니다. 단계별 연습은 빠른 시작: 호스트된 에이전트 만들기 및 배포를 참조하세요.

Python SDK를 사용하여 배포

Python 코드에서 직접 에이전트 배포를 관리하려는 경우 SDK를 사용합니다.

추가 필수 구성 요소

• Python 3.10 이상

• Azure Container Registry

• 컨테이너 레지스트리 리포지토리 작성자 또는 AcrPush 역할(이미지를 푸시하기 위해)

• AZURE AI Projects SDK 버전 2.1.0 이상

  pip install "azure-ai-projects>=2.1.0"
  

컨테이너 이미지 빌드 및 푸시

1. Docker 이미지를 빌드합니다.

   docker build --platform linux/amd64 -t myagent:v1 .
   

   Python 및 C# 샘플 Dockerfiles를 참조하세요.

2. Azure Container Registry에 푸시하기:

   az acr login --name myregistry
   docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
   docker push myregistry.azurecr.io/myagent:v1
   

컨테이너 레지스트리 권한 구성

프로젝트의 관리 ID 액세스 권한을 부여하여 이미지를 끌어오세요.

1. Azure 포털 Foundry 프로젝트 리소스로 이동합니다.

2. ID를 선택하고 시스템 할당에서 개체(보안 주체) ID를 복사합니다.

3. 컨테이너 레지스트리의 이 ID에 Container Registry 리포지토리 읽기 권한자 역할을 할당합니다. Azure Container Registry 역할 및 권한 참조하세요.

호스트된 에이전트 버전 만들기

버전을 만들면 플랫폼이 트리거하여 에이전트를 자동으로 프로비전합니다. 별도의 시작 단계는 없습니다. 플랫폼은 컨테이너 스냅샷을 빌드하고 에이전트가 요청을 처리할 준비가 되도록 합니다.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentProtocol
from azure.identity import DefaultAzureCredential

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client
credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
    allow_preview=True,
)

# Create a hosted agent version
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        image="your-registry.azurecr.io/your-image:tag",
        environment_variables={
            "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
        }
    )
)

print(f"Agent created: {agent.name}, version: {agent.version}")

두 프로토콜을 모두 노출하려면 다음을 모두 전달합니다.container_protocol_versions

container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentProtocol.INVOCATIONS, version="1.0.0")
],

키 매개 변수:

버전 상태에 대한 폴링

버전을 만든 후 에이전트를 호출하기 전에 상태가 active 될 때까지 폴링합니다. 프로비저닝은 일반적으로 이미지 크기에 따라 1분 미만이 소요됩니다.

import time

# Poll until the agent version is active
while True:
    version_info = project.agents.get_version(
        agent_name="my-agent",
        agent_version=agent.version
    )
    status = version_info["status"]
    print(f"Status: {status}")

    if status == "active":
        print("Agent is ready!")
        break
    elif status == "failed":
        print(f"Provisioning failed: {version_info['error']}")
        break

    time.sleep(5)

버전 상태 값:

에이전트 호출

버전이 일정한 상태에 도달하면, get_openai_client을 사용하여 에이전트의 엔드포인트에 바인딩된 OpenAI 클라이언트를 만듭니다 active.

응답 프로토콜의 경우:

# Create an OpenAI client bound to the agent endpoint
openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Hello! What can you do?",
)

print(response.output_text)

호출 프로토콜의 경우 호출 엔드포인트를 직접 호출합니다.

import requests

token = credential.get_token("https://ai.azure.com/.default").token
url = f"{PROJECT_ENDPOINT}/agents/my-agent/endpoint/protocols/invocations"

response = requests.post(url, headers={
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Foundry-Features": "HostedAgents=V1Preview"
}, params={"api-version": "v1"}, json={
    "message": "Process this task"
})

print(response.json())

자세한 예제는 호스트된 에이전트 샘플을 참조하세요.

REST API를 사용하여 배포

직접 HTTP 기반 배포 또는 사용자 지정 도구와 통합할 때 REST API를 사용합니다.

시작하기 전에 컨테이너 이미지를 빌드 및 푸시하고 컨테이너레지스트리 권한을 구성합니다.

변수 설정

BASE_URL="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="v1"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

에이전트 만들기

curl -X POST "$BASE_URL/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v1",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

또한 에이전트를 만들면 버전 1 이 만들어지고 프로비저닝이 트리거됩니다.

버전 상태에 대한 폴링

status가 active이 될 때까지 버전 엔드포인트를 폴링합니다.

while true; do
  STATUS=$(curl -s -X GET "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "active" ] && echo "Ready!" && break
  [ "$STATUS" = "failed" ] && echo "Provisioning failed." && exit 1
  sleep 5
done

에이전트 호출

에이전트의 전용 엔드포인트를 사용하여 요청을 보냅니다. 서버에서 보낸 이벤트를 수신하도록 설정합니다 "stream": true .

응답 프로토콜:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello! What can you do?",
    "store": true
  }'

호출 프로토콜:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/invocations?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: HostedAgents=V1Preview" \
  -d '{
    "message": "Process this task"
  }'

새 버전 만들기

새 버전을 만들어 업데이트된 코드 또는 구성을 배포합니다.

curl -X POST "$BASE_URL/agents/my-agent/versions?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v2",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

리소스 정리

요금을 방지하려면 완료되면 리소스를 정리합니다. 에이전트 컴퓨팅은 비활성 15분 후에 프로비전 해제되므로 에이전트가 요청을 처리하지 않을 때 비용이 발생하지 않습니다.

Azure 개발자 CLI 정리

azd down

SDK 정리

단일 버전을 삭제합니다.

project.agents.delete_version(agent_name="my-agent", agent_version=agent.version)

또는 전체 에이전트 및 모든 해당 버전을 삭제합니다.

project.agents.delete(agent_name="my-agent")

REST API 정리

단일 버전을 삭제합니다.

curl -X DELETE "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

또는 전체 에이전트를 삭제합니다.

curl -X DELETE "$BASE_URL/agents/my-agent?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

문제 해결

프로비전 오류는 버전 개체 error.code 및 error.message 필드에 표시됩니다. 만든 후 버전 상태를 확인하여 문제를 식별합니다.

5xx 오류는 Microsoft 지원에 문의하세요.

자세한 RBAC 요구 사항 및 권한 문제 해결은 호스트된 에이전트 권한 참조를 참조하세요.

다음 단계

관련 콘텐츠

• 호스트된 에이전트는 무엇인가요?
• 에이전트 ID 개념
• 에이전트 애플리케이션
• Azure Container Registry 설명서