중요합니다
이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며, 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.
사용자 지정 코드 인터프리터를 사용하면 에이전트에서 생성된 Python 코드의 런타임 환경을 완전히 제어할 수 있습니다. 사용자 지정 Python 패키지, 컴퓨팅 리소스 및 Azure Container Apps 환경 설정을 구성할 수 있습니다. 코드 인터프리터 컨테이너는 MCP(모델 컨텍스트 프로토콜) 서버를 노출합니다.
에이전트용 기본 제공 코드 인터프리터 도구 가 요구 사항을 충족하지 않는 경우(예: 특정 Python 패키지, 사용자 지정 컨테이너 이미지 또는 전용 컴퓨팅 리소스가 필요한 경우) 사용자 지정 코드 인터프리터를 사용합니다.
MCP 및 에이전트가 MCP 도구에 연결하는 방법에 대한 자세한 내용은 모델 컨텍스트 프로토콜 서버에 연결(미리 보기)을 참조하세요.
사용량 지원
이 문서에서는 Azure CLI 및 실행 가능한 샘플 프로젝트를 사용합니다.
✔️ (GA)는 일반 가용성을 ✔️ 나타내고(미리 보기)는 공개 미리 보기를 나타내고 대시(-)는 기능을 사용할 수 없음을 나타냅니다.
| Microsoft Foundry 지원 | Python SDK | C# SDK | JavaScript SDK | Java SDK | REST API | 기본 에이전트 설정 | 표준 에이전트 설정 |
|---|---|---|---|---|---|---|---|
| ✔️ | ✔️ (미리 보기) | - | - | - | ✔️ (GA) | - | ✔️ |
에이전트 도구에 대한 최신 SDK 및 API 지원은 Microsoft Foundry 에이전트 서비스의 도구 사용에 대한 모범 사례를 참조하세요.
SDK 제한 사항
사용자 지정 코드 인터프리터는 현재 Python SDK 및 REST API를 통해서만 지원됩니다. C#, JavaScript/TypeScript 및 Java SDK는 아직 이 기능을 지원하지 않습니다. 이러한 언어를 사용하는 사용자 지정 코드 인터프리터 기능이 필요한 경우 REST API를 직접 사용합니다.
필수 조건
- Azure CLI 버전 2.60.0 이상.
- uv를 사용하여 Python 패키지 관리를 더 빠르게 할 수 있습니다. (선택 사항)
- 다음 역할 할당이 있는 Azure 구독 및 리소스 그룹:
- Azure AI Projects SDK(시험판). 설치에 대한 빠른 시작을 참조하세요.
환경 변수
인프라를 프로비전한 후 다음 환경 변수를 설정합니다.
| 변수 | Description |
|---|---|
FOUNDRY_PROJECT_ENDPOINT |
Foundry 프로젝트 엔드포인트 URL입니다. |
FOUNDRY_MODEL_DEPLOYMENT_NAME |
모델 배포 이름(예: gpt-4o). |
MCP_SERVER_URL |
Azure Container Apps 배포의 MCP 서버 엔드포인트입니다. |
MCP_PROJECT_CONNECTION_ID |
사용자 지정 코드 인터프리터에 대한 프로젝트 연결 ID입니다. |
시작하기 전 주의 사항:
이 절차는 Azure Container Apps 리소스를 포함하여 Azure 인프라를 프로비전합니다. 배포하기 전에 조직의 Azure 비용 및 거버넌스 요구 사항을 검토합니다.
사용자 지정 코드 인터프리터를 사용하여 에이전트 만들기
다음 단계에서는 사용자 지정 코드 인터프리터 MCP 서버를 사용하는 에이전트를 만드는 방법을 보여줍니다.
미리 보기 기능 등록
Azure Container Apps 동적 세션에 대한 MCP 서버 기능을 등록합니다.
az feature register --namespace Microsoft.App --name SessionPoolsSupportMCP
az provider register -n Microsoft.App
샘플 코드 가져오기
GitHub 리포지토리에서 샘플 코드를 복제하고 터미널의 samples/python/prompt-agents/code-interpreter-custom 폴더로 이동합니다.
인프라 구축
인프라를 프로비전하려면 Azure CLI(az)를 사용하여 다음 명령을 실행합니다.
az deployment group create \
--name custom-code-interpreter \
--subscription <your_subscription> \
--resource-group <your_resource_group> \
--template-file ./infra.bicep
비고
배포는 요청하는 대기 인스턴스 수에 따라 최대 1시간이 걸릴 수 있습니다. 동적 세션 풀 할당은 가장 긴 단계입니다.
에이전트 구성 및 실행
.env.sample 리포지토리에서 파일을 복사하여 .env 배포 출력의 값을 채웁다. 이러한 값은 Azure Portal의 리소스 그룹 아래에서 찾을 수 있습니다.
uv sync 또는 pip install를 사용하여 Python 종속성을 설치합니다. 마지막으로 ./main.py을(를) 실행합니다.
빠른 확인
전체 샘플을 실행하기 전에 인증 및 프로젝트 연결을 확인합니다.
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from dotenv import load_dotenv
load_dotenv()
with (
DefaultAzureCredential() as credential,
AIProjectClient(endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"], credential=credential) as project_client,
):
print("Connected to project.")
# List connections to verify MCP connection exists
connections = project_client.connections.list()
for conn in connections:
print(f" Connection: {conn.name} (type: {conn.type})")
이 코드가 오류 없이 실행되면 자격 증명 및 프로젝트 엔드포인트가 올바르게 구성됩니다.
코드 예제
다음 Python 샘플에서는 사용자 지정 코드 인터프리터 MCP 도구를 사용하여 에이전트를 만드는 방법을 보여줍니다.
import os
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, MCPTool
load_dotenv()
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
with (
DefaultAzureCredential() as credential,
AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
project_client.get_openai_client() as openai_client,
):
# Configure the custom code interpreter MCP tool
custom_code_interpreter = MCPTool(
server_label="custom-code-interpreter",
server_url=os.environ["MCP_SERVER_URL"],
project_connection_id=os.environ.get("MCP_PROJECT_CONNECTION_ID"),
)
agent = project_client.agents.create_version(
agent_name="CustomCodeInterpreterAgent",
definition=PromptAgentDefinition(
model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
instructions="You are a helpful assistant that can run Python code to analyze data and solve problems.",
tools=[custom_code_interpreter],
),
description="Agent with custom code interpreter for data analysis.",
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")
# Test the agent with a simple calculation
response = openai_client.responses.create(
input="Calculate the factorial of 10 using Python.",
extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(f"Response: {response.output_text}")
# Clean up
project_client.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
print("Agent deleted")
예상 출력
샘플을 실행하면 다음과 유사한 출력이 표시됩니다.
Agent created (id: agent-xxxxxxxxxxxx, name: CustomCodeInterpreterAgent, version: 1)
Response: The factorial of 10 is 3,628,800. I calculated this using Python's math.factorial() function.
Agent deleted
설치 확인
인프라를 프로비전하고 샘플을 실행한 후:
- Azure 배포가 성공적으로 완료되었는지 확인합니다.
- 파일
.env의 값을 사용하여 샘플이 연결되는지 확인합니다. - Microsoft Foundry에서 에이전트가 추적을 사용하여 도구를 호출했는지 확인합니다. 자세한 내용은 Microsoft Foundry 에이전트 서비스의 도구 사용에 대한 모범 사례를 참조하세요.
문제 해결
| 문제 | 가능한 원인 | 해결 방법 |
|---|---|---|
| 기능 등록이 아직 보류 중입니다. | 명령은 az feature register 상태를 반환합니다 Registering . |
등록이 완료되기를 기다립니다(15~30분이 걸릴 수 있음). 를 사용하여 상태를 확인합니다 az feature show --namespace Microsoft.App --name SessionPoolsSupportMCP. 그런 다음 다시 실행 az provider register -n Microsoft.App 합니다. |
| 권한 오류로 배포 실패 | 필수 역할 할당이 누락되었습니다. | 구독 또는 리소스 그룹에 Azure AI 소유자 및 Container Apps ManagedEnvironment 기여자 역할이 있는지 확인합니다. |
| 지역 오류로 배포 실패 | 선택한 지역은 Azure Container Apps 동적 세션을 지원하지 않습니다. | 다른 지역을 사용해 보세요. 지원되는 지역에 대해서는 Azure Container Apps 지역을 참조하세요. |
| 에이전트가 도구를 호출하지 않음 | MCP 연결이 올바르게 구성되지 않았거나 에이전트 지침에 따라 도구 사용을 묻는 메시지가 표시되지 않습니다. | Microsoft Foundry에서 추적을 사용하여 도구 호출을 확인합니다. 배포된 MCP_SERVER_URL Container Apps 엔드포인트와 일치하는지 확인합니다.
모범 사례를 참조하세요. |
| MCP 서버 연결 시간 제한 | Container Apps 세션 풀이 실행되고 있지 않거나 대기 인스턴스가 없습니다. | Azure Portal에서 세션 풀 상태를 확인합니다. 필요한 경우 Bicep 템플릿에서 standbyInstanceCount를 증가시킵니다. |
| 컨테이너에서 코드 실행 실패 | 사용자 지정 컨테이너에 Python 패키지가 없습니다. | 필요한 패키지를 포함하도록 컨테이너 이미지를 업데이트합니다. 컨테이너를 다시 빌드하고 다시 배포합니다. |
| MCP 서버에 연결하는 인증 오류 | 프로젝트 연결 자격 증명이 잘못되었거나 만료되었습니다. | 연결 자격 증명을 다시 생성하고 파일을 업데이트합니다 .env . 형식을 확인합니다 MCP_PROJECT_CONNECTION_ID . |
제한점
API는 파일 입력 또는 출력 또는 파일 저장소 사용을 직접 지원하지 않습니다. 데이터를 가져오기 위해 작은 파일에 대한 데이터 URL 및 큰 파일에 대한 Azure Blob Service SAS(공유 액세스 서명) URL과 같은 URL을 사용해야 합니다.
보안
SAS URL을 사용하여 런타임 내/외부로 데이터를 전달하는 경우:
- 수명이 짧은 SAS 토큰을 사용합니다.
- SAS URL을 기록하거나 소스 제어에 저장하지 마세요.
- 필요한 최소 권한(예: 읽기 전용 또는 쓰기 전용)으로 권한 범위를 지정합니다.
정리
프로비전된 리소스에 대한 청구를 중지하려면 샘플 배포에서 만든 리소스를 삭제합니다. 이 문서에 전용 리소스 그룹을 사용한 경우 리소스 그룹을 삭제합니다.