Important
이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.
이 빠른 시작에서는 하나의 관리형 엔드포인트 뒤에 두 개의 도구를 결합하는 도구 상자를 빌드합니다.
- 실시간 공용 웹 결과의 응답을 근거로 하는 웹 검색입니다.
- 공식 Microsoft 설명서의 응답을 근거로 하는 Microsoft Learn MCP 서버입니다. 인증이 필요하지 않은 퍼블릭 엔드포인트입니다.
그런 다음 Python 작성된 호스트된 에이전트에서 도구 상자를 사용합니다. 도구 상자는 하나의 MCP 엔드포인트를 노출하므로 에이전트는 단일 URL에 연결하고 런타임에 모든 도구를 검색합니다. 나중에 에이전트 코드를 변경하지 않고 도구를 변경할 수 있습니다.
사전 요구 사항
이 빠른 시작은 호스트 에이전트 도구 체인을 기반으로 합니다. 먼저 호스트된 에이전트 빠른 시작에서 필수 구성 요소를 완료합니다. 이 빠른 시작에서는 Azure 구독, 프로젝트 역할, Python, Azure 개발자 CLI(azd) 및 microsoft.foundry 확장을 다룹니다.
VS Code 경로를 사용하는 경우, Azure에 로그인된 Visual Studio Code와 Microsoft Foundry Toolkit 확장이 추가로 필요합니다.
1단계: 호스트된 에이전트 초기화
MCP를 통해 도구 상자에 연결하고 해당 도구를 모델에 노출하는 Foundry 도구 상자 샘플에서 호스트된 에이전트를 초기화합니다. 다음 단계에서 도구 상자(my-toolbox)를 만들고 해당 엔드포인트에서 에이전트를 가리킵니다. 빈 디렉터리에서 이러한 명령을 실행합니다.
mkdir my-toolbox-agent && cd my-toolbox-agent
azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/agent.manifest.yaml" --src src/toolbox-agent
프롬프트에 따라 프로젝트 및 기존 모델 배포를 선택합니다.
컨테이너 리소스 할당을 선택하라는 메시지가 표시되면 1코어, 2Gi 메모리를 선택합니다. 에이전트의 컨테이너 이미지에는 기본 계층 이상이 필요합니다.
--src 플래그는 에이전트를 src/toolbox-agent로 생성합니다.
2단계: 도구 상자 만들기
도구 상자를 만든 다음 반환하는 MCP 엔드포인트를 복사합니다. 이후 단계에서 해당 엔드포인트를 환경 변수로 설정합니다.
먼저 초기화 중에 선택한 Foundry 프로젝트에서 도구 상자 명령을 가리킵니다. 초기화 과정에서 이미 azd 환경에 저장된 엔드포인트를 재사용하세요.
azd env set FOUNDRY_PROJECT_ENDPOINT "$(azd env get-value AZURE_AI_PROJECT_ENDPOINT)"
샘플에는 하나의 엔드포인트 뒤에 있는 두 도구를 모두 정의하는 toolbox.yaml 내의 src/toolbox-agent가 포함되어 있습니다. 해당 파일에서 도구 상자를 만듭니다.
azd ai toolbox create my-toolbox --from-file ./src/toolbox-agent/toolbox.yaml
첫 번째 버전은 자동으로 기본 버전이 됩니다. 이 명령은 도구 상자의 버전이 지정된 MCP 엔드포인트를 출력합니다. 출력에서 Endpoint 값을 복사합니다. 다음 단계에서 환경 변수로 TOOLBOX_ENDPOINT 설정합니다. 이것은 다음과 같이 보입니다.
https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/my-toolbox/versions/1/mcp?api-version=v1
Visual Studio Code 열고 작업 모음에서 Foundry 도구 키트를 선택합니다.
메시지가 표시되면 Azure 계정에 로그인합니다.
내 리소스 아래에서 프로젝트를 확장한 다음 도구를 확장합니다.
도구 보기에서 + 도구 상자 추가 아이콘을 선택합니다.
도구 상자 이름(
my-toolbox)과 설명을 입력합니다.웹 검색을 선택합니다.
+ 도구 추가를 선택하고, 원격 MCP 서버를 추가하도록 선택하고, 서버 URL
https://dotnet.territoriali.olinfo.it/api/mcp을 입력합니다. 서버가 공용이므로 인증이 필요하지 않습니다.게시를 선택합니다. 게시하면 도구 상자의 첫 번째 버전이 만들어집니다.
도구 상자의 MCP 엔드포인트를 복사합니다. 다음 명령을 실행하고 출력에서
endpoint값을 복사합니다. 다음 단계에서 환경 변수로TOOLBOX_ENDPOINT설정합니다.azd ai toolbox show my-toolbox --output json
3단계: Azure 리소스 프로비전
에이전트는 TOOLBOX_ENDPOINT 환경 변수에서 도구 상자의 MCP 엔드포인트를 읽고, src/toolbox-agent/agent.yaml는 사용자의 azd 환경에서 이를 해석합니다. 다음 단계에서 해당 값을 설정합니다. 에이전트의 Azure 리소스를 프로비전합니다.
azd provision
4단계: 에이전트를 로컬로 실행
.env의src/toolbox-agent파일에서 이러한 값을 설정하여 로컬 에이전트가 도구 상자를 가리키도록 하세요. 2단계에서 복사한 엔드포인트를 붙여넣습니다.AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name> TOOLBOX_ENDPOINT=<versioned-endpoint-from-step-2>azd ai agent run는FOUNDRY_PROJECT_ENDPOINT를 삽입하고 로컬 실행 시.env파일을 읽습니다. 샘플은 툴박스 연결, 헤더 및 인증을 대신 처리해 줍니다.에이전트를 시작합니다.
azd ai agent run이 명령은 가상 환경을 만들고, 종속성을 설치하고, 에이전트를 제공합니다
http://localhost:8088. 미리 보기 패키지는 설치 중에 pip 경고를 생성할 수 있습니다. 이러한 경고는 차단되지 않습니다.별도의 터미널에서 도구를 연습하는 프롬프트를 보냅니다.
azd ai agent invoke --local "Find the latest release notes for the Azure CLI on the web." azd ai agent invoke --local "How do I create a hosted agent in Microsoft Foundry? Use the Microsoft Learn documentation."
5단계: Foundry 에이전트 서비스에 배포
2단계에서 복사한 엔드포인트를 azd 환경에 저장하세요. agent.yaml는 배포 시 해당 엔드포인트를 확인합니다. 그런 다음 에이전트 컨테이너를 빌드하고 배포합니다.
azd env set TOOLBOX_ENDPOINT "<versioned-endpoint-from-step-2>"
azd deploy
명령이 완료되면 출력에 에이전트 플레이그라운드 및 에이전트 엔드포인트에 대한 링크가 표시됩니다. 배포된 에이전트를 호출합니다.
azd ai agent invoke "What's new in Azure AI Foundry? Use the Microsoft Learn documentation."
자원을 정리하세요
완료되면 리소스를 삭제하여 요금 발생을 중지합니다.
도구 상자를 삭제합니다.
azd ai toolbox delete my-toolbox --force
도구 상자를 삭제하면 해당 엔드포인트의 작동이 중지됩니다.
src/toolbox-agent/.env에서 이를 제거하고 azd 환경에서 이를 지우세요.
azd env set TOOLBOX_ENDPOINT ""
에이전트 및 해당 Azure 리소스를 삭제합니다.
Warning
azd down 는 Foundry 프로젝트, 모델 배포, Container Registry 및 호스트된 에이전트를 포함하여 리소스 그룹의 모든 리소스를 영구적으로 삭제합니다. 다른 리소스가 포함된 리소스 그룹으로 프로비전한 경우 해당 리소스도 삭제됩니다.
azd down
Troubleshooting
| Issue | 해결 방법 |
|---|---|
tools/list는 Microsoft Learn 도구를 반환하지 않습니다. |
mslearn에서 toolbox.yaml 도구가 https://dotnet.territoriali.olinfo.it/api/mcp를 가리키는지 확인합니다. |
에이전트가 시작되지만 TOOLBOX_ENDPOINT is set but empty를 표시하거나 사용 가능한 도구가 없습니다 |
로컬에서 실행할 때는 TOOLBOX_ENDPOINT의 2단계에 있는 버전 지정 엔드포인트로 .env를 설정하고, 배포하기 전에 azd env set TOOLBOX_ENDPOINT "<endpoint>"를 실행하세요. |
| 권한 부여 또는 헤더 오류로 도구 상자 엔드포인트에 대한 호출이 실패함 | 모든 요청에 Foundry-Features: Toolboxes=V1Preview 헤더와 https://ai.azure.com/.default 범위로 지정된 Entra 토큰이 포함되어 있는지 확인합니다. 샘플이 이를 대신 처리해 줍니다. |
Connection refused 로컬 실행 시 |
다른 프로세스가 포트 8088를 사용하고 있지 않은지 확인합니다. |
배운 내용
이 빠른 시작에서 당신은 다음을 수행합니다.
- 웹 검색과 Microsoft Learn MCP 서버를 하나의 엔드포인트 뒤에 결합하는 도구 상자를 빌드했습니다.
- 모델 컨텍스트 프로토콜을 통해 연결되는 Python 호스팅 에이전트의 툴박스를 사용했습니다.
- 에이전트를 로컬로 실행하고 Foundry 에이전트 서비스에 배포했습니다.