Important
이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.
이 빠른 시작에서는 하나의 관리형 엔드포인트 뒤에 두 개의 도구를 결합하는 도구 상자를 빌드합니다.
- 실시간 공용 웹 결과의 응답을 근거로 하는 웹 검색입니다.
- 공식 Microsoft 설명서의 응답을 근거로 하는 Microsoft Learn MCP 서버입니다. 인증이 필요하지 않은 퍼블릭 엔드포인트입니다.
그런 다음 Python 작성된 호스트된 에이전트에서 도구 상자를 사용합니다. 도구 상자는 하나의 MCP 엔드포인트를 노출하므로 에이전트는 단일 URL에 연결하고 런타임에 모든 도구를 검색합니다. 나중에 에이전트 코드를 변경하지 않고 도구를 변경할 수 있습니다.
사전 요구 사항
이 빠른 시작은 호스트 에이전트 도구 체인을 기반으로 합니다. 먼저 호스트된 에이전트 빠른 시작에서 필수 구성 요소를 완료합니다. 이 빠른 시작에서는 Azure 구독, 프로젝트 역할, Python, Azure 개발자 CLI(azd) 및 microsoft.foundry 확장을 다룹니다.
Python SDK 경로의 경우 Azure 개발자 CLI 또는 VS Code 워크플로 대신 이 문서의 뒷부분에 있는 Python 섹션을 사용합니다. 해당 경로는 도구 상자를 project_client.toolboxes.create_version(...)만든 다음 호스트 에이전트 코드를 새 버전으로 업로드하고 이름으로 해당 도구 상자를 가리킵니다.
이 경로에 사용되는 Python 패키지를 설치합니다.
pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv
배포된 채팅 가능 모델을 사용하는 기존 Foundry 프로젝트가 필요합니다. 이 빠른 시작의 Python SDK 경로는 도구 상자와 호스트 에이전트 버전을 만들지만 새 Foundry 프로젝트를 스캐폴드하거나 모델 배포를 만들지는 않습니다.
또한 Azure에 로그인된 상태에서 Microsoft Foundry Toolkit 확장 프로그램이 설치된 Visual Studio Code도 필요합니다.
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/azure.yaml" --src src/toolbox-agent
프롬프트에 따라 프로젝트 및 기존 모델 배포를 선택합니다.
컨테이너 리소스 할당을 선택하라는 메시지가 표시되면 1코어, 2Gi 메모리를 선택합니다. 에이전트의 컨테이너 이미지에는 기본 계층 이상이 필요합니다.
--src 플래그는 에이전트를 src/toolbox-agent로 생성합니다.
메모
에이전트 매니페스트(agent.manifest.yaml) 및 독립 실행형 에이전트 정의(agent.yaml)는 더 이상 사용되지 않습니다. Foundry azd 확장(azure.ai.agents 1.0.0-beta.1)을 기준으로 호스트된 모든 에이전트 구성은 단일 azure.yaml에 있습니다.
호스팅된 에이전트용 azure.yaml 작성은 여기에서 참조하세요.
2단계: 도구 상자 만들기
도구 상자를 만든 다음 반환하는 MCP 엔드포인트를 복사합니다. 이후 단계에서 해당 엔드포인트를 환경 변수로 설정합니다.
샘플의 azure.yaml는 도구 상자를 azure.ai.toolbox 서비스로 정의하고, uses:를 사용해 호스팅된 에이전트 서비스에 연결합니다. 도구 상자 구성을 변경하는 경우 azure.yaml가 아니라 src/toolbox-agent/agent.yaml에서 도구 상자 서비스를 편집하세요.
먼저 초기화 중에 선택한 Foundry 프로젝트에서 도구 상자 명령을 가리킵니다. 초기화 과정에서 이미 azd 환경에 저장된 엔드포인트를 재사용하세요.
azd env set FOUNDRY_PROJECT_ENDPOINT "$(azd env get-value FOUNDRY_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://learn.microsoft.com/api/mcp을 입력합니다. 서버가 공용이므로 인증이 필요하지 않습니다.게시를 선택합니다. 게시하면 도구 상자의 첫 번째 버전이 만들어집니다.
도구 상자의 MCP 엔드포인트를 복사합니다. 다음 명령을 실행하고 출력에서
endpoint값을 복사합니다. 다음 단계에서 환경 변수로TOOLBOX_ENDPOINT설정합니다.azd ai toolbox show my-toolbox --output json
3단계: Azure 리소스 프로비전
에이전트는 TOOLBOX_ENDPOINT 환경 변수에서 도구 상자의 MCP 엔드포인트를 읽고, azure.yaml는 사용자의 azd 환경에서 이를 해석합니다. 다음 단계에서 해당 값을 설정합니다. 에이전트의 Azure 리소스를 프로비전합니다.
azd provision
4단계: 에이전트를 로컬로 실행
.env의src/toolbox-agent파일에서 이러한 값을 설정하여 로컬 에이전트가 도구 상자를 가리키도록 하세요. 2단계에서 복사한 엔드포인트를 붙여넣습니다.FOUNDRY_MODEL_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 환경에 저장하세요. azure.yaml는 배포 시 해당 엔드포인트를 확인합니다. 그런 다음 에이전트 컨테이너를 빌드하고 배포합니다.
azd env set TOOLBOX_ENDPOINT "<versioned-endpoint-from-step-2>"
azd deploy
명령이 완료되면 출력에 에이전트 플레이그라운드 및 에이전트 엔드포인트에 대한 링크가 표시됩니다. 배포된 에이전트를 호출합니다.
azd ai agent invoke "What's new in Microsoft Foundry? Use the Microsoft Learn documentation."
Python SDK 경로
도구 상자를 만들고 Azure 개발자 CLI 또는 VS Code 흐름 대신 Python SDK를 사용하여 호스트 에이전트 버전을 배포하려면 다음 단계를 사용합니다.
1. Foundry 프로젝트 만들기 또는 선택
- Foundry 포털을 열고 Foundry 프로젝트를 만들거나 기존 프로젝트를 선택합니다.
- 프로젝트에서 채팅 가능 모델(예:
gpt-5.4-mini.)을 배포합니다. - 개요에서 프로젝트 엔드포인트를 복사하고 빌드>배포에서 배포 이름을 복사합니다.
2. 도구상자 호스팅된 에이전트 샘플 다운로드
Foundry 샘플 리포지토리를 복제합니다.
git clone https://github.com/microsoft-foundry/foundry-samples.git
배포 스크립트에 대한 작업 폴더를 만듭니다. 해당 폴더에서 다음 값을 가진 .env 파일을 만듭니다.
FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=toolbox-agent
TOOLBOX_NAME=my-toolbox
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/src/agent-framework-agent-with-foundry-toolbox-responses>
3단계: Python 사용하여 도구 상자 만들기
다음과 같은 작업 폴더create_toolbox.py에 이름이 지정된 .env 파일을 만듭니다.
import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPToolboxTool, WebSearchToolboxTool
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv
load_dotenv()
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
toolbox_name = os.environ["TOOLBOX_NAME"]
with (
DefaultAzureCredential() as credential,
AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
created = project_client.toolboxes.create_version(
name=toolbox_name,
description="Toolbox with web search and Microsoft Learn MCP.",
tools=[
WebSearchToolboxTool(
name="web_search",
search_context_size="medium",
),
MCPToolboxTool(
server_label="mslearn",
server_url="https://learn.microsoft.com/api/mcp",
require_approval="never",
),
],
)
print(f"Created toolbox version {created.version} for {created.name}")
mcp_endpoint = (
f"{endpoint}/toolboxes/{created.name}/versions/"
f"{created.version}/mcp?api-version=v1"
)
print(f"Toolbox version: {created.version}")
print(f"Toolbox MCP endpoint: {mcp_endpoint}")
스크립트를 실행합니다.
python create_toolbox.py
샘플 호스트형 에이전트는 도구 상자를 TOOLBOX_ENDPOINT에서 또는 FOUNDRY_PROJECT_ENDPOINT와 TOOLBOX_NAME에서 찾을 수 있습니다. 이 경로는 TOOLBOX_NAME를 사용하므로 .env에 버전이 지정된 엔드포인트를 저장할 필요가 없습니다.
4. Python 사용하여 호스트된 에이전트 배포
다음과 같은 작업 폴더deploy_toolbox_agent.py에 이름이 지정된 .env 파일을 만듭니다.
import os
import tempfile
import time
import zipfile
from pathlib import Path
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
AgentEndpointConfig,
CodeConfiguration,
CodeDependencyResolution,
FixedRatioVersionSelectionRule,
HostedAgentDefinition,
ProtocolConfiguration,
ProtocolVersionRecord,
ResponsesProtocolConfiguration,
VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv
load_dotenv()
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "toolbox-agent")
toolbox_name = os.environ["TOOLBOX_NAME"]
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()
def create_code_zip(source_dir: Path) -> Path:
zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
excluded = {".git", ".venv", "__pycache__", ".env"}
with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
for path in source_dir.rglob("*"):
if not path.is_file():
continue
if any(part in excluded for part in path.parts):
continue
zip_file.write(path, path.relative_to(source_dir))
return zip_path
def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
for attempt in range(60):
time.sleep(10)
details = project_client.agents.get_version(
agent_name=agent_name,
agent_version=version,
)
status = details["status"]
print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")
if status == "active":
return
if status == "failed":
raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")
raise RuntimeError("Timed out waiting for the hosted agent version to become active.")
code_zip_path = create_code_zip(sample_path)
with (
code_zip_path.open("rb") as code_stream,
DefaultAzureCredential() as credential,
AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
original_agent_endpoint = None
created = None
try:
created = project_client.agents.create_version_from_code(
agent_name=agent_name,
description="Hosted agent with Foundry Toolbox integration.",
definition=HostedAgentDefinition(
cpu="1",
memory="2Gi",
code_configuration=CodeConfiguration(
runtime="python_3_13",
entry_point=["python", "main.py"],
dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
),
environment_variables={
"FOUNDRY_PROJECT_ENDPOINT": endpoint,
"AZURE_AI_MODEL_DEPLOYMENT_NAME": model_name,
"TOOLBOX_NAME": toolbox_name,
},
protocol_versions=[
ProtocolVersionRecord(protocol="responses", version="2.0.0")
],
),
code=code_stream,
)
print(f"Created hosted agent version {created.version}")
wait_for_active_version(project_client, created.version)
original_agent_endpoint = project_client.agents.get(
agent_name=agent_name
).agent_endpoint
project_client.agents.update_details(
agent_name=agent_name,
agent_endpoint=AgentEndpointConfig(
version_selector=VersionSelector(
version_selection_rules=[
FixedRatioVersionSelectionRule(
agent_version=created.version,
traffic_percentage=100,
),
]
),
protocol_configuration=ProtocolConfiguration(
responses=ResponsesProtocolConfiguration()
),
),
)
with project_client.get_openai_client(agent_name=agent_name) as openai_client:
response = openai_client.responses.create(
input=(
"How do I create a hosted agent in Microsoft Foundry? "
"Use the Microsoft Learn documentation."
),
)
if response.status != "completed":
raise RuntimeError(f"Agent invocation failed: {response.error}")
print(response.output_text)
finally:
if original_agent_endpoint is not None:
project_client.agents.update_details(
agent_name=agent_name,
agent_endpoint=original_agent_endpoint,
)
if created is not None:
project_client.agents.delete_version(
agent_name=agent_name,
agent_version=created.version,
force=True,
)
스크립트를 실행합니다.
python deploy_toolbox_agent.py
이 스크립트는 도구 상자 샘플을 새 호스트 에이전트 버전으로 업로드하고, 해당 버전에서 호스트된 에이전트를 일시적으로 가리키고, Microsoft Learn 질문으로 호출하고, 완료되면 이전 엔드포인트 구성을 복원합니다.
5. 툴박스 기반 응답 확인
도구 상자를 올바르게 구성하면 호스트된 에이전트가 도구 상자 도구를 검색하고 Microsoft Learn 설명서를 사용하여 응답했음을 보여 줍니다.
자원을 정리하세요
완료되면 리소스를 삭제하여 요금 발생을 중지합니다.
도구 상자를 삭제합니다.
azd ai toolbox delete my-toolbox --force
도구 상자를 삭제하면 해당 엔드포인트의 작동이 중지됩니다.
src/toolbox-agent/.env에서 이를 제거하고 azd 환경에서 이를 지우세요.
azd env set TOOLBOX_ENDPOINT ""
에이전트 및 해당 Azure 리소스를 삭제합니다.
Warning
현재 azd 환경에서 Foundry 프로젝트를 만든 경우 프로젝트의 azd down 리소스 그룹 및 해당 프로젝트의 모든 항목을 영구적으로 삭제합니다. 초기화 중에 기존 프로젝트를 선택한 경우 프로젝트, azd down 해당 리소스 그룹, 호스트된 에이전트 및 기타 빠른 시작 리소스를 제자리에 둡니다. 기존 프로젝트에서 더 이상 필요하지 않은 리소스를 삭제하려면 별도로 삭제합니다.
azd down
이름으로 도구 상자를 삭제합니다.
import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv
load_dotenv()
with (
DefaultAzureCredential() as credential,
AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=credential,
) as project_client,
):
project_client.toolboxes.delete(name=os.environ["TOOLBOX_NAME"])
이 빠른 시작에 대한 전용 리소스 그룹 또는 프로젝트를 만든 경우 도구 상자, 채팅 배포 또는 호스트된 에이전트가 더 이상 필요하지 않은 후 Azure 포털에서 삭제합니다.
Troubleshooting
| Issue | 해결 방법 |
|---|---|
tools/list는 Microsoft Learn 도구를 반환하지 않습니다. |
mslearn에서 toolbox.yaml 도구가 https://learn.microsoft.com/api/mcp를 가리키는지 확인합니다. |
에이전트가 시작되지만 TOOLBOX_ENDPOINT is set but empty를 표시하거나 사용 가능한 도구가 없습니다 |
로컬에서 실행할 때는 TOOLBOX_ENDPOINT의 2단계에 있는 버전 지정 엔드포인트로 .env를 설정하고, 배포하기 전에 azd env set TOOLBOX_ENDPOINT "<endpoint>"를 실행하세요. |
| 권한 부여 오류로 도구 상자 엔드포인트에 대한 호출이 실패함 | 모든 요청에 https://ai.azure.com/.default 범위로 지정된 Entra 토큰이 포함되어 있는지 확인합니다. 샘플이 이를 대신 처리해 줍니다. |
Connection refused 로컬 실행 시 |
다른 프로세스가 포트 8088를 사용하고 있지 않은지 확인합니다. |
배운 내용
이 빠른 시작에서 당신은 다음을 수행합니다.
- 웹 검색과 Microsoft Learn MCP 서버를 하나의 엔드포인트 뒤에 결합하는 도구 상자를 빌드했습니다.
- Azure Developer CLI 또는 Python SDK를 사용하여 모델 컨텍스트 프로토콜을 통해 연결되는 Python 호스팅 에이전트에서 도구 상자를 사용했습니다.
- 에이전트를 로컬로 실행하거나 원격으로 유효성을 검사하여 Foundry 에이전트 서비스에 배포했습니다.