langchain-azure-ai 패키지를 사용하여 Foundry 도구 상자에서 LangChain 및 LangGraph 에이전트로 도구와 기술을 로드합니다. Foundry 도구 상자는 단일 MCP(모델 컨텍스트 프로토콜) 엔드포인트 뒤에 구성된 여러 도구를 집계하는 관리형 다중 MCP 서버입니다.
도구를 로드하고, 승인이 필요한 도구를 식별하고, 도구 상자 기술을 리소스로 로드하고, 심층 에이전트를 위한 기술을 준비하는 방법을 알아봅니다.
사전 요구 사항
- Azure 구독입니다. 체험 계정 만들기
- 파운드리 프로젝트.
- 프로젝트에 배포된 채팅 모델(예:
gpt-4.1)입니다. - Foundry 프로젝트에 구성된 도구 상자입니다. 해당 이름을 적어 둡다.
- Python 3.10 이상.
- Azure CLI 로그인(
az login)하므로DefaultAzureCredential인증할 수 있습니다.
필요한 패키지를 설치합니다.
pip install -U langchain-azure-ai langchain-mcp-adapters httpx azure-identity
도구 상자 통합에는 다음이 필요합니다.langchain-mcp-adaptershttpx 딥 에이전트용 스킬을 로드하려면 deepagents도 설치하세요.
환경 구성
도구 상자에는 프로젝트 엔드포인트와 도구 상자 이름이 필요합니다. 엔드포인트를 환경 변수로 설정하고 도구 상자 이름을 생성자에 전달합니다.
프로젝트 엔드포인트를 설정합니다.
import os
os.environ["FOUNDRY_PROJECT_ENDPOINT"] = (
"https://<resource>.services.ai.azure.com/api/projects/<project>"
)
통합은 프로젝트 엔드포인트로 FOUNDRY_PROJECT_ENDPOINT 또는 AZURE_AI_PROJECT_ENDPOINT를 읽습니다. 도구 상자 이름을 제공하는 환경 변수가 없으므로 항상 생성자에 전달 toolbox_name 합니다.
공용 클래스를 가져오고 이 문서 전체에서 사용되는 모델을 초기화합니다.
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage
model = init_chat_model("azure_ai:gpt-4.1")
툴박스는 DefaultAzureCredential로 인증하며, 이때 사용자의 az login 세션을 감지합니다. 자격 증명을 직접 생성할 필요가 없습니다.
도구 상자에 연결
네임스페이스 AzureAIProjectToolbox의 langchain_azure_ai.tools를 사용하여 도구 상자에 연결합니다. 통합은 환경 변수를 설정할 때 프로젝트 연결을 검색합니다 FOUNDRY_PROJECT_ENDPOINT . Microsoft Entra ID 기본 인증 방법입니다.
from langchain_azure_ai.tools import AzureAIProjectToolbox
toolbox = AzureAIProjectToolbox(
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
toolbox_name="my-toolbox",
)
환경에서 엔드포인트를 설정하면 생략 project_endpoint할 수 있습니다. 항상 다음을 제공해야 합니다toolbox_name:
toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
비고
AzureAIProjectToolbox는 미리 보기 상태이며, 이를 만들면 ExperimentalWarning이 발생합니다. 해당 API는 변경될 수 있습니다.
도구 상자에서 도구 로드
호출 aget_tools() 하여 도구 상자로 세션을 열고 LangChain BaseTool 인스턴스로 노출되는 모든 도구를 로드합니다. 각 호출은 상태를 유지하지 않습니다. 즉, 새로운 MCP 세션을 열고 도구를 로드한 다음 이를 반환합니다.
async def main():
toolbox = AzureAIProjectToolbox(
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
toolbox_name="my-toolbox",
)
tools = await toolbox.aget_tools()
agent = create_agent(model=model, tools=tools)
result = await agent.ainvoke(
{"messages": [HumanMessage("What can you do?")]}
)
print(result["messages"][-1].content)
이 코드 조각이 수행하는 작업: 도구 상자에 연결하고, 해당 도구를 로드하고, 에이전트에 바인딩합니다. 에이전트를 호출할 때 모델은 도구 상자가 요청에 응답하기 위해 제공하는 모든 도구를 호출할 수 있습니다.
AzureAIProjectToolbox 는 비동기 컨텍스트 관리자 프로토콜도 지원합니다. 각 aget_tools() 호출이 자체 세션을 관리하기 때문에 동작은 동일합니다.
async with AzureAIProjectToolbox(toolbox_name="my-toolbox") as toolbox:
tools = await toolbox.aget_tools()
참조:create_agent
승인이 필요한 도구 식별
일부 도구 상자 도구는 실행하기 전에 승인이 필요하도록 구성됩니다. 실행하기 전에 휴먼 인 더 루프 단계를 추가할 수 있도록 해당 도구의 이름을 검색하기 위해 호출 get_tools_requiring_approval() 합니다.
tools_needing_approval = await toolbox.get_tools_requiring_approval()
print("Tools that require approval before execution:")
for name in tools_needing_approval:
print(f"- {name}")
이 코드 조각이 수행하는 작업: 툴박스 메타데이터를 검사하고 구성이 require_approval을(를) always(으)로 설정한 도구의 이름을 반환합니다. 이 목록을 사용하여 승인 워크플로 뒤에서 중요한 작업을 제어할 수 있습니다.
이 기능은 OAuth 동의 처리와 독립적입니다. 휴먼 인 더 루프 승인에 대한 자세한 내용은 LangGraph에서 Foundry 에이전트 서비스 사용을 참조하세요.
OAuth 동의 처리
Microsoft Foundry의 도구 상자는 대신 워크플로를 처리할 수 있습니다. 도구 상자에 도구를 추가할 때 권한 부여 요구 사항을 구성할 수 있습니다.
도구 상자 도구가 아직 권한이 부여되지 않은 서비스에 연결되면 Foundry 게이트웨이에 OAuth 동의가 필요합니다. 예외 get_tools()/aget_tools() 를 발생시키는 대신 에이전트가 사용자에게 표시할 수 있도록 동의 URL을 표시하는 대체 도구를 반환합니다.
에이전트를 호출하고 모델이 대체 도구를 호출하는 경우 응답에는 다음과 유사한 메시지가 포함됩니다.
OAuth consent is required before this toolbox can be used. Open the following
URL in a browser to authorize access, then restart the agent:
https://consent.azure-apim.net/...
브라우저에서 URL을 열어 액세스 권한을 부여 한 다음 에이전트를 다시 시작합니다. 동의를 부여하면 도구 상자가 해당 도구를 정상적으로 로드합니다.
도구 상자에서 기능 불러오기
도구 상자는 양식 skill://{name}의 URI를 사용하여 MCP 리소스로 기술을 노출합니다. 그것들을 LangChain get_resources() 객체로 로드하려면 Blob를 사용합니다. 각 Blob에는 source 속성에 리소스 이름이, metadata["uri"] 아래에 원시 URI가 포함됩니다.
skill_blobs = toolbox.get_resources(scheme="skills")
for blob in skill_blobs:
print(f"Skill: {blob.source}")
print(blob.as_string())
Skill: jokes-teller/SKILL.md
{'content': '---\nname: jokes-teller\ndescription: A skill to tell jokes\n---\n\nUse...'}
이 코드 조각이 수행하는 작업: 도구 상자의 모든 skill:// 리소스를 Blob로 로드합니다.
scheme="skills" 필터는 결과를 스킬 리소스로 제한합니다. 일치 항목은 대/소문자를 구분하지 않으며 단수 또는 복수 형식("skill" 또는 "skills")을 허용합니다.
특정 리소스를 로드하려면 해당 URI를 명시적으로 전달합니다.
uris를 제공하면 scheme 필터는 무시됩니다:
skill_blobs = toolbox.get_resources(uris="skill://my-skill/SKILL.md")
비동기 버전에는 aget_resources()을(를) 사용하세요:
skill_blobs = await toolbox.aget_resources(scheme="skills")
딥 에이전트용 스킬 불러오기
deepagents 패키지를 사용하는 경우, get_skills()용 즉시 사용 가능한 파일 매핑으로 도구 상자 기술을 로드하려면 create_deep_agent를 호출하세요. 이 메서드는 get_resources()을 기반으로 하며, 각 Blob을 딥 에이전트가 기대하는 파일 레이아웃으로 변환하는 반복 작업을 없앱니다.
패키지를 설치합니다.
pip install deepagents
다음 예제에서는 a StateBackend (기본값)를 시드합니다.
backend 인수는 설정하지 않은 상태로 두고, 반환된 매핑을 files에서 invoke 페이로드로 전달합니다:
from deepagents import create_deep_agent
from deepagents.backends import StateBackend
toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
skill_files = toolbox.get_skills()
agent = create_deep_agent(
model="azure_ai:gpt-4.1",
backend=StateBackend(),
skills=["/skills/"],
)
agent.invoke({"messages": [HumanMessage("Use a skill")], "files": skill_files})
이 코드 조각이 수행하는 작업: 툴박스 스킬을 가상 SKILL.md 경로의 매핑에 로드하고, files 페이로드를 통해 이를 에이전트 상태의 초기값으로 설정합니다. 그러면 에이전트가 기본 경로 아래 /skills/ 의 기술을 사용할 수 있습니다.
FilesystemBackend와 같은 독립 실행형 스토리지로 백엔드를 초기화하려면 이를 backend 인수로 전달합니다. 기술은 백 엔드에 기록되며 동일한 매핑도 반환됩니다.
from deepagents.backends import FilesystemBackend
backend = FilesystemBackend(root_dir="./my-project")
toolbox = AzureAIProjectToolbox(toolbox_name="my-toolbox")
await toolbox.aget_skills(backend=backend)
agent = create_deep_agent(
model="azure_ai:gpt-4.1",
backend=backend,
skills=["/skills/"],
)
기본적으로 기술 파일은 기본 경로 아래에 /skills/ 배치됩니다. 위치를 변경하려면 다른 base_path 값을 전달합니다. 값은 슬래시로 시작하고 끝나야 하며 동일한 값을 인수skills에 create_deep_agent 전달해야 합니다.