소스 코드에서 호스트된 에이전트 배포

이 문서에서는 컨테이너 이미지를 빌드하거나 푸시하지 않고 Python 또는 .NET 소스 코드에서 Foundry 에이전트 서비스에서 Hosted agent 배포하는 방법을 보여줍니다. 코드(및 필요에 따라 종속성)를 업로드 .zip 하면 에이전트 서비스가 as-is 실행하거나 클라우드에서 종속성을 빌드합니다.

팁

대부분의 시나리오에서는 Azure 개발자 CLI(azd) 또는 VS Code용 Foundry Toolkit 배포합니다. 이러한 도구는 대부분의 복잡한 작업을 대신 처리합니다. 즉, 소스를 패키징하고 업로드하며 active 상태를 주기적으로 확인하고 역할 기반 액세스 제어를 자동으로 구성합니다. 시작하려면 빠른 시작: 첫 번째 호스팅 에이전트를 배포하고 배포 방법을 묻는 메시지가 표시되면 코드 (또는 소스 코드(ZIP 업로드)를 선택합니다.

사용자 고유의 애플리케이션에서 Python SDK 또는 .NET SDK에서 프로그래밍 방식으로 소스 코드 에이전트를 배포하거나, 사용자 지정 도구, 언어 중립적 자동화 또는 기존 지속적인 업데이트 시스템과의 통합을 위해 REST API를 통해 직접 배포해야 하는 경우 이 문서의 SDK 및 REST 절차를 사용합니다. 이 문서에서는 다음 작업을 완료합니다.

  • 종속성 확인 모드를 선택하고 원본을 패키지합니다.
  • 에이전트를 만들고, 에이전트가 도달할 active때까지 기다렸다가 호출합니다.
  • 배포된 에이전트에 대한 로그를 업데이트, 버전, 다운로드 및 스트리밍합니다.

런타임 이미지를 완전히 제어해야 하거나 이미 작업 중인 Dockerfile이 있는 경우 컨테이너 기반 경로인 호스트된 에이전트 배포를 사용합니다.

GitHub Copilot 같은 코딩 에이전트를 사용하여 소스 코드를 패키지하고 배포하는 경우 Microsoft Foundry Skill은 프로젝트를 준비하고 필요한azd, SDK 또는 REST 단계를 수행하는 데 도움이 될 수 있습니다.

사전 요구 사항

  • pip Python 3.13 이상에서는 소스 코드를 로컬에서 패키징할 수 있습니다.

  • azure-ai-projects 버전 2.2.0 이상 및 azure-identity 패키지입니다.

    pip install "azure-ai-projects>=2.2.0" azure-identity

지원되는 런타임

code_configuration.runtime 에이전트 정의의 필드는 다음 값을 허용합니다. zip 파일의 바이너리와 일치하는 런타임을 선택하세요. Python의 경우 Linux x86_64 wheel을, .NET의 경우 TargetFramework 출력의 dotnet publish을 선택하세요.

언어 런타임 값
Python python_3_13, python_3_14
.NET dotnet_10

언어 버전 지원 정책

에이전트 서비스 런타임에는 각 값 code_configuration.runtime에 대한 플랫폼 빌드 컨테이너 이미지가 포함됩니다. 배포된 에이전트를 완전히 지원하도록 Foundry는 호스트된 에이전트 언어 지원을 각 언어에 대한 수명 종료 지원에 맞춥니다. 지원은 언어 버전의 커뮤니티 지원 종료 날짜에 종료됩니다. Microsoft 플랫폼 제약 조건(예: 기본 기본 이미지)에 필요한 경우 이전에 code_configuration.runtime 값을 사용 중지할 수 있습니다.

업스트림 지원 종료 일정은 다음을 참조하세요.

사용 중지 단계

언어 수명 종료 날짜 후에도 사용 중지된 런타임 값을 사용하는 호스트된 에이전트를 만들고 업데이트하고 실행할 수 있습니다. 그러나 이러한 에이전트는 현재 code_configuration.runtime 값을 설정하고 다시 배포하여 지원되는 런타임으로 업그레이드할 때까지 지원, 새 기능 또는 보안 패치를 받을 수 없습니다.

필요한 권한

호스트된 에이전트를 배포하려면 project 범위에서 Foundry Project Manager 역할이 필요합니다. 이 역할은 에이전트를 만들고 업데이트할 수 있는 데이터 평면 권한과 필요한 경우 플랫폼에서 만든 에이전트 ID에 대한 역할 할당을 만드는 기능을 부여합니다. 관련된 권한에 대한 자세한 내용은 호스트 에이전트 권한 참조를 참조하세요.

Important

Foundry RBAC 역할의 이름이 최근에 바뀌었습니다. Foundry User, Foundry OwnerFoundry 계정 소유자 및 Foundry Project Manager는 이전에 Azure AI 사용자, Azure AI 소유자, Azure AI 계정 소유자 및 Azure AI Project Manager로 이름이 지정되었습니다. 이름 바꾸기가 롤아웃되는 동안 일부 위치에서는 이전 이름이 계속 표시될 수 있습니다. 역할 ID 및 핵심 권한은 이름 바꾸기에 의해 변경되지 않습니다.

에이전트는 사용자 ID와 별개의 플랫폼 할당 관리 ID로 실행됩니다. 이 ID는 기본적으로 프로젝트 엔드포인트 및 세션 스토리지를 통해 모델 추론에 액세스할 수 있습니다. 외부 리소스(예: 고유한 Azure Storage)의 경우 에이전트의 Microsoft Entra ID RBAC 역할을 수동으로 할당합니다. 자세한 내용은 기본값 이외의 에이전트 액세스를 참조하세요.

배포 수명 주기

모든 소스 코드 배포는 동일한 시퀀스를 따릅니다. 패키지 -> 만들기 또는 업데이트 -> 폴링까지 active -> 호출. 소스 코드 경로는 에이전트 정의에서 사용합니다 code_configuration . 대신 이미지 기반 경로가 사용됩니다 container_configuration . 이 두 옵션은 단일 버전에서 함께 사용할 수 없습니다.

워크플로에 맞는 경로를 선택합니다. 확실하지 않은 경우 Azure 개발자 CLI 또는 VS Code로 시작합니다. 이는 대부분의 고객에게 권장되는 경로입니다.

경로 적합한 대상 패키징
Azure 개발자 CLI 또는 VS Code 초기 배포와 가장 빠른 내부 반복 주기를 포함한 대부분의 배포 도구가 대신 ZIP 파일을 만들어 업로드합니다.
Python SDK Python 앱 또는 자동화에서 프로그래밍 방식으로 배포합니다. zip을 빌드합니다. SDK가 업로드합니다.
.NET SDK .NET 앱 또는 자동화에서 프로그래밍 방식으로 배포합니다. SDK는 폴더를 압축합니다.
JavaScript/TypeScript SDK Node.js 앱 또는 자동화에서 프로그래밍 방식으로 배포합니다. Python 또는 .NET 원본을 배포합니다. 호스트된 런타임에는 Node.js 없습니다. zip을 빌드합니다. SDK가 업로드합니다.
REST API 사용자 지정 도구, 언어에 구애받지 않은 자동화 및 CD 시스템. zip을 빌드하고 다중 파트 요청을 보냅니다.

종속성을 해결하는 방법 선택

시작하기 전에 에 대한 code_configuration.dependency_resolution값을 선택합니다. 이 선택은 zip에 넣은 내용에 영향을 줍니다.

가치 동작 사용 시기
remote_build 에이전트 서비스는 requirements.txt(Python)의 종속성을 설치하거나 프로비전하는 동안 프로젝트 파일(.NET)을 복원합니다. 작은 업로드와 가장 간단한 내부 루프를 원합니다. 처음 사용자에게 권장합니다.
bundled ZIP 파일은 있는 그대로 실행됩니다. 미리 빌드된 Linux 종속성을 packages/(Python) 또는 dotnet publish 출력(.NET)으로 제공합니다. 재현 가능한 빌드가 필요하거나, 종속성이 비공개이거나 휠 전용이거나, 프로젝트가 서버 측에서 깔끔하게 복원되지 않는 경우입니다.

번들 모드의 경우 로컬 빌드 명령은 zip을 수동으로 패키징하기를 참조하세요.

프라이빗 가상 네트워크에 대한 방화벽 요구 사항

프라이빗 가상 네트워크를 사용하여 프로젝트를 보호하는 경우 배포하기 전에 다음 엔드포인트에 대한 아웃바운드 연결을 허용하도록 네트워크 정책을 업데이트합니다.

모든 소스 코드 배포에는 다음을 위한 아웃바운드 액세스가 필요합니다.

  • mcr.microsoft.com
  • *.login.microsoft.com

Foundry 호스팅 라이브러리(예: azure-ai-agentserver-core 또는 agent-framework-foundry-hosting)를 사용하는 에이전트 코드는 에이전트의 텔레메트리도 전송합니다. 추적이 삭제되지 않도록 다음 엔드포인트를 허용합니다.

  • agent365.svc.cloud.microsoft (TCP 443): Foundry 리소스에 대해 에이전트 365 데이터 수집을 사용하도록 설정한 경우 에이전트 365 관찰성 내보내기. 차단하면 에이전트가 계속 실행되지만 해당 추적은 에이전트 365로 내보내지지 않습니다. 이 트래픽을 중지하려면 에이전트 365 데이터 수집을 사용하지 않도록 설정합니다. 자세한 내용은 Microsoft Foundry에 대한 에이전트 365 데이터 수집 구성을 참조하세요.
  • 프로젝트에 Application Insights 연결이 있는 경우 방화벽 허용 목록에 나열된 Application Insights 엔드포인트입니다.

네트워크 구성은 가상 네트워크에 호스트된 에이전트 배포를 참조하세요.

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

Azure 개발자 CLI(azd) 및 VS Code용 Foundry 도구 키트는 전체 소스 코드 배포 수명 주기를 자동화합니다. 원본을 zip으로 패키지하고, SHA-256을 컴퓨팅하고, 업로드하고, active 폴링하고, 역할 기반 액세스 제어를 구성합니다. 이러한 도구는 대부분의 고객에게 권장되는 경로이며 가장 빠른 내부 루프입니다.

단계별 연습은 빠른 시작: 첫 번째 호스팅 에이전트 배포를 참조하세요. 빠른 시작에서 배포 방법을 묻는 경우 Code(또는 Source Code (ZIP upload))를 선택합니다.

소스 코드 배포 선택

대화형으로 실행 azd ai agent init 하면 도구에서 배포 모드를 선택하라는 메시지를 표시합니다. 컨테이너 이미지를 빌드하는 대신 원본에서 ZIP 업로드로 배포할 코드를 선택합니다. 코드 배포는 Python 및 .NET 호스팅된 에이전트의 기본 모드입니다. VS Code용 Foundry 도구 키트는 동일한 방식으로 배포 방법을 묻는 메시지를 표시합니다.

예를 들어 CI/CD 파이프라인에서 소스 코드 배포를 비대화형으로 선택하려면 --deploy-mode code를 전달합니다. 이 모드에는 --runtime 및 --entry-point이 필요하며, 선택적 --dep-resolution 값으로 remote_build(기본값) 또는 bundled를 허용합니다:

azd ai agent init --no-prompt --project-id "<project-resource-id>" \
  --deploy-mode code --runtime python_3_13 --entry-point main.py

초기화 후 azd는 codeConfiguration의 azure.ai.agent 서비스에 있는 azure.yaml 필드에 소스 코드 배포 설정을 기록합니다.

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    codeConfiguration:
      runtime: python_3_13
      entryPoint:
        - python
        - main.py
      dependencyResolution: remote_build

azd up을(를) 실행하여 프로비전 및 배포합니다. 대신 컨테이너 이미지를 빌드하거나 참조하려는 경우에만 사용합니다 --deploy-mode container .

사용자 고유의 애플리케이션에서 프로그래밍 방식으로 배포하거나 기존 도구와 통합해야 하는 경우 다음 섹션의 SDK 또는 REST 경로를 사용합니다.

소스 코드에서 배포

언어 또는 인터페이스를 선택합니다. 각 탭은 동일한 수명 주기를 거칩니다. 즉, 에이전트를 생성하고, active 상태에 도달할 때까지 폴링하고, 에이전트를 호출한 다음, 배포된 코드를 다운로드합니다.

Python SDK를 사용하여 사용자 고유의 애플리케이션 또는 자동화에서 소스 코드 에이전트를 배포합니다. zip을 직접 빌드하고 해당 바이트 및 SHA-256을 SDK에 전달하여 업로드하고 REST API와 동일한 만들기, 폴링, 호출 및 다운로드 작업을 노출합니다. 코드 배포에는 azure-ai-projects 버전 2.2.0 이상이 필요합니다.

ZIP 파일 생성

Python SDK는 빌드한 zip을 업로드합니다. zip 패키지에 설명된 것과 동일한 레이아웃 및 종속성 확인 규칙을 수동으로 사용합니다. 최소 remote_build 페이로드는 루트에 main.py 및 requirements.txt가 있는 플랫 ZIP입니다.

에이전트 만들기

import hashlib
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    CodeConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)
from azure.identity import DefaultAzureCredential

# Format: "https://<account>.services.ai.azure.com/api/projects/<project>"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "my-code-agent"
ZIP_PATH = Path("agent-code.zip")

code_zip_bytes = ZIP_PATH.read_bytes()
code_zip_sha256 = hashlib.sha256(code_zip_bytes).hexdigest()

credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
)

created = project.agents.create_version_from_code(
    agent_name=AGENT_NAME,
    definition=HostedAgentDefinition(
        cpu="1",
        memory="2Gi",
        code_configuration=CodeConfiguration(
            runtime="python_3_13",
            entry_point=["python", "main.py"],
            dependency_resolution="remote_build",
        ),
        protocol_versions=[
            ProtocolVersionRecord(protocol="responses", version="2.0.0")
        ],
        environment_variables={"AZURE_AI_MODEL_DEPLOYMENT_NAME": "gpt-5.4-mini"},
    ),
    code=(ZIP_PATH.name, code_zip_bytes, "application/zip"),
    code_zip_sha256=code_zip_sha256,
    description="Hello-world code agent",
)
print(f"Created version: {created.version}")

Invocations 프로토콜의 경우 protocol_versions 항목을 ProtocolVersionRecord(protocol="invocations", version="2.0.0")로 설정합니다. 호출(WebSocket) 프로토콜에는 ProtocolVersionRecord(protocol="invocations_ws", version="2.0.0")를 사용하세요. bundled 모드의 경우 dependency_resolution="bundled"을(를) 설정하고 zip에 미리 빌드된 종속성을 포함합니다. 자세한 내용은 로컬에서 Linux 종속성 빌드를 참조하세요.

활성에 대한 폴링

import time

while True:
    version = project.agents.get_version(
        agent_name=AGENT_NAME, agent_version=created.version
    )
    status = version["status"]
    print(f"Status: {status}")
    if status == "active":
        break
    if status == "failed":
        raise RuntimeError(f"Provisioning failed: {version.get('error')}")
    time.sleep(5)

전체 상태 값 목록과 오류 발생 시 객체를 읽는 방법은 error을 참조하십시오.

에이전트 호출

버전이 active에 도달한 후 OpenAI 클라이언트를 에이전트 엔드포인트에 바인딩하고 이를 호출하세요. 이 예제에서는 응답 프로토콜을 사용합니다.

openai_client = project.get_openai_client(agent_name=AGENT_NAME)

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

호출 프로토콜의 경우 에이전트 호출에 표시된 것처럼 전달자 토큰을 사용하여 직접 호출 엔드포인트 를 호출합니다.

배포된 zip 다운로드

zip을 다운로드하고 SHA-256을 업로드한 값과 비교하여 배포된 내용을 정확하게 확인합니다.

import hashlib
from pathlib import Path

out_path = Path(f"{AGENT_NAME}-{created.version}.zip")
sha = hashlib.sha256()
with open(out_path, "wb") as f:
    for chunk in project.agents.download_code(
        agent_name=AGENT_NAME, agent_version=created.version
    ):
        f.write(chunk)
        sha.update(chunk)

print(f"Downloaded {out_path} (matches upload: {sha.hexdigest() == code_zip_sha256})")

실행 가능한 전체 예제는 Python hosted-agent 샘플 참조하세요.

zip을 수동으로 패키지

azd를 사용하는 경우 이 섹션은 건너뛰세요. azd가 zip 파일을 대신 빌드해 줍니다. REST API를 사용하거나, 번들된 종속성 해결 방식으로 전환하거나, 업로드 내용 전체를 완전히 제어해야 하는 경우 이 내용을 읽어보세요.

zip은 루트에서 평평해야 하며 최상위 래퍼 폴더는 없어야 합니다.

에이전트 언어에 대한 탭을 선택합니다.

Python 레이아웃(원격 빌드 모드)

서비스는 클라우드에서 requirements.txt의 종속성을 설치합니다.

agent-code.zip
+-- main.py
+-- requirements.txt

Python 레이아웃(번들 모드)

packages/에 사전 빌드된 리눅스 종속성을 포함합니다.

agent-code.zip
+-- main.py                    # entry point
+-- requirements.txt
+-- packages/                  # extracted modules (not raw .whl files)
    +-- azure/identity/__init__.py
    +-- requests/__init__.py

Linux 종속성을 로컬로 빌드(번들, Python)

manylinux2014_x86_64 플랫폼 태그를 사용하여 pip Windows 또는 macOS에서도 Linux 휠을 다운로드합니다.

Bash

pip install -r requirements.txt \
    --target packages/ \
    --platform manylinux2014_x86_64 \
    --python-version 3.13 \
    --implementation cp \
    --only-binary=:all:

zip -r agent-code.zip main.py requirements.txt packages/

PowerShell/Windows cmd

pip install -r requirements.txt --target packages --platform manylinux2014_x86_64 --python-version 3.13 --implementation cp --only-binary=:all:

tar -a -c -f agent-code.zip main.py requirements.txt packages

--only-binary=:all:는 휠을 강제로 만듭니다(원본 빌드 없음). 에이전트 --python-version 정의의 값과 runtime 일치해야 합니다.

Warning

session_creation_failed 또는 ModuleNotFoundError를 유발하는 일반적인 패키징 실수:

  • 원본을 폴더에 래핑(루트에서는 my-agent/main.py 대신 main.py).
  • 추출된 모듈 대신 원시 .whl 파일을 packages/ 포함합니다.
  • Linux 런타임에 Windows 이진 파일(.pyd, .dll)을 묶습니다.

Limits

Limit 가치
최대 zip 크기(다중 파트 업로드) 250MB

지원되는 cpu 항목과 memory 조합은 샌드박스 크기를 참조하세요.

Troubleshooting

증상 가능한 원인 수정
401 Unauthorized 누락되었거나 범위가 잘못된 토큰 --resource https://ai.azure.com를 사용하여 토큰을 획득합니다.
403 Forbidden 호출자에게 프로젝트에 대한 역할 기반 액세스 제어 권한이 없습니다. 프로젝트 범위에 Foundry 에이전트 소비자(호출만 하는 경우) 또는 Foundry 사용자(개발도 하는 경우)를 부여하세요.
409 conflict: 만들기에서(Agent '<name>' already exists) 에이전트 이름이 이미 있음 업데이트(POST /agents/{name})를 사용하거나 새 이름을 선택합니다.
생성 또는 업데이트의 400 bad_request (CPU and Memory must be specified as a valid resource tier) cpu / memory 은 지원되는 계층 중 하나가 아닙니다. cpu 및 memory을 샌드박스 크기에서 유효한 쌍으로 설정합니다.
400 bad_request (Agent version is still being provisioned) 호출 시 새 버전의 배포가 진행 중이며 활성 버전이 전환되고 있습니다. status까지 버전 active을 폴링한 다음, 다시 시도합니다.
424 session_not_ready 호출 시 컨테이너가 시작되었지만 /readiness 시간 제한 내에 HTTP 200을 반환하지 않았습니다. :logstream로 로그를 스트리밍하고, 준비 상태 프로브 또는 시작 오류를 수정한 후 다시 배포하세요.
409 conflict: DELETE 에이전트에서(Agent has active sessions) 열린 세션으로 인해 삭제가 차단됨 세션이 유휴 상태가 될 때까지 기다리거나 연속 삭제 세션에 추가 &force=true 합니다.
버전이 creating에서 멈춤 (>10분, 원격 빌드) 서버 빌드가 실패했거나 확인할 수 없습니다. requirements.txt 로컬로 dependency_resolution: bundled 전환하고 미리 빌드합니다.
프라이빗 가상 네트워크에서 배포 실패 필요한 아웃바운드 엔드포인트는 방화벽에 의해 차단됩니다. 프라이빗 가상 네트워크에 대한 방화벽 요구 사항의 엔드포인트를 허용한 다음 다시 배포합니다.
버전이 failed로 전환됩니다. 잘못된 zip 레이아웃, 구문 오류 또는 (remote_build) 복원/컴파일 실패 버전의 error 개체를 먼저 읽습니다. error.code 오류를 분류하고 error.message에는 기본 복원 또는 컴파일 오류 줄(Python pip, .NET 경우 NuGet)과 문제 해결 링크가 포함되어 있습니다. 폴더 구조를 확인합니다. 컨테이너가 시작된 후에만 사용합니다 :logstream .
ModuleNotFoundError: 런타임 시. packages/ 누락되었거나, 원시 .whl 파일을 포함하거나, Windows 이진 파일이 있습니다. pip install --target packages/ --platform manylinux2014_x86_64 --only-binary=:all:로 다시 빌드합니다.
409 AgentNotCodeBased 다운로드할 때 에이전트는 이미지 기반입니다. 컨테이너 기반 배포 문서를 사용합니다.

자원을 정리하세요

빠른 시작azd에서 프로젝트를 스캐폴드한 경우 프로젝트 루트에서 실행 azd down 하여 프로비전된 전체 환경을 제거합니다.

SDK 또는 REST API를 사용하여 배포한 에이전트를 삭제하려면 아래와 일치하는 경로를 사용합니다.

# Delete one version
project.agents.delete_version(agent_name=AGENT_NAME, agent_version=created.version)

# Delete the agent and all its versions
project.agents.delete(agent_name=AGENT_NAME)

Warning

에이전트를 삭제하면 모든 버전이 제거되고 활성 세션이 종료됩니다. 이 작업은 취소할 수 없습니다.

다음 단계

호스트된 에이전트 수명 주기 관리

관련 콘텐츠

  • Last updated on