중요합니다
이 문서에서 미리 보기로 표시된 항목은 현재 미리 보기로 제공됩니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며 Microsoft 프로덕션 워크로드에 권장하지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.
Azure 개발자 CLI(azd) 및 확장 azd ai agent 은 아이디어에서 Microsoft Foundry의 프로덕션 준비 에이전트로 이동하는 단일 명령줄 워크플로를 제공합니다. 코드 기반 호스팅 에이전트 및 선언적 프롬프트 기반 음성 에이전트를 개발할 수 있습니다. 이 문서에서는 개발자 경험, 에이전트를 정의하는 파일 및 그 과정에서 발생하는 핵심 개념을 설명합니다.
이 문서는 Foundry 포털 또는 언어 SDK보다 터미널 우선 스크립트 가능 워크플로를 선호하는 개발자를 위한 것입니다.
개발자 경험
워크플로는 azd ai 작은 프로토타입 또는 프로덕션 에이전트를 빌드하든 동일한 수명 주기를 따릅니다. 프로젝트를 한 번 스캐폴드한 다음, 프로젝트가 증가함에 따라 명령을 혼합하고 일치시킬 수 있습니다.
| 단계 | 수행할 일 | 자세히 알아볼 수 있는 위치 |
|---|---|---|
| Install |
azd 및 Foundry 확장을 설치합니다. |
개발자 환경 설정 |
| 스캐폴드 | 템플릿 또는 기존 코드에서 호스트된 에이전트를 초기화하거나 프롬프트 기반 음성 에이전트를 만듭니다. | 빠른 시작: 호스팅된 에이전트 배포 또는 빠른 시작: 프롬프트 음성 에이전트 만들기 |
| 정의 | 에서 에이전트, 모델 배포 종속성, 프로토콜, 도구 및 환경을 azure.yaml구성합니다. |
호스팅된 에이전트용 azure.yaml 작성 |
| Develop | 에이전트 논리를 작성하고, 도구 상자를 사용하여 도구를 추가하고, 로컬로 테스트합니다. | 도구 상자 개요 |
| Deploy | 인프라를 프로비전하고 Foundry에 배포합니다. | 호스트된 에이전트 배포 |
| Operate | 로그를 모니터링하고, 버전을 관리하고, 실행을 자동화합니다. | 호스트된 에이전트 관리 |
| Evaluate | 에이전트 품질을 측정하고 프롬프트를 개선합니다. | azd CLI를 사용하여 에이전트 평가 실행 |
에이전트 유형
확장은 azd ai agent 호스팅형, 프롬프트형 및 음성 에이전트를 지원합니다.
| 유형 | Description | 사용 시기 |
|---|---|---|
| 호스팅 에이전트 | 소스 코드 또는 컨테이너 이미지로 배포하는 애플리케이션입니다. | 사용자 지정 논리, 프레임워크 통합 또는 동작에 대한 모든 권한이 필요합니다. |
| 프롬프트 에이전트 | 사용자 지정 코드 없이 지침 및 도구 구성을 통해 완전히 정의된 에이전트입니다. | 애플리케이션 코드를 작성하지 않고도 빠른 구성 기반 에이전트를 원합니다. |
| 음성 에이전트 | 선언적 프롬프트 음성 에이전트 또는 호스트된 에이전트에 연결하는 음성 래퍼입니다. | Voice Live 클라이언트를 통해 실시간 음성 경험이 필요합니다. |
호스트된 에이전트는 런타임, 프레임워크 및 도구 통합을 완전히 제어하고 Foundry는 인프라, 크기 조정 및 세션 관리를 처리합니다.
프롬프트 기반 음성 에이전트에는 사용자 지정 컨테이너가 필요하지 않습니다. 사용자 고유의 컨테이너에서 사용자 지정 음성 변환 또는 계단식 오디오 파이프라인을 실행해야 하는 경우 호스트된 에이전트를 사용하여 음성 에이전트를 빌드하고 프로토콜을 invocations_ws 사용합니다.
Voice Live가 오디오를 처리하는 동안 호스트된 텍스트 에이전트에 대화 논리를 유지하려면 호스트된 음성 래퍼 워크플로를 사용합니다. 래퍼와 대상은 동일한 azure.yaml 프로젝트의 별도 서비스입니다. 이 흐름은 기존 사용자 지정 invocations_ws 오디오 파이프라인 흐름을 대체하지 않습니다.
공개 미리 보기 음성 CLI 옵션을 사용하기 전에 음성 에이전트 빠른 시작 필수 구성 요소에 설명된 대로 설치된 확장을 확인합니다.
구성 파일
호스트된 에이전트 프로젝트는 프로젝트 루트에서 하나의 azure.yaml 파일을 사용하여 에이전트와 해당 프로비저닝 및 배포 모델을 모두 선언합니다. 파일은 분할 서비스 모델을 사용합니다. 여기서 명명된 각 서비스에는 host , azure.ai.project, azure.ai.agent, azure.ai.connectionazure.ai.toolbox또는 azure.ai.skill와 같은 azure.ai.routine값이 있습니다.
| 파일 | 목적 | 누가 유지 관리 |
|---|---|---|
azure.yaml |
Foundry 프로젝트, 모델 배포, 호스트된 에이전트 서비스, 종속성, 프로토콜, 도구, 환경 변수, 컨테이너 리소스 및 배포 설정을 선언합니다. 에이전트 ID, 모델, 프로토콜, 도구 및 환경 값은 azure.ai.agent 서비스에 있습니다. |
초기화 시 생성됩니다. 필요에 따라 사용자 지정합니다. |
서비스는 azure.ai.agent 에이전트를 인라인으로 또는 직접 YAML 또는 JSON 정의를 가리키는 명시적 루트 $ref 를 통해 정의합니다. 파일 기반 서비스에는 azd ai agent add <service> --file <path>를 사용합니다. 매개 변수가 있는 AgentManifest 래퍼는 현재 초기화에서 지원되지 않습니다. 서비스의 uses: 목록은 프로젝트, 연결 및 도구 상자와 같은 종속성을 참조합니다.
프롬프트 기반 음성 에이전트의 경우 모델, azure.yaml 모델 유형 및 에이전트 이름을 비롯한 kind: prompt-voice선언적 에이전트 정의를 저장합니다. 호스트 에이전트 컨테이너 런타임은 포함되지 않습니다. 지침, 오디오, 턴 감지, 전사, 음성 출력, 도구 및 인사말을 사용자 지정하려면 음성 에이전트 구성을 참조하세요.
호스트된 음성 래퍼 conversationEngine.name 의 경우 호스트된 대상의 서비스 이름을 참조합니다. 래퍼의 uses 종속성은 배포를 주문하며 conversationEngine.version , 기본적으로 현재 환경에서 배포된 버전으로 설정됩니다. 구성 필드에 대한 음성 서비스 참조 를 참조하세요.
변수 치환
${VAR_NAME} 환경에 따라 달라지는 값에는 azure.yaml에서 azd을 사용합니다. 플레이스홀더는 배포 시 또는 실행 시 .azure/<env>/.env에서 해석되므로 개발, 스테이징, 프로덕션과 같은 여러 환경에서 동일한 azure.yaml를 사용할 수 있습니다.
CLI가 실행되는 위치
azd ai 명령은 azd 프로젝트 디렉터리 내부와 외부 모두에서 작동합니다.
-
azd프로젝트 내에서는 명령이 활성azd환경에서 Foundry 프로젝트 엔드포인트를 해결합니다. -
azd프로젝트 외부에서는azd ai project set <endpoint>로 활성 컨텍스트를 한 번 설정하거나, 개별 리소스 명령(--project-endpoint,connection,toolbox또는skill)에routine를 지정합니다. 대체 수단으로,azd ai는FOUNDRY_PROJECT_ENDPOINT환경 변수를 읽습니다. - 활성 환경에서 확인된 비어 있지 않은 엔드포인트가 전역 컨텍스트보다 우선합니다. 셸 대체 및 명령별 동작에 대해서는 프로젝트 컨텍스트 설정을 참조하세요.
Protocols
프로토콜은 Foundry와 에이전트 컨테이너 간의 HTTP 계약을 정의합니다. 에이전트는 포트 8088에서 수신 대기하고 프로토콜에 관계없이 상태 프로브를 제공합니다.
| Protocol | API 스타일 | 사용 시기 |
|---|---|---|
responses |
OpenAI 응답 API(POST /responses) |
OpenAI API 에코시스템과 호환되는 표준 선택입니다. |
invocations |
사용자 지정 JSON 계약(POST /invocations) |
요청 및 응답 페이로드를 완전히 제어해야 하는 경우 |
전체 사양은 호스팅된 에이전트 런타임 계약을 참조하세요.
이러한 프로토콜 설정은 호스트 에이전트 컨테이너에 적용됩니다. 프롬프트 기반 음성 에이전트는 호스트 에이전트 프로토콜을 구성하지 않습니다.
azd ai agent invoke 는 프롬프트 기반 음성 에이전트 또는 호스트된 음성 래퍼에 대한 음성 대화를 구현하지 않습니다. CLI 동작 및 테스트 지침은 음성 에이전트 제한 사항을 참조하세요.
세션 및 대화
| 개념 | Description |
|---|---|
| Session | 단일 에이전트 상호 작용을 위한 격리된 실행 환경입니다. 각 세션은 전용 리소스가 있는 자체 샌드박스에서 실행됩니다. |
| 대화 | 응답 프로토콜에 대한 메시지 기록입니다. 호출은 대화 기록을 자동으로 저장하지 않습니다. |
세션은 .로 식별됩니다 session_id. CLI는 에이전트당 세션 선택을 저장하고 기본적으로 다시 사용합니다. 새로 시작하거나 --new-session 특정 세션을 대상으로 지정하는 데 사용합니다--session-id <id>. 캐시는 위임된 사용자별로 키 지정되지 않습니다. --user-identity를 사용할 때 명시적 사용자-세션 매핑을 유지합니다.
Foundry 프로젝트의 리소스
Foundry 프로젝트는 에이전트 이상을 호스트합니다. 또한 에이전트가 런타임에 참조하는 공유 리소스도 보유합니다. CLI는 전용 명령 그룹을 통해 각각을 관리합니다.
| Resource | 그것이 무엇인지 | 을 사용하여 관리 |
|---|---|---|
| Connection | Foundry 프로젝트를 MCP 서버, Azure AI 검색, Bing 기반 그라운딩과 같은 외부 리소스에 연결합니다. |
azd ai connection 명령어 |
| 도구 상자 | 에이전트가 런타임에 사용하는 명명된 도구 컬렉션입니다. |
azd ai toolbox 명령어 |
| 기술 | 프로젝트의 에이전트 간에 공유되는 재사용 가능한 동작 지침입니다. |
azd ai skill 명령어 |
| 루틴 | 트리거와 에이전트를 호출하는 작업 |
azd ai routine 명령어 |
이러한 리소스는 동일한 프로젝트의 개발자와 에이전트 간에 공유됩니다. 해당 명령은 서로 다릅니다. 연결 및 루틴은 update을 통해, 기술은 update을 통해 새 버전을 게시하며, 도구 상자는 버전 생성 연결 및 기술 변형을 수행한 다음 publish를 사용합니다.
에이전트 평가 및 개선
에이전트가 실행된 후 두 개의 관련 워크플로를 통해 품질을 측정하고 개선하는 데 도움이 됩니다.
- 빠른 에이전트 평가는
azd ai agent eval와 로컬eval.yaml를 사용하며, 최적화 프로그램 워크플로를 포함합니다. 프로젝트 평가에서는 별도로 설치된azd ai eval확장과evals/azure.eval.yaml, 그리고 추적 또는 데이터 세트 소스와 명시적 CI 품질 게이트를 사용합니다. 두 구성 형식은 서로 바꿔 사용할 수 없습니다. - 최적화는 에이전트의 프롬프트를 반복적으로 다시 작성하여 평가 신호를 해제합니다. 평가를 목표 함수로 사용하고 검토하고 수락하는 후보 프롬프트를 생성합니다.
azd ai agent optimize로 관리합니다.
자세한 내용은 azd CLI 및 Optimize 에이전트 프롬프트를 사용하여 에이전트 평가 실행을 참조하세요.
개발자 직무별 명령 그룹
필요한 결과에 대한 명령을 선택합니다. 플래그 및 지원되는 출력 형식을 검사하려면 --help을 추가합니다.
| Job | Commands | 지침 |
|---|---|---|
| 프로젝트 및 관리형 모델 구성 |
azd ai project add, azd ai project deployment add |
프로젝트 구성 및 컨텍스트 |
| 엔드포인트 컨텍스트 선택 또는 검사 |
azd ai project set, azd ai project show, , azd ai project unset, azd ai project context |
전역 엔드포인트 선택은 인프라 선언과는 별개입니다. 컨텍스트 출력에는 민감한 정보가 포함될 수 있습니다. |
| 샘플 찾아보기 또는 에이전트 초기화 |
azd ai agent sample list, azd ai agent init, azd ai agent add |
호스팅된, 프롬프트 및 음성 에이전트 초기화 |
| 에이전트를 위한 문서 및 콘텐츠 구문 분석, 추출 및 분류 |
azd ai cu analyze, azd ai cu analyzer |
Azure Content Understanding CLI 빠른 시작(미리 보기) |
| 로컬로 실행 및 검사 |
azd ai agent run, azd ai inspector launch |
로컬 개발 |
| 호출, 사용자 ID 위임 또는 사용자 지정 헤더 보내기 | azd ai agent invoke |
호출 옵션 |
| 작업 검사, 추적 또는 취소 |
azd ai agent invocations show, azd ai agent invocations follow, azd ai agent invocations cancel |
장기 실행 호출 |
| 엔드포인트 검사 또는 업데이트 |
azd ai agent endpoint show, azd ai agent endpoint update |
엔드포인트 및 카드 업데이트 |
| 상태 검사, 문제 진단 또는 로그 읽기 |
azd ai agent show, azd ai agent doctor, azd ai agent monitor |
진단 및로그 |
| 샌드박스 만들기, 목록 보기, 확인, 중지 또는 삭제 |
azd ai agent sessions create, azd ai agent sessions list, azd ai agent sessions show, azd ai agent sessions stopazd ai agent sessions delete |
세션 관리 |
| 샌드박스 파일 생성, 검색 또는 유지 관리 |
azd ai agent files upload, azd ai agent files download, azd ai agent files list, azd ai agent files mkdir, azd ai agent files statazd ai agent files delete |
세션 파일 작업 |
| 배포된 원본을 복구 | azd ai agent code download |
코드 또는 ZIP 다운로드 |
| 내구성 저장소 검사 및 공유 항목 유지 관리 |
azd ai agent state-stores list, azd ai agent state-stores select, , azd ai agent state-stores show, azd ai agent state-stores items |
상태 저장 작업 및 제한 |
| 배포 구성에 에이전트 종속성 추가 |
azd ai agent connection add, azd ai agent toolbox add |
두 서비스는 azure.yaml에 이미 있어야 합니다. 이러한 명령은 원격 리소스가 아니라 uses 항목을 추가합니다. |
| 연결 자격 증명 및 메타데이터 관리 |
azd ai connection create, azd ai connection list, azd ai connection show, azd ai connection updateazd ai connection delete |
연결 인증 및 유지 관리 |
| 작성자, 버전 또는 재사용 가능한 스킬 다운로드 |
azd ai skill add, azd ai skill create, azd ai skill update, azd ai skill list, azd ai skill show, azd ai skill download, azd ai skill delete |
스킬 워크플로 |
| 도구 상자 만들기 및 관리 |
azd ai toolbox add, azd ai toolbox create, azd ai toolbox list, azd ai toolbox showazd ai toolbox delete |
도구상자 구성 |
| 도구 모음을 발전시키고 홍보 |
azd ai toolbox connection, azd ai toolbox skill, , azd ai toolbox versions list, azd ai toolbox publish |
뮤테이션은 최신 버전에서 분기되고, 승격은 명시적입니다. |
| 루틴을 예약, 전송 또는 검사 |
azd ai routine add, azd ai routine create, azd ai routine list, azd ai routine show, azd ai routine update, azd ai routine enable, azd ai routine disableazd ai routine dispatch, azd ai routine run listazd ai routine delete |
루틴 워크플로 |
| 빠른 평가 생성 및 실행 |
azd ai agent eval generate, azd ai agent eval update, azd ai agent eval run, azd ai agent eval listazd ai agent eval show |
빠른 평가 및 옵티마이저 자산 |
| 최적화 후보 개선 및 배포 |
azd ai agent optimize, azd ai agent optimize status, azd ai agent optimize list, azd ai agent optimize cancel, azd ai agent optimize applyazd ai agent optimize deploy |
최적화 워크플로 |
| Teams용 활동 에이전트 패키지 또는 게시 |
azd ai agent pack, azd ai agent publish |
팀 배포 |
| 호스팅된 버전 또는 에이전트 삭제 | azd ai agent delete |
에이전트 삭제 |
| 프로젝트 평가 및 품질 게이트 시행 |
azd ai eval init, azd ai eval generate, azd ai eval create, azd ai eval run, azd ai eval dataset, azd ai eval evaluator, azd ai eval job |
프로젝트 평가; azure.ai.evaluations을 별도로 설치합니다. |
| 재사용 가능한 데이터 세트 등록 및 버전 관리 | azd ai dataset |
데이터 세트 수명 주기; azure.ai.dataset은 별도로 설치합니다. |
| 미세 조정 작업 제출, 일시 중지, 다시 시작, 취소 또는 배포 |
azd ai finetuning init, azd ai finetuning jobs |
미세 조정; azure.ai.finetune은 별도로 설치합니다. |
| 사용자 지정 모델 가중치 업로드 및 관리 | azd ai models |
사용자 지정 모델 가져오기 및 유지 관리; azure.ai.models를 별도로 설치합니다. |
명령을 추가하는 각 확장은 azd ext list을 노출합니다. 대신 version로 microsoft.foundry 번들을 검사하세요. 연결, 루틴 및 기술 그룹은 로컬 프로젝트 및 환경 검사에도 context를 제공하며, 출력을 잠재적으로 중요한 것으로 처리합니다.
활동 에이전트 배포
Activity-protocol 에이전트를 배포한 후 azd ai agent pack는 사이드로드를 위해 appPackage.zip를 만듭니다.
--display-name, --app-version, --output-dir를 사용하여 패키지를 사용자 지정합니다. 패키징은 퍼블리싱과 동일하지 않습니다.
azd ai agent publish는 Microsoft 365 통해 게시됩니다. 단순 활동 에이전트는 달리 구성하지 않는 한 shared 배포를 기본값으로 사용합니다. --scope tenant에는 관리자의 승인이 필요합니다. 디지털 작업자에 테넌트 범위가 필요합니다. 반복 가능한 --access-boundary 값을 사용하고, --clear-access-boundaries을 사용하여 기존 경계를 제거하고, 선택적 권한에 대해 반복 가능한 --optional-permission-scope <resource-app-id>=<scope> 값을 사용합니다.
personal는 게시 범위가 아닙니다. 사용자별 테스트를 위해 pack --scope personal를 사용하고 패키지를 사이드로드합니다.
배포 수명 주기
전체 개발자 루프는 짧은 명령 시퀀스로 압축됩니다. 한 번 스캐폴드한 다음 프로젝트가 커지면 직접 명령을 사용합니다.
관리되는 음성 에이전트 경로는 빠른 시작: 프롬프트 음성 에이전트 만들기를 참조하세요.
# Scaffold a project from a template or your existing code
azd ai agent init
# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"
# Provision infrastructure and deploy the agent
azd up
# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent
# Evaluate quality
azd ai agent eval generate
azd ai agent eval run
# Tear down all Azure resources
azd down