Azure Developer CLI를 사용한 에이전트 개발

Azure 개발자 CLI(azd) 및 해당 azd ai agent 확장은 아이디어에서 Microsoft Foundry의 프로덕션 준비 호스트 에이전트로 이동하는 단일 명령줄 워크플로를 제공합니다. 이 문서에서는 개발자 경험, 에이전트를 정의하는 파일 및 그 과정에서 발생하는 핵심 개념을 설명합니다.

이 문서는 Foundry 포털 또는 언어 SDK보다 터미널 우선 스크립트 가능 워크플로를 선호하는 개발자를 위한 것입니다.

개발자 경험

워크플로는 azd ai 작은 프로토타입 또는 프로덕션 에이전트를 빌드하든 동일한 수명 주기를 따릅니다. 프로젝트를 한 번 스캐폴드한 다음, 프로젝트가 증가함에 따라 명령을 혼합하고 일치시킬 수 있습니다.

에이전트 유형

확장은 azd ai agent 호스트된 에이전트에 중점을 둡니다.

호스트된 에이전트는 런타임, 프레임워크 및 도구 통합을 완전히 제어하고 Foundry는 인프라, 크기 조정 및 세션 관리를 처리합니다.

구성 파일

세 개의 파일은 에이전트를 빌드하고 배포하는 방법을 정의합니다.

중요한 차이점은 에이전트가 agent.yaml무엇인지 설명하는 동시에 azure.yaml 배포 되는 방법을 설명하는 것입니다.

연결, 툴박스, 스킬, 루틴처럼 Foundry 프로젝트 자체에 속한 리소스는 agent.yaml에 선언하는 대신 직접 azd ai 명령을 통해 관리됩니다.

변수 치환

에이전트 프로젝트 파일에 다음과 같은 두 가지 변수 구문이 표시됩니다.

• ${VAR_NAME} 는 azd 환경 변수 자리 표시자입니다. 배포 시점에 .azure/<env>/.env에서 확인되므로 개발, 스테이징, 프로덕션과 같은 환경 전반에서 동일한 agent.yaml를 사용할 수 있습니다.
• {{ parameter }} 는 매니페스트 템플릿 매개 변수입니다. 템플릿이 구체적인 프로젝트로 스캐폴딩될 때 azd ai agent init 중에 확인됩니다.

CLI가 실행되는 위치

azd ai 명령은 azd 프로젝트 디렉터리 내부와 외부 모두에서 작동합니다.

• azd 프로젝트 내에서는 명령어가 활성 azd 환경에서 Foundry 프로젝트 엔드포인트를 확인해 결정합니다.
• azd 프로젝트 외부에서는 azd ai project set <endpoint>로 활성 컨텍스트를 한 번 설정하거나, 개별 리소스 명령(connection, toolbox, skill 또는 routine)에 --project-endpoint를 지정합니다. 대체 수단으로, azd ai는 FOUNDRY_PROJECT_ENDPOINT 환경 변수를 읽습니다.
• 프로젝트 내 환경은 항상 전역 컨텍스트보다 우선하므로 디렉터리를 프로젝트로 변경하면 해당 프로젝트의 엔드포인트에서 CLI가 대상을 다시 지정합니다.

Protocols

프로토콜은 Foundry와 에이전트 컨테이너 간의 HTTP 계약을 정의합니다. 에이전트는 포트 8088에서 수신 대기하고 프로토콜에 관계없이 상태 프로브를 제공합니다.

전체 사양은 호스팅된 에이전트 런타임 계약을 참조하세요.

세션 및 대화

세션은 .로 식별됩니다 session_id. 실행할 azd ai agent invoke때 Foundry는 기본적으로 마지막 호출에서 세션을 다시 사용합니다. 새로 시작하거나 --new-session 특정 세션을 대상으로 지정하는 데 사용합니다--session-id <id>.

Foundry 프로젝트의 리소스

Foundry 프로젝트는 에이전트 이상을 호스트합니다. 또한 에이전트가 런타임에 참조하는 공유 리소스도 보유합니다. CLI는 전용 명령 그룹을 통해 각각을 관리합니다.

이러한 리소스는 동일한 프로젝트의 개발자와 에이전트 간에 공유됩니다. 각 명령 그룹은 표준create, , updatedeleteshow및 list 동사를 노출합니다.

에이전트 평가 및 개선

에이전트가 실행된 후 두 개의 관련 워크플로를 통해 품질을 측정하고 개선하는 데 도움이 됩니다.

• 평가는 데이터 세트에 대해 에이전트를 실행하고, 하나 이상의 평가자를 사용하여 응답의 점수를 매기고, 집계 품질 신호를 보고합니다. azd ai agent eval로 관리합니다.
• 최적화는 에이전트의 프롬프트를 반복적으로 다시 작성하여 평가 신호를 해제합니다. 평가를 목표 함수로 사용하고 검토하고 수락하는 후보 프롬프트를 생성합니다. azd ai agent optimize로 관리합니다.

자세한 내용은 azd CLI 및 Optimize 에이전트 프롬프트를 사용하여 에이전트 평가 실행을 참조하세요.

배포 수명 주기

전체 개발자 루프는 짧은 명령 시퀀스로 압축됩니다. 한 번 스캐폴드한 다음 프로젝트가 커지면 직접 명령을 사용합니다.

# 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

관련 콘텐츠

• 빠른 시작: 첫 번째 호스팅 에이전트 배포
• 호스팅 에이전트란?
• 호스팅 에이전트 런타임 계약
• 에이전트 개발 수명 주기