Microsoft Agent Framework는 Microsoft Foundry 프로젝트 엔드포인트의 직접 모델 유추와 Foundry 에이전트 서비스 서비스 관리 에이전트를 모두 지원합니다.
시작하기
필요한 NuGet 패키지를 프로젝트에 추가합니다.
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease
두 가지 에이전트 유형
Microsoft Foundry 통합은 두 가지 고유한 사용 패턴을 노출합니다.
| 유형 | 생성된 형식 | 설명 | 사용 시기 |
|---|---|---|---|
| 응답 에이전트 | ChatClientAgent |
앱은 런타임 AIProjectClient.AsAIAgent(...)에 프로그래밍 방식으로 모델, 지침 및 도구를 제공합니다. 서버 쪽 에이전트 리소스가 만들어지지 않습니다. |
에이전트 정의를 소유하고 있으며 간단하고 유연한 설정을 원합니다. 대부분의 샘플에서 사용되는 패턴입니다. |
| Foundry 에이전트 (버전) | FoundryAgent |
서버 관리 - 에이전트 정의는 Foundry 포털을 통해 만들어지거나 프로그래밍 방식으로 AIProjectClient.AgentAdministrationClient 생성되며 버전이 지정됩니다.
ProjectsAgentVersion 또는 ProjectsAgentRecord 또는 AgentReference를 AIProjectClient.AsAIAgent(...)에 전달하십시오. |
서비스 API를 통해 Foundry 포털에서 관리되는 엄격한 버전 관리 에이전트 정의가 필요합니다. |
응답 에이전트(직접 유추)
AsAIAgent에 직접 AIProjectClient를 모델과 지침과 함께 사용합니다. 대부분의 시나리오에서 권장되는 시작점입니다.
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
AIAgent agent = new AIProjectClient(
new Uri("<your-foundry-project-endpoint>"),
new DefaultAzureCredential())
.AsAIAgent(
model: "gpt-4o-mini",
name: "Joker",
instructions: "You are good at telling jokes.");
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
경고
DefaultAzureCredential 은 개발에 편리하지만 프로덕션 환경에서 신중하게 고려해야 합니다. 프로덕션 환경에서는 특정 자격 증명(예: ManagedIdentityCredential)을 사용하여 대기 시간 문제, 의도하지 않은 자격 증명 검색 및 대체 메커니즘의 잠재적인 보안 위험을 방지하는 것이 좋습니다.
이 경로는 코드 우선이며 서버 관리 에이전트 리소스를 만들지 않습니다.
Foundry 에이전트(버전 관리)
AI Projects SDK의 네이티브 AIProjectClient.AgentAdministrationClient API를 사용하여 버전이 지정된 에이전트 리소스를 검색한 다음, AsAIAgent 로 래핑하십시오. 에이전트를 만들어 Foundry 포털에서 직접 구성하거나 프로그래밍 방식으로 구성할 AIProjectClient.AgentAdministrationClient수 있습니다.
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;
var aiProjectClient = new AIProjectClient(
new Uri("<your-foundry-project-endpoint>"),
new DefaultAzureCredential());
// Retrieve an existing agent by name (uses the latest version automatically)
ProjectsAgentRecord jokerRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync("Joker");
FoundryAgent agent = aiProjectClient.AsAIAgent(jokerRecord);
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
중요합니다
Foundry 에이전트 도구 및 지침은 생성된 도구와 지침에 엄격하게 맞추어 있으며, 런타임 시 도구 및 지침을 수정하려는 시도는 지원되지 않습니다.
에이전트 사용
(응답) 및 ChatClientAgent (버전 관리) 모두 FoundryAgent 표준 AIAgent 인스턴스이며 세션, 도구, 미들웨어 및 스트리밍을 포함한 모든 표준 작업을 지원합니다.
AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke.", session));
Console.WriteLine(await agent.RunAsync("Now make it funnier.", session));
에이전트를 실행하고 상호 작용하는 방법에 대한 자세한 내용은 에이전트 시작 자습서를 참조하세요.
Tools
(응답 경로)에서 AIProjectClient.AsAIAgent(...) 만든 Foundry 에이전트는 표준 에이전트 프레임워크 도구 화면을 지원합니다. 전체 목록 및 지원되는 기능 매트릭스에 대한 도구 개요 를 참조하세요. 버전이 지정된 에이전트 정의(FoundryAgent)에서 로드된 Foundry 에이전트의 경우 에이전트의 도구는 클라이언트가 아닌 Foundry 에이전트 정의에 의해 소유됩니다.
| Tool | Notes |
|---|---|
| 함수 도구 | Supported. |
| 도구 승인 | Supported. 프레임워크의 함수 호출 채팅 클라이언트에서 제공합니다. |
| 코드 해석기 | Supported. |
| 파일 검색 | Supported. |
| 호스트된 MCP 도구 | Supported. |
| 로컬 MCP 도구 | Supported. |
| Foundry 도구 상자 | Supported. |
공구함
메모
Foundry 도구 상자 .NET 문서는 곧 제공될 예정입니다.
Python 파운드리
Python 모든 Foundry 관련 클라이언트는 이제 agent_framework.foundry 아래에 있습니다.
-
agent-framework-foundry는 클라우드 Foundry 커넥터를FoundryChatClientFoundryAgentFoundryEmbeddingClientFoundryMemoryProvider제공합니다. -
agent-framework-foundry-local는FoundryLocalClient로컬 모델 실행을 제공합니다.
중요합니다
이 페이지에서는 Microsoft Foundry 프로젝트 엔드포인트, 모델 엔드포인트 및 Foundry 에이전트 서비스에 대한 현재 Python 클라이언트에 대해 설명합니다. 독립 실행형 Azure OpenAI 리소스 엔드포인트(https://<your-resource>.openai.azure.com)가 있는 경우 OpenAI 공급자 페이지 Python 지침을 사용합니다. 지원되는 모델을 로컬로 실행하려면 Foundry 로컬 공급자 페이지를 참조하세요.
Python 파운드리 채팅 및 에이전트 패턴
| 시나리오 | Python 셰이프 | 사용 시기 |
|---|---|---|
| Foundry 응답 엔드포인트를 사용하여 일반 유추 | Agent(client=FoundryChatClient(...)) |
앱은 에이전트 정의, 도구 및 대화 루프를 소유하고 있으며, 당신은 Foundry 프로젝트에 모델을 배포하길 원합니다. |
| Foundry 에이전트 서비스의 서비스 관리형 에이전트 | FoundryAgent(...) |
Foundry 포털 또는 서비스 API를 통해 만들어지고 구성된 PromptAgent 또는 HostedAgent에 연결하려고 합니다. |
설치
pip install agent-framework-foundry
pip install azure-identity
동일한 agent-framework-foundry 패키지에는 Foundry 모델-엔드포인트 임베딩도 FoundryEmbeddingClient 포함됩니다.
Configuration
FoundryChatClient
FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_MODEL="gpt-4o-mini"
FoundryAgent
FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"
FOUNDRY_AGENT_VERSION을(를) 프롬프트 에이전트에 사용하세요. 호스트된 에이전트는 생략할 수 있습니다.
FoundryEmbeddingClient
FOUNDRY_MODELS_ENDPOINT="https://<apim-instance>.azure-api.net/<foundry-instance>/models"
FOUNDRY_MODELS_API_KEY="<api-key>"
FOUNDRY_EMBEDDING_MODEL="text-embedding-3-small"
FOUNDRY_IMAGE_EMBEDDING_MODEL="Cohere-embed-v3-english" # optional
FoundryChatClient 및 FoundryAgent는 프로젝트 엔드포인트를 사용합니다.
FoundryEmbeddingClient 는 별도의 모델 엔드포인트를 사용합니다.
올바른 Python 클라이언트 선택
| 시나리오 | 기본 설정 클라이언트 | Notes |
|---|---|---|
| Azure OpenAI 리소스 | OpenAIChatCompletionClient / OpenAIChatClient |
OpenAI 공급자 페이지를 사용합니다. |
| Microsoft Foundry 프로젝트 유추 | Agent(client=FoundryChatClient(...)) |
Foundry 응답 엔드포인트를 사용합니다. |
| Microsoft Foundry 서비스 관리 에이전트 | FoundryAgent |
프롬프트 에이전트 및 HostedAgents에 권장됩니다. |
| Microsoft Foundry 모델 엔드포인트 임베딩 | FoundryEmbeddingClient |
더하기 FOUNDRY_MODELS_ENDPOINTFOUNDRY_EMBEDDING_MODEL / FOUNDRY_IMAGE_EMBEDDING_MODEL를 사용합니다. |
| Foundry 로컬 런타임 | Agent(client=FoundryLocalClient(...)) |
Foundry Local을 참조하세요. |
다음을 사용하여 에이전트 만들기 FoundryChatClient
FoundryChatClient 는 Foundry 프로젝트에서 배포된 모델에 연결하고 응답 엔드포인트를 사용합니다. 앱이 지침, 도구 및 세션 처리를 소유해야 하는 경우 표준 Agent 과 페어링합니다.
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
agent = Agent(
client=FoundryChatClient(
project_endpoint="https://your-project.services.ai.azure.com",
model="gpt-4o-mini",
credential=AzureCliCredential(),
),
name="FoundryWeatherAgent",
instructions="You are a helpful assistant.",
)
FoundryChatClient 직접 유추를 위한 Foundry 우선 Python 경로이며 도구, 구조적 출력 및 스트리밍을 지원합니다.
Tools
FoundryChatClient 는 호스트된 각 Foundry 도구에 대한 정적 팩터리 메서드를 제공합니다. 팩터리는 Agent에서 tools=에 전달하거나 직접 client.get_response(..., tools=[...])에 전달한 SDK 도구 개체를 반환합니다. 에이전트FoundryAgent의 도구는 Foundry 에이전트 정의 자체에 있습니다. 작동되는 항목과 작동하지 않는 FoundryAgent항목은 참조하세요.
팩터리 클래스 메서드이므로 도구를 만드는 데 인스턴스가 필요하지 않습니다.
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
agent = Agent(
client=FoundryChatClient(credential=AzureCliCredential()),
instructions="You can search the web and run code.",
tools=[
FoundryChatClient.get_web_search_tool(),
FoundryChatClient.get_code_interpreter_tool(),
],
)
도구 지원
아래 표에는 현재 Python FoundryChatClient 노출하는 모든 도구가 나와 있습니다.
FoundryAgent 는 동일한 도구에서 작동하지만 코드에서 전달되지 않고 Foundry 에이전트 정의에서 구성해야 합니다.
| Tool | 팩터리 켜기 FoundryChatClient |
상태 | 세부 정보 |
|---|---|---|---|
| 함수 도구 | n/a — 임의의 Python 호출 가능한 객체 또는 @ai_function 를 전달합니다. |
GA | Python 프로세스에서 로컬로 호출됩니다. |
| 도구 승인 | n/a — 기존 도구를 감싸서 사용 | GA | 호스트된 MCP 및 함수 도구에서 작동합니다. |
| 코드 해석기 | get_code_interpreter_tool |
GA | Foundry에서 샌드박스 코드 실행 |
| 파일 검색 | get_file_search_tool |
GA | Foundry 벡터 저장소를 통해 업로드된 파일을 검색합니다. |
| 웹 검색 | get_web_search_tool |
GA | Microsoft에서 관리하는 Bing 기반 웹 그라운딩. Azure OpenAI 모델만. |
| 이미지 생성 | get_image_generation_tool |
GA | Foundry에서 호스트되는 이미지 생성입니다. |
| 호스트된 MCP | get_mcp_tool |
GA | Foundry에서 호출한 원격 MCP 서버입니다. |
| 로컬 MCP | n/a — MCPStreamableHTTPTool / MCPStdioTool 사용 |
GA | 프로세스에서 실행합니다. 는 모든 클라이언트에서 작동합니다. |
| Foundry 도구 상자 |
MCPStreamableHTTPTool 툴박스 MCP 엔드포인트로 |
GA |
FoundryChatClient에서 MCP를 통해 사용됨; FoundryAgent에서 서버 측에 연결됨. |
| 빙 접지 | get_bing_grounding_tool |
Experimental | Bing Search 리소스를 사용한 사용자 제공 그라운딩 |
| 빙 커스텀 검색 | get_bing_custom_search_tool |
Preview | Bing 그라운딩은 엄선된 도메인 목록으로 제한됩니다. |
| Azure AI 검색 | get_azure_ai_search_tool |
Experimental | Foundry 연결을 통해 Azure AI 검색 인덱스 검색 |
| SharePoint | get_sharepoint_tool |
Preview | SharePoint 콘텐츠의 기본 답변입니다. |
| Microsoft Fabric | get_fabric_tool |
Preview | Fabric 데이터 에이전트를 쿼리합니다. |
| 메모리 검색 | get_memory_search_tool |
Preview | Foundry 관리 메모리 저장소를 검색합니다. |
| 컴퓨터 사용 | get_computer_use_tool |
Preview | 에이전트가 데스크톱 또는 브라우저 환경을 구동하도록 합니다. |
| 브라우저 자동화 | get_browser_automation_tool |
Preview | Azure Playwright 연결을 통해 브라우저를 구동합니다. |
| 에이전트 투 에이전트 (A2A) | get_a2a_tool |
Preview | 다른 A2A 에이전트를 도구로 호출합니다. |
메모
실험용 팩터리는 GA Foundry SDK 유형을 래핑하지만, 래퍼 자체는 GA 릴리스 전에 변경될 수 있습니다.
미리 보기 팩터리는 기본 기능이 미리 보기로 제공되며 변경되거나 제거될 수 있는 Foundry SDK 형식을 래핑합니다. 둘 다 프로세스 내에서 처음 사용될 때 ExperimentalWarning를 내보낸다.
웹 검색 변형
Foundry는 Bing 기반 그라운딩 옵션 세 가지를 제공합니다. 시나리오와 일치하는 항목을 선택합니다.
-
get_web_search_tool(GA) - 0 설정 기본값; Microsoft 의해 관리되는 Bing 리소스입니다. Azure OpenAI 모델만.user_location및search_context_size로 제한됩니다. -
get_bing_grounding_tool(실험적) — Bing Search Azure 리소스를 사용한 사용자 지정 그라운딩.countfreshnessmarketset_langOpenAI Foundry가 아닌 모델을 지원합니다. -
get_bing_custom_search_tool(미리 보기) — 자체 Bing Custom Search 인스턴스를 사용하여 응답의 근거를 선별된 도메인 집합으로 제한합니다.
세 가지 모두 Azure 준수 경계 외부에서 검색 데이터를 보냅니다. 전체 비교는 웹 기초 개요를 참조하세요.
client = FoundryChatClient(credential=AzureCliCredential())
# Default (GA): minimal configuration
web_search = client.get_web_search_tool(
user_location={"city": "Amsterdam", "country": "NL"},
search_context_size="medium",
)
이미지 생성
get_image_generation_tool 는 Foundry의 호스트된 이미지 생성 도구를 구성합니다. 모델은 응답에 이미지 콘텐츠를 생성합니다. 관리할 추가 파일이 없습니다.
image_gen = FoundryChatClient.get_image_generation_tool(
model="gpt-image-1",
size="1024x1024",
output_format="png",
quality="high",
)
Bing 기반 근거 제공
get_bing_grounding_tool는 Grounding with Bing Search Foundry 도구를 래핑합니다. Bing Search 리소스를 사용하여 Grounding을 직접 만들고 Foundry 프로젝트 연결로 추가한 다음 연결 ID를 전달합니다.
bing = FoundryChatClient.get_bing_grounding_tool(
connection_id="/subscriptions/.../connections/my-bing",
market="en-US",
freshness="Day",
count=10,
)
Bing 사용자 지정 검색
get_bing_custom_search_tool 는 Bing Custom Search 리소스에 정의된 허용 목록으로 접지를 제한합니다.
bing_custom = FoundryChatClient.get_bing_custom_search_tool(
connection_id="/subscriptions/.../connections/my-bing-custom",
instance_name="docs-only",
market="en-US",
)
Azure AI 검색
get_azure_ai_search_tool 사용하면 에이전트가 Foundry 프로젝트 연결을 통해 Azure AI 검색 인덱스 쿼리를 수행할 수 있습니다.
ai_search = FoundryChatClient.get_azure_ai_search_tool(
index_connection_id="/subscriptions/.../connections/my-search",
index_name="product-docs",
query_type="vector_semantic_hybrid",
top_k=5,
)
SharePoint
get_sharepoint_tool는 Foundry SharePoint 연결을 통해 액세스할 수 있는 SharePoint 콘텐츠에 답변의 근거를 둡니다.
sharepoint = FoundryChatClient.get_sharepoint_tool(
connection_id="/subscriptions/.../connections/my-sharepoint",
)
Microsoft Fabric
get_fabric_tool 에이전트가 Fabric 데이터에 대한 질문에 대답할 수 있도록 Foundry 연결을 통해 에이전트를 Microsoft Fabric 데이터 에이전트에 연결합니다.
fabric = FoundryChatClient.get_fabric_tool(
connection_id="/subscriptions/.../connections/my-fabric",
)
메모리 검색
get_memory_search_tool 를 사용하면 에이전트가 선택적으로 사용자 또는 테넌트에 범위가 지정된 Foundry 관리 메모리 저장소를 검색할 수 있습니다.
memory = FoundryChatClient.get_memory_search_tool(
memory_store_name="user-preferences",
scope="{{$userId}}",
)
컴퓨터 사용
get_computer_use_tool 는 컴퓨터 사용 미리 보기 도구를 구성합니다. 모델은 포인터 및 키보드 작업을 실행하여 데스크톱 또는 브라우저 환경을 구동할 수 있습니다.
computer = FoundryChatClient.get_computer_use_tool(
environment="browser",
display_width=1280,
display_height=800,
)
브라우저 자동화
get_browser_automation_tool Foundry 연결을 통해 에이전트를 Azure Playwright Testing 리소스에 연결합니다. 에이전트는 Playwright를 통해 실제 브라우저를 구동할 수 있습니다.
browser = FoundryChatClient.get_browser_automation_tool(
connection_id="/subscriptions/.../connections/my-playwright",
)
에이전트 간의 통신(A2A)
get_a2a_tool 는 Foundry 에이전트가 호출할 수 있도록 원격 A2A 에이전트를 도구로 노출합니다. 저장된 A2A 연결에 대해 base_url(선택적으로 agent_card_path 포함) 또는 project_connection_id를 제공합니다.
a2a = FoundryChatClient.get_a2a_tool(
base_url="https://remote-agent.example.com",
agent_card_path="/.well-known/agent-card.json",
)
검색, 세션, 스트리밍과 같은 일반적인 A2A 지침은 에이전트-에이전트 공급자 페이지를 참조하세요.
FoundryEmbeddingClient을 사용하여 임베딩 생성하기
Foundry 모델 엔드포인트에서 텍스트 또는 이미지 포함을 원하는 경우에 사용합니다 FoundryEmbeddingClient .
from agent_framework.foundry import FoundryEmbeddingClient
async with FoundryEmbeddingClient() as client:
result = await client.get_embeddings(["hello from Agent Framework"])
print(result[0].dimensions)
를 사용하여 서비스 관리 에이전트에 연결 FoundryAgent
에이전트 정의가 Foundry에 있을 때 사용합니다 FoundryAgent . 프롬프트 에이전트 및 HostedAgents에 권장되는 Python API입니다.
from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential
agent = FoundryAgent(
project_endpoint="https://your-project.services.ai.azure.com",
agent_name="my-prompt-agent",
agent_version="1.0",
credential=AzureCliCredential(),
)
HostedAgent의 경우 호스트된 에이전트 이름을 생략 agent_version 하고 대신 사용합니다.
FoundryAgent에서 되는 것과 안 되는 것
FoundryAgent 는 Foundry(프롬프트 에이전트 또는 호스트된 에이전트)에 이미 있는 에이전트에 연결합니다. 에이전트의 정의(지침 및 도구 구성)는 Python 코드가 아닌 Foundry에 있습니다. 즉, 여러 Agent 수준의 기능은 Agent(client=FoundryChatClient(...)) 또는 다른 채팅 클라이언트 기반 에이전트와 함께 사용할 때와는 다르게 동작한다는 의미입니다.
Tools
FoundryAgent(...)에 전달된 도구 유형 |
Behavior |
|---|---|
FunctionTool(로컬 Python 호출 가능) |
지원되지만 일치하는 함수 정의가 Foundry 에이전트에 이미 있는 경우에만 지원됩니다. Foundry 런타임은 에이전트 정의에 따라 모델에 노출할 도구를 결정합니다. 모델이 함수를 호출하면 Foundry는 클라이언트에 도구 호출을 반환하고, 프레임워크는 사용자 프로세스에서 로컬 Python 호출 가능 객체를 호출한 다음(Foundry 내에서가 아니라) 그 결과를 다시 보냅니다. 클라이언트 쪽을 FunctionTool 전달하면 해당 로컬 구현만 제공됩니다. 함수가 Foundry 에이전트에 선언되지 않은 경우 모델은 이 함수를 호출하지 않습니다. |
| 호스트된 도구(웹 검색, 코드 인터프리터, 파일 검색, MCP, 이미지 생성 등) | 무시됩니다. 이러한 구성은 Foundry 포털 또는 서비스 API를 통해 Foundry 에이전트 정의 자체에서 구성해야 합니다. Foundry 런타임은 에이전트 정의에 연결된 도구에 대해서만 알고 있으므로 클라이언트 쪽을 전달해도 아무 효과가 없습니다. |
즉, 건설 시 새 도구를 추가할 수 없습니다. 로컬 Python 함수를 포함하여 모델이 호출할 수 있는 모든 도구는 이미 Foundry의 에이전트 정의에 속해야 합니다.
FunctionTool
FoundryAgent(...) 전달하면 Foundry 정의 함수가 호출되는 경우 Python 프로세스에서 실행되는 로컬 구현만 제공하며 에이전트에 새 도구를 등록하지는 않습니다.
컨텍스트 공급자
context_providers=[...] 는 부분적으로 지원됩니다. 컨텍스트 공급자의 작동 여부는 공급자가 수행하려고 하는 작업에 따라 달라집니다.
| 컨텍스트 공급자 동작 |
FoundryAgent와 호환되나요? |
|---|---|
| 메시지로 추가 컨텍스트 추가(예: 검색된 메모리, RAG 코드 조각, 사용자 프로필 정보) | Yes. 삽입된 컨텍스트는 요청과 함께 전달됩니다. |
| 대화를 유지하거나 관찰합니다(예: 쓰기는 외부 저장소로 바뀝니다). | Yes. 요청/응답을 중심으로 로컬로 실행됩니다. |
도구를 동적으로 추가합니다(예: SkillsProvider 또는 invoking()에서 도구를 반환하는 공급자). |
아니요, 도구가 이미 Foundry 에이전트 정의에 속하지 않는 한 Foundry 런타임은 Foundry의 에이전트에 연결된 도구에 대해 모델을 실행합니다. 로컬에만 존재하는 도구는 모델에 노출되지 않으며 호출되지 않습니다. |
동적 도구 선택, 기술 로드 또는 런타임에 추가되는 도구에 의존하는 다른 동작이 필요한 경우 대신 사용합니다 Agent(client=FoundryChatClient(...)) . 해당 경로는 모델 루프를 로컬로 소유하고 도구 유형 및 도구 추가 컨텍스트 공급자의 전체 집합을 지원합니다.
실행 옵션(default_options 및 agent.run(...) 옵션)
FoundryAgent(default_options=...) 또는 agent.run(..., **options)에 전달하는 옵션(예: temperature, top_p, max_tokens, instructions, tool_choice, response_format, metadata 등)은 모두 적용되지는 않습니다. Foundry의 에이전트 정의는 진실의 근원이므로 많은 옵션이 자동으로 무시됩니다.
프롬프트 에이전트의 경우 프레임워크는 Foundry 응답 API에 요청을 보내기 전에 다음을 명시적으로 제거하거나 재정의합니다.
| 옵션 |
FoundryAgent와(과) 함께하는 동작 |
|---|---|
model |
무시됩니다. 모델은 Foundry 에이전트 정의에서 가져옵니다. |
tools, tool_choice, parallel_tool_calls |
요청 본문에서 제거되었습니다. 도구는 Foundry 에이전트 정의에 선언되어야 합니다(이전 섹션 참조).
FunctionTool 호출 가능 항목은 여전히 함수 호출을 위해 로컬로 연결되지만 도구 목록 자체는 서비스로 전송되지 않습니다. |
instructions 및 시스템/개발자 메시지 |
무시됩니다. Foundry 에이전트의 자체 지침은 신뢰할 수 있습니다. 요청이 전송되기 전에 시스템/개발자 메시지가 메시지 목록에서 제거됩니다. |
conversation_id |
사용되며, Foundry 에이전트 세션을 참조하는 경우 해당 세션에 매핑됩니다. |
extra_body |
전달되어, 프레임워크에서 설정된 agent_reference 페이로드와 병합됩니다. |
샘플링 매개 변수(temperature, ,top_p, max_tokensseed, frequency_penalty, presence_penalty, stop...), metadata, userstore, response_format등 |
응답 API로 전달됩니다. Foundry가 실제로 적용되는지 여부는 에이전트 및 모델 구성에 따라 달라집니다. 에이전트 정의는 이를 재정의하거나 제한할 수 있으므로 프롬프트 에이전트에 적용되는 것에 의존하지 마세요. |
호스트된 에이전트의 경우 동일한 클라이언트 쪽 제거가 적용되지만 그 이상의 모든 항목은 특정 호스팅 에이전트가 구현하는 항목에 따라 달라집니다. 호스트된 에이전트는 전달된 모든 옵션을 수락, 무시 또는 재해석할 수 있습니다. 런타임 옵션을 권고로 처리하고 호출하는 호스트된 에이전트에 대한 실제 동작을 확인합니다.
팁 (조언)
실행마다 생성 매개변수, 지침 또는 도구 선택을 정밀하게 제어해야 하는 경우 Foundry 에이전트 정의에서 이를 구성하거나, Agent(client=FoundryChatClient(...))를 처음부터 끝까지 준수하는 ChatOptions로 전환하세요.
팁 (조언)
좋은 경험칙이 있습니다. 기능이 실행할 때마다 에이전트의 지침이나 도구를 바꿔야 한다면, 그 기능은 Agent(client=FoundryChatClient(...))에 해당합니다. 에이전트의 정의가 Foundry에서 수정되고 로컬 함수 호출과 메시지 수준 컨텍스트 FoundryAgent 만 필요한 경우 적합한 선택입니다.
배포된(호스트된) Foundry 에이전트에 연결
서비스 측 세션(/agents/{name}/sessions)을 실행하는 HostedAgents의 경우, 미리 보기 Responses 화면을 사용하도록 설정하려면 FoundryAgent와 함께 allow_preview=True을 사용하세요:
from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential
agent = FoundryAgent(
agent_name="my-hosted-agent",
credential=AzureCliCredential(),
allow_preview=True,
)
특정 테넌트 또는 사용자에게 세션을 바인딩하는 등 기본 서비스 세션을 직접 관리해야 하는 경우 미리 보기 AIProjectClient API를 통해 세션을 만들고 다음으로 agent.get_session(...)래핑합니다.
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import VersionRefIndicator
service_session = await project_client.beta.agents.create_session(
agent_name="my-hosted-agent",
isolation_key="user-123",
version_indicator=VersionRefIndicator(agent_version="1.0"),
)
session = agent.get_session(service_session.agent_session_id)
response = await agent.run("Hello!", session=session)
팁 (조언)
using_deployed_agent.py
최신 버전 자동 해결을 포함하여 전체 예제는 샘플을 참조하세요.
경고
이전 Python AzureAIClient, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider 및 Azure AI 포함 호환성 화면이 현재 agent_framework.azure 네임스페이스에서 제거되었습니다. 현재 Python 코드의 경우 앱이 명령 및 도구를 소유할 때 FoundryChatClient, 에이전트 정의가 Foundry에 있을 때는 FoundryAgent, Foundry 모델 엔드포인트 포함에는 FoundryEmbeddingClient 사용합니다.
에이전트 사용
FoundryChatClient 및 FoundryAgent 모두 도구 호출, 세션 및 스트리밍 응답을 포함하여 표준 Python Agent 환경과 통합됩니다. 로컬 런타임의 경우 별도의 Foundry 로컬 공급자 페이지를 사용합니다.
공구함
중요합니다
도구 상자 API는 실험적입니다. 표면은 향후 릴리스에서 변경될 수 있습니다.
Foundry 도구 상자는 Microsoft Foundry 프로젝트에 구성된 호스트된 도구 구성(코드 인터프리터, 파일 검색, 이미지 생성, MCP, 웹 검색)의 명명된 버전이 지정된 서버 쪽 번들입니다. 도구 상자를 사용하면 Foundry 포털에서 도구 구성을 한 번 관리하고 에이전트 간에 다시 사용할 수 있습니다.
에이전트 프레임워크는 사용 량에만 해당합니다. 도구 상자 버전을 만들고 업데이트하는 작업은 Foundry 포털 또는 원시 azure-ai-projects SDK(azure-ai-projects>=2.1.0)를 통해 수행됩니다.
FoundryAgent vs FoundryChatClient
| 에이전트 유형 | 도구 상자 동작 |
|---|---|
| FoundryAgent (호스트됨) | 도구 상자 연결은 서버 쪽에서 발생합니다. 클라이언트 쪽 배선이 필요하지 않습니다. |
| FoundryChatClient (직접 유추) | 도구 상자를 가져오고 get_toolbox()를 tools=로 전달하세요. |
두 가지 사용 패턴
| Pattern | 설명 |
|---|---|
| 네이티브(호스트된 도구) | 도구 구성은 Foundry 런타임에서 실행됩니다. 도구 상자를 tools=로 직접 전달합니다. |
| MCP | 도구 상자의 MCP 엔드포인트에 MCPStreamableHTTPTool를 사용합니다. 뿐만 FoundryChatClient아니라 모든 채팅 클라이언트에서 작동합니다. |
도구 상자 가져오기
이 기능을 사용하여 FoundryChatClient.get_toolbox()를 통해 도구 상자를 검색하십시오.
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential
async with AzureCliCredential() as credential:
client = FoundryChatClient(credential=credential)
toolbox = await client.get_toolbox("research_toolbox")
async with Agent(client=client, name="ResearchAgent", tools=toolbox) as agent:
result = await agent.run("Summarize recent findings.")
print(result.text)
version 생략하면 get_toolbox 두 요청에서 기본 버전을 확인합니다. 추가 왕복을 방지하기 위해 특정 버전을 고정합니다.
toolbox = await client.get_toolbox("research_toolbox", version="v3")
메모
기본 버전은 서버 측에서 변경될 수 있기 때문에 각 get_toolbox() 호출은 네트워크를 거치게 됩니다. 프레임워크 쪽에 캐시가 없습니다. 캐싱은 호출자 소유입니다.
암시적 평면화
toolbox.tools을(를) 작성할 필요가 없습니다. 프레임워크는 normalize_tools 자동으로 인식하고 ToolboxVersionObject 평면화합니다. 이러한 모든 작업:
# Single toolbox
agent = Agent(client=client, tools=toolbox)
# Toolbox in a list
agent = Agent(client=client, tools=[toolbox])
# Mix local function tools with a toolbox
agent = Agent(client=client, tools=[get_internal_metrics, toolbox])
# Combine multiple toolboxes
agent = Agent(client=client, tools=[toolbox_a, toolbox_b])
를 사용하여 필터링 도구
도구 상자에서 여러 도구를 번들로 묶지만 에이전트에 하위 집합만 필요한 경우, 페치 후 집합을 좁히는 데에 select_toolbox_tools를 사용합니다. 이렇게 하면 불필요한 도구 정의를 모델에 보내지 않으므로 토큰 사용량이 줄어들고 모델이 노출하지 않으려는 도구를 호출하지 못하게 됩니다.
from agent_framework.foundry import select_toolbox_tools, get_toolbox_tool_name
# Filter by tool name
tools = select_toolbox_tools(toolbox, include_names=["web_search", "code_interpreter"])
# Filter by tool type
tools = select_toolbox_tools(toolbox, include_types=["mcp", "web_search"])
# Filter with a custom predicate
tools = select_toolbox_tools(toolbox, predicate=lambda t: "search" in (get_toolbox_tool_name(t) or ""))
도우미 함수 get_toolbox_tool_name(tool)와 get_toolbox_tool_type(tool)는 각각 도구 항목의 선택 이름과 원시 형식을 반환합니다.
FoundryHostedToolType는 TypeAlias이며 (Literal["code_interpreter", "file_search", "image_generation", "mcp", "web_search"] | str)로 IDE 기반의 자동 완성을 제공합니다 include_types / exclude_types.
MCP 사용 경로
툴박스의 MCP 엔드포인트 URL을 MCPStreamableHTTPTool에 지정함으로써 툴박스를 MCP 서버로 사용할 수도 있습니다.
MCP 엔드포인트 URL은 Foundry 포털에 표시되거나 형식을 따릅니다.
https://<account>.services.ai.azure.com/api/projects/<project>/toolsets/<name>/mcp?api-version=v1
클라이언트가 Foundry 도구 상자 엔드포인트에 직접 연결하므로, header_provider로 Entra ID 베어러 토큰을 사용하여 인증해야 합니다.
from azure.identity.aio import DefaultAzureCredential
from azure.identity.aio import get_bearer_token_provider
from agent_framework import Agent, MCPStreamableHTTPTool
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
mcp_tool = MCPStreamableHTTPTool(
name="research_mcp",
url="https://<your-toolbox-mcp-endpoint>",
header_provider=lambda: {"Authorization": f"Bearer {token_provider()}"},
)
async with Agent(client=client, name="MCPAgent", tools=[mcp_tool]) as agent:
result = await agent.run("Search for recent papers on LLM agents.")
print(result.text)
제한점
- 도구 상자 내의 MCP 도구는 서버 쪽 인증을 사용합니다. 업스트림 MCP 서버에 대한 인증은 (Foundry 프로젝트에 구성된 OAuth 연결)을 통해
project_connection_id처리됩니다. 클라이언트는 업스트림 서버에 대한 전달자 토큰을 보유하지 않습니다. - 도구 상자를 MCP 서버로 사용하려면 클라이언트 쪽 인증이 필요합니다. 도구 상자의 MCP 엔드포인트를 가리킬
MCPStreamableHTTPTool때는get_bearer_token_provider(credential, "https://ai.azure.com/.default")를 통해 Entra ID 전달자 토큰을 제공해야 합니다(예:header_provider를 통해). - 동의 흐름 처리는 런타임 문제입니다. 만약 도구 상자 MCP 도구가
CONSENT_REQUIRED동안agent.run()트리거되면, 이는 도구 상자 가져오기 중이 아니라 런타임에 처리됩니다.
샘플
| Sample | 설명 |
|---|---|
| foundry_chat_client_with_toolbox.py | 기본 도구 상자 가져오기, 버전 고정, 도구 상자 결합 및 필터링 |
| foundry_chat_client_with_toolbox_mcp.py | MCP 사용 경로 MCPStreamableHTTPTool |
| foundry_toolbox_context_provider.py | 컨텍스트 공급자를 통한 동적 턴별 도구 선택 |