다음을 통해 공유

Azure Developer CLI AI 에이전트 확장을 사용하여 Microsoft Foundry에 에이전트 배포

이 문서에서는 Azure 개발자 CLI(azd) AI 에이전트 확장을 사용하여 Microsoft Foundry에서 에이전트를 설정하고 배포하는 방법을 알아봅니다. 확장을 사용하면 터미널 또는 편집기에서 에이전트를 스캐폴드하고 배포할 수 있으며, 일관된 로컬-클라우드 워크플로를 위해 Foundry 기능과 azd 수명 주기 명령(azd init, azd up)을 결합할 수 있습니다.

주요 기능

  • 프로젝트 스캐폴딩: 전체 에이전트 프로젝트(코드 템플릿, 에이전트 정의, 구성으로 인프라)를 설정하고 즉시 반복을 시작합니다.
  • 선언적 구성: 일관된 환경을 위해 파일에서 서비스, 리소스 및 모델 배포를 azure.yaml 정의합니다.
  • 통합 프로비전 및 배포: 실행 azd up 하여 컨테이너를 빌드하고, 이미지를 푸시하고, 리소스를 만들고, 모델을 배포하고, 에이전트를 한 단계로 게시합니다.
  • 에이전트 정의 관리: 카탈로그, GitHub 또는 로컬 경로에서 에이전트 정의를 가져옵니다. CLI는 필요한 매개 변수를 환경 변수에 매핑합니다.
  • 기본적으로 보안: 자격 증명을 수동으로 처리하지 않고 관리 ID 및 기준 보안을 자동으로 설정합니다.
  • 확장 가능한 모델 프로비전: 모델 이름, 버전 및 용량을 지정합니다. azd 은 여러 환경에서 일관되게 배포합니다.

필수 조건

  • Azure 개발자 CLI(azd)가 설치되고(버전 1.21.3 이상) 인증되었습니다azd auth login.
    • 설치된 azd ai agent 확장(azd extension install azure.ai.agents)입니다. 확장이 설치되어 있지 않으면 시작 템플릿을 초기화하거나 확장을 실행할 azd ai agent 때 자동으로 설치됩니다.
  • 리소스 그룹 및 Microsoft Foundry 리소스를 만들 수 있는 권한이 있는 Azure 구독 입니다.
  • 필요한 작업을 위해 설치된 Azure CLI 입니다.

에이전트 설정 및 배포

다음 섹션을 완료하여 AI 에이전트 확장을 사용하여 Microsoft Foundry에 에이전트를 azd 프로비전하고 배포합니다.

Foundry 템플릿 초기화

  1. 템플릿을 사용하여 새 프로젝트를 초기화합니다 azd-ai-starter-basic . 빈 폴더에서 다음을 실행합니다.

    azd init -t Azure-Samples/azd-ai-starter-basic --location northcentralus

    비고

    호스트된 에이전트는 현재 미국 중북부 Azure 지역으로 제한됩니다. Microsoft Foundry 설명서에서 호스트된 에이전트 지역 사용에 대해 자세히 알아보세요.

  2. 메시지가 표시되면 에이전트 프로젝트의 환경 이름(예: "my-analytics-agent")을 입력합니다.

    프로세스:azd init

    • 시작 템플릿 파일을 프로젝트에 복제합니다.
    • (코드로서의 인프라 파일) 및 infra/ 폴더를 사용하여 src/ 디렉터리 구조를 만듭니다.
    • 구성 파일을 생성합니다.azure.yaml
    • 환경별 변수 .azure/<env>/.env 설정

에이전트 정의 초기화

시작 템플릿은 프로젝트 구조를 제공하지만 특정 에이전트 정의를 추가해야 합니다. 에이전트 정의는 에이전트의 동작, 도구 및 기능을 설명합니다. 에이전트 프레임워크 리포지토리에서 예제 정의를 찾습니다.

사용자 고유의 에이전트 정의 또는 카탈로그의 에이전트 정의를 사용합니다. 사용자 고유 azd ai agent init 의 <agent-definition-url> 값으로 명령을 실행합니다.

azd ai agent init -m <agent-definition-url>

예를 들어 간단한 계산기 에이전트에 다음 URL을 사용합니다.

azd ai agent init -m https://github.com/azure-ai-foundry/foundry-samples/blob/main/samples/python/hosted-agents/calculator-agent/agent.yaml

azd ai agent init 명령은 다음을 수행합니다.

  • 에이전트 정의 YAML 파일을 프로젝트의 src/ 디렉터리에 다운로드합니다.
  • 에이전트 정의를 분석하여 요구 사항을 이해합니다.
  • azure.yaml 해당 서비스 및 구성을 사용하여 업데이트
  • 에이전트 매개 변수를 환경 변수에 매핑

프로젝트 구조 검토

초기화된 템플릿에는 다음 키 파일이 포함됩니다.

├── .azure/                 # Environment-specific settings (.env)
├── infra/                  # Bicep files for Azure infrastructure
├── src/                    # Agent definition and code
└── azure.yaml              # Project configuration

에이전트 프로젝트를 설정하는 방법을 보려면 다음 azure.yaml 을 엽니다.

requiredVersions:
    extensions:
        azure.ai.agents: latest
services:
    CalculatorAgent:
        project: src/CalculatorAgent
        host: azure.ai.agent
        language: docker
        docker:
            remoteBuild: true
        config:
            container:
                resources:
                    cpu: "1"
                    memory: 2Gi
                scale:
                    maxReplicas: 3
                    minReplicas: 1
            deployments:
                - model:
                    format: OpenAI
                    name: gpt-4o-mini
                    version: "2024-07-18"
                  name: gpt-4o-mini
                  sku:
                    capacity: 10
                    name: GlobalStandard
infra:
    provider: bicep
    path: ./infra
    module: main

이 선언적 구성은 모델 배포를 포함하여 에이전트 서비스 및 필요한 Azure AI 리소스를 정의합니다.

에이전트 프로비전 및 배포

실행 azd up 하여 리소스 및 에이전트를 배포합니다.

azd up

이 azd up 명령은 인프라에서 라이브 에이전트 엔드포인트로 배포 워크플로를 오케스트레이션합니다.

  • 인프라 프로비전: Bicep 파일에 정의된 Microsoft Foundry 계정, 프로젝트 및 Azure 리소스를 만듭니다. - 사전 프로비전 후크는 에이전트 및 해당 종속성, 모델 및 기타 리소스를 검사한 다음, Bicep이 다음을 포함하여 프로비전할 항목을 알 수 있도록 환경 변수를 채웁니다. - AI_PROJECT_DEPLOYMENTS (JSON): 배포할 모델의 사양입니다. - AI_PROJECT_CONNECTIONS (JSON): 만들려는 연결의 사양입니다. - AI_PROJECT_DEPENDENT_RESOURCES (JSON): 종속 리소스의 사양입니다. - ENABLE_HOSTED_AGENTS (부울): 호스트된 에이전트를 프로비전해야 하는지 여부(ACR 및 CapHost 포함).
  • 모델 배포: 지정된 azure.yaml 모델 배포를 프로비전합니다(예: 구성된 용량으로 GPT-4o-mini).
  • 컨테이너 빌드 및 푸시: 에이전트에 사용자 지정 코드 azd 가 있는 경우 컨테이너 이미지에 패키지하고 Azure Container Registry에 푸시합니다.
  • 에이전트 게시: Microsoft Foundry에서 에이전트 애플리케이션을 만들고 에이전트를 호출 가능한 라이브 서비스로 배포합니다.

azd up 완료되면 출력에 Microsoft Foundry 프로젝트 엔드포인트, 리소스 그룹 및 프로젝트 이름 및 에이전트 애플리케이션 세부 정보가 표시됩니다. 또한 출력은 Microsoft Foundry 포털의 에이전트 플레이그라운드에 대한 직접 링크를 제공합니다.

비고

새 프로젝트의 경우 프로비전 및 배포 프로세스를 완료하는 데 일반적으로 몇 분 정도 걸립니다.

ID 및 보안

azd 는 자격 증명을 수동으로 관리할 필요가 없도록 보안 액세스 패턴을 자동으로 구성합니다.

  • 관리 ID: 에이전트는 Foundry 프로젝트의 시스템 할당 관리 ID를 사용하여 다른 Azure 리소스로 인증합니다.
  • 역할 할당: azd 필요한 권한을 자동으로 부여합니다(예: Azure AI 서비스, 스토리지 또는 데이터베이스에 대한 에이전트 액세스 권한 부여).
  • 엔드포인트 보안: 에이전트 엔드포인트는 기본적으로 Microsoft Entra ID(Azure AD) 인증을 사용하므로 권한 있는 사용자 또는 애플리케이션만 에이전트를 호출할 수 있습니다.

이러한 보안 구성은 Azure 모범 사례를 따르고 기본적으로 작동하므로 보안 기반부터 시작합니다.

Microsoft Foundry에서 에이전트 테스트

  1. Microsoft Foundry 포털을 엽니다.
  2. 프로젝트 이름으로 설정된 azd 프로젝트로 이동합니다(출력에 azd up 프로젝트 이름이 표시됨).
  3. 에이전트 섹션 을 열어 배포된 에이전트를 확인합니다.
  4. 플레이그라운드에서 에이전트를 시작하고 "기능 요약"과 같은 테스트 쿼리를 보냅니다.

채팅 창에 에이전트의 응답이 표시됩니다.

고급 구성

기본 워크플로 이외의 고급 요구 사항을 충족하도록 프로젝트를 사용자 지정할 수 있습니다.

모델 배포 환경 구성

이 azure.yaml 파일을 사용하면 배포하는 모델을 제어할 수 있습니다. 모델을 추가하거나 변경하려면 파일을 편집합니다.

services:
    CalculatorAgent:
        project: src/CalculatorAgent
        host: azure.ai.agent
        language: docker
        docker:
            remoteBuild: true
        config:
            container:
                resources:
                    cpu: "1"
                    memory: 2Gi
                scale:
                    maxReplicas: 3
                    minReplicas: 1
            deployments:
                - model:
                    format: OpenAI
                    name: gpt-4o-mini
                    version: "2024-07-18"
                  name: gpt-4o-mini
                  sku:
                    capacity: 10
                    name: GlobalStandard

실행 azd up 하여 새 모델을 배포하고 프로젝트를 업데이트합니다.

이 샘플 구성은 에이전트가 복잡한 추론을 위해 더 큰 모델을 사용하고 간단한 쿼리에 더 작은 모델을 사용할 수 있도록 여러 모델을 배포합니다.

환경 변수 관리

설정하거나 사용하는 환경 변수 azd :

변수 목적
AZURE_SUBSCRIPTION_ID 리소스에 대한 대상 구독입니다.
AZURE_RESOURCE_GROUP AI 프로젝트를 호스트하는 리소스 그룹입니다.
AZURE_LOCATION Azure 지역(선택한 모델을 지원해야 합니다).
AZURE_AI_ACCOUNT_NAME Microsoft Foundry 계정(허브).
AZURE_AI_PROJECT_NAME 에이전트를 호스팅하는 프로젝트입니다.
AZURE_AI_FOUNDRY_PROJECT_ENDPOINT 에이전트 관리 및 런타임 호출을 위한 엔드포인트입니다.

이러한 변수는 에 .azure/<environment-name>/.env저장됩니다. 각 환경(개발, 테스트 및 prod)에 맞게 사용자 지정합니다.

샘플 사용 사례 및 시나리오

Microsoft Foundry를 사용하여 다양한 에이전트 시나리오를 가속화하기 위해 AI 에이전트 확장을 사용합니다 azd .

대화형 도우미 빌드

컨텍스트를 사용하여 질문에 대답하고 내부 데이터에 연결하는 에이전트를 만듭니다.

  • A/B 테스트를 위한 변형 배포
  • 검색 보강 응답을 위한 Azure AI Search 추가
  • 사용자 지정 도구를 통해 비즈니스 API 통합

데이터 및 인사이트 에이전트 빌드

요약, 계산 및 시각화를 제공합니다.

  • Azure SQL Database 또는 Cosmos DB에 연결합니다.
  • 계산에 코드 인터프리터 도구 사용
  • 더 작은 비용 효율적인 모델과 더 큰 추론 모델 혼합

여러 에이전트를 오케스트레이션하다

복잡한 워크플로에 대한 전문가를 조정합니다.

  • 요청을 라우팅하는 코디네이터 에이전트를 추가합니다.
  • 에서 azure.yaml선언적으로 관계를 정의합니다.
  • 부하에 따라 독립적으로 에이전트 크기를 조정합니다.

엔터프라이즈 배포 표준화

팀 전체에서 일관성을 유지합니다.

  • 재사용 가능한 청사진 및 템플릿 게시
  • 일관된 보안, 규정 준수 및 모니터링 적용
  • CI/CD에서 azd provision와azd deploy을 사용하여 프로비저닝과 배포를 자동화합니다.

에코시스템 살펴보기

추가 리소스

  • Last updated on