이 문서를 사용하여 MCP(모델 컨텍스트 프로토콜) 서버와 Foundry 에이전트 서비스를 연결하기 위한 코드 샘플을 찾을 수 있습니다.
필수 조건
- GitHub MCP 서버와 같은 구성된 MCP 서버입니다.
프로젝트 클라이언트 만들기
AI 프로젝트 및 기타 리소스에 연결하기 위한 엔드포인트가 포함된 클라이언트 개체를 만듭니다.
비고
GitHub에서 비동기 예제를 찾을 수 있습니다.
var projectEndpoint = System.Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
var modelDeploymentName = System.Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME");
var mcpServerUrl = System.Environment.GetEnvironmentVariable("MCP_SERVER_URL");
var mcpServerLabel = System.Environment.GetEnvironmentVariable("MCP_SERVER_LABEL");
PersistentAgentsClient agentClient = new(projectEndpoint, new DefaultAzureCredential());
MCP 도구 정의 만들기
MCP 도구 정의를 만들고 허용된 도구를 구성합니다.
// Create MCP tool definition
MCPToolDefinition mcpTool = new(mcpServerLabel, mcpServerUrl);
// Configure allowed tools (optional)
string searchApiCode = "search_azure_rest_api_code";
mcpTool.AllowedTools.Add(searchApiCode);
MCPToolDefinition 에이전트 초기화 중에 사용합니다.
PersistentAgent agent = agentClient.Administration.CreateAgent(
model: modelDeploymentName,
name: "my-mcp-agent",
instructions: "You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
tools: [mcpTool]);
스레드 만들기 및 메시지 추가
스레드를 만들고 에이전트에 대한 질문이 포함된 메시지를 추가하고 MCP 도구 리소스를 사용하여 실행을 시작합니다.
PersistentAgentThread thread = agentClient.Threads.CreateThread();
// Create message to thread
PersistentThreadMessage message = agentClient.Messages.CreateMessage(
thread.Id,
MessageRole.User,
"Please summarize the Azure REST API specifications Readme");
MCPToolResource mcpToolResource = new(mcpServerLabel);
mcpToolResource.UpdateHeader("SuperSecret", "123456");
ToolResources toolResources = mcpToolResource.ToToolResources();
// Run the agent with MCP tool resources
ThreadRun run = agentClient.Runs.CreateRun(thread, agent, toolResources);
// Handle run execution and tool approvals
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress || run.Status == RunStatus.RequiresAction)
{
Thread.Sleep(TimeSpan.FromMilliseconds(1000));
run = agentClient.Runs.GetRun(thread.Id, run.Id);
if (run.Status == RunStatus.RequiresAction && run.RequiredAction is SubmitToolApprovalAction toolApprovalAction)
{
var toolApprovals = new List<ToolApproval>();
foreach (var toolCall in toolApprovalAction.SubmitToolApproval.ToolCalls)
{
if (toolCall is RequiredMcpToolCall mcpToolCall)
{
Console.WriteLine($"Approving MCP tool call: {mcpToolCall.Name}, Arguments: {mcpToolCall.Arguments}");
toolApprovals.Add(new ToolApproval(mcpToolCall.Id, approve: true)
{
Headers = { ["SuperSecret"] = "123456" }
});
}
}
if (toolApprovals.Count > 0)
{
run = agentClient.Runs.SubmitToolOutputsToRun(thread.Id, run.Id, toolApprovals: toolApprovals);
}
}
}
메시지 인쇄
Pageable<PersistentThreadMessage> messages = agentClient.Messages.GetMessages(
threadId: thread.Id,
order: ListSortOrder.Ascending
);
foreach (PersistentThreadMessage threadMessage in messages)
{
Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
foreach (MessageContent contentItem in threadMessage.ContentItems)
{
if (contentItem is MessageTextContent textItem)
{
Console.Write(textItem.Text);
}
else if (contentItem is MessageImageFileContent imageFileItem)
{
Console.Write($"<image from ID: {imageFileItem.FileId}>");
}
Console.WriteLine();
}
}
선택 사항: 에이전트 삭제
에이전트 작업이 끝나면 다음을 사용하여 삭제할 수 있습니다.
agentClient.Threads.DeleteThread(threadId: thread.Id);
agentClient.Administration.DeleteAgent(agentId: agent.Id);
MCP 도구를 사용하여 에이전트 만들기
다음 코드 샘플은 필요한 가져오기를 설정하고, 관련 MCP 서버 구성을 가져오고, AI Project 클라이언트를 초기화하는 것으로 시작합니다. 그런 다음 에이전트를 만들고, 스레드에 메시지를 추가하고, 에이전트를 실행합니다.
# Import necessary libraries
import os, time
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import (
ListSortOrder,
McpTool,
RequiredMcpToolCall,
RunStepActivityDetails,
SubmitToolApprovalAction,
ToolApproval,
)
# Get MCP server configuration from environment variables
mcp_server_url = os.environ.get("MCP_SERVER_URL", "https://gitmcp.io/Azure/azure-rest-api-specs")
mcp_server_label = os.environ.get("MCP_SERVER_LABEL", "github")
project_client = AIProjectClient(
endpoint=os.environ["PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
)
# Initialize agent MCP tool
mcp_tool = McpTool(
server_label=mcp_server_label,
server_url=mcp_server_url,
allowed_tools=[], # Optional: specify allowed tools
)
# You can also add or remove allowed tools dynamically
search_api_code = "search_azure_rest_api_code"
mcp_tool.allow_tool(search_api_code)
print(f"Allowed tools: {mcp_tool.allowed_tools}")
# Create agent with MCP tool and process agent run
with project_client:
agents_client = project_client.agents
# Create a new agent.
# NOTE: To reuse existing agent, fetch it with get_agent(agent_id)
agent = agents_client.create_agent(
model=os.environ["MODEL_DEPLOYMENT_NAME"],
name="my-mcp-agent",
instructions="You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
tools=mcp_tool.definitions,
)
print(f"Created agent, ID: {agent.id}")
print(f"MCP Server: {mcp_tool.server_label} at {mcp_tool.server_url}")
# Create thread for communication
thread = agents_client.threads.create()
print(f"Created thread, ID: {thread.id}")
# Create message to thread
message = agents_client.messages.create(
thread_id=thread.id,
role="user",
content="Please summarize the Azure REST API specifications Readme",
)
print(f"Created message, ID: {message.id}")
# Create and process agent run in thread with MCP tools
mcp_tool.update_headers("SuperSecret", "123456")
# mcp_tool.set_approval_mode("never") # Uncomment to disable approval requirement
run = agents_client.runs.create(thread_id=thread.id, agent_id=agent.id, tool_resources=mcp_tool.resources)
print(f"Created run, ID: {run.id}")
while run.status in ["queued", "in_progress", "requires_action"]:
time.sleep(1)
run = agents_client.runs.get(thread_id=thread.id, run_id=run.id)
if run.status == "requires_action" and isinstance(run.required_action, SubmitToolApprovalAction):
tool_calls = run.required_action.submit_tool_approval.tool_calls
if not tool_calls:
print("No tool calls provided - cancelling run")
agents_client.runs.cancel(thread_id=thread.id, run_id=run.id)
break
tool_approvals = []
for tool_call in tool_calls:
if isinstance(tool_call, RequiredMcpToolCall):
try:
print(f"Approving tool call: {tool_call}")
tool_approvals.append(
ToolApproval(
tool_call_id=tool_call.id,
approve=True,
headers=mcp_tool.headers,
)
)
except Exception as e:
print(f"Error approving tool_call {tool_call.id}: {e}")
print(f"tool_approvals: {tool_approvals}")
if tool_approvals:
agents_client.runs.submit_tool_outputs(
thread_id=thread.id, run_id=run.id, tool_approvals=tool_approvals
)
print(f"Current run status: {run.status}")
print(f"Run completed with status: {run.status}")
if run.status == "failed":
print(f"Run failed: {run.last_error}")
# Display run steps and tool calls
run_steps = agents_client.run_steps.list(thread_id=thread.id, run_id=run.id)
# Loop through each step
for step in run_steps:
print(f"Step {step['id']} status: {step['status']}")
# Check if there are tool calls in the step details
step_details = step.get("step_details", {})
tool_calls = step_details.get("tool_calls", [])
if tool_calls:
print(" MCP Tool calls:")
for call in tool_calls:
print(f" Tool Call ID: {call.get('id')}")
print(f" Type: {call.get('type')}")
if isinstance(step_details, RunStepActivityDetails):
for activity in step_details.activities:
for function_name, function_definition in activity.tools.items():
print(
f' The function {function_name} with description "{function_definition.description}" will be called.:'
)
if len(function_definition.parameters) > 0:
print(" Function parameters:")
for argument, func_argument in function_definition.parameters.properties.items():
print(f" {argument}")
print(f" Type: {func_argument.type}")
print(f" Description: {func_argument.description}")
else:
print("This function has no parameters")
print() # add an extra newline between steps
# Fetch and log all messages
messages = agents_client.messages.list(thread_id=thread.id, order=ListSortOrder.ASCENDING)
print("\nConversation:")
print("-" * 50)
for msg in messages:
if msg.text_messages:
last_text = msg.text_messages[-1]
print(f"{msg.role.upper()}: {last_text.text.value}")
print("-" * 50)
# Example of dynamic tool management
print(f"\nDemonstrating dynamic tool management:")
print(f"Current allowed tools: {mcp_tool.allowed_tools}")
# Remove a tool
try:
mcp_tool.disallow_tool(search_api_code)
print(f"After removing {search_api_code}: {mcp_tool.allowed_tools}")
except ValueError as e:
print(f"Error removing tool: {e}")
# Clean-up and delete the agent once the run is finished.
# NOTE: Comment out this line if you plan to reuse the agent later.
agents_client.delete_agent(agent.id)
print("Deleted agent")
다음 단계
REST API 빠른 시작에 따라 환경 변수AGENT_TOKENAZURE_AI_FOUNDRY_PROJECT_ENDPOINTAPI_VERSION에 적합한 값을 설정하고 .
MCP 도구를 사용하도록 설정된 에이전트 만들기
에이전트에서 MCP 도구를 사용할 수 있도록 하려면 서버 엔드포인트, 서버 레이블 등을 사용하여 도구를 초기화합니다.
curl --request POST \
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/assistants?api-version=$API_VERSION \
-H "Authorization: Bearer $AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d "{
"instructions": "You are a customer support chatbot. Use the tools provided and your knowledge base to best respond to customer queries.",
"tools": [
{
"type": "mcp",
"server_label": "<unique name for your MCP server>",
"server_url": "<your MCP server URL>",
"allowed_tools": ["<tool_name>"], # optional
}
],
"name": "my-assistant",
"model": "gpt-4o",
}"
스레드 만들기
curl --request POST \
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads?api-version=$API_VERSION \
-H "Authorization: Bearer $AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d ''
스레드에 사용자 질문 추가
curl --request POST \
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=$API_VERSION \
-H "Authorization: Bearer $AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"role": "user",
"content": "<user input related to the MCP server you connect>"
}'
실행을 만들고 출력을 확인합니다.
도구의 헤더를 전달하는 실행을 만듭니다. 모델이 Bing Search를 사용하는 Grounding 도구를 사용하여 사용자의 질문에 대한 응답을 제공하는지 관찰합니다.
require_approval 매개 변수는 선택 사항입니다. 지원되는 값은 다음과 같습니다.
-
always: 개발자는 모든 호출에 대한 승인을 제공해야 합니다. 값을 제공하지 않으면 이 값이 기본값입니다. -
never: 승인이 필요하지 않습니다. -
{"never":[<tool_name_1>, <tool_name_2>]}: 승인이 필요하지 않은 도구 목록을 제공합니다. -
{"always":[<tool_name_1>, <tool_name_2>]}: 승인이 필요한 도구 목록을 제공합니다.
curl --request POST \
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs?api-version=$API_VERSION \
-H "Authorization: Bearer $AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assistant_id": "<agent_id>",
"tool_resources": {
"mcp": [
{
"server_label": "<the same unique name you provided during agent creation>",
"require_approval": "always" #always by default
"headers": {
"Authorization": "Bearer <token>",
}
}
]
},
}'
실행 상태 검색
curl --request GET \
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=$API_VERSION \
-H "Authorization: Bearer $AGENT_TOKEN"
모델이 승인이 필요한 MCP 서버에서 도구를 호출하려고 하면 다음과 같은 requires_action 상태의 실행이 수행됩니다.
{
"id": "run_123",
"object": "thread.run",
...
"status": "requires_action",
...
"required_action": {
"type": "submit_tool_approval",
"submit_tool_approval": {
"tool_calls": [
{
"id": "call_123",
"type": "mcp",
"arguments": "{...}",
"name": "<tool_name>",
"server_label": "<server_label_you_provided>"
}
]
}
},
...
"tools": [
{
"type": "mcp",
"server_label": "<server_label_you_provided>",
"server_url": "<server_url_you_provided>",
"allowed_tools": null
}
],
...
}
승인을 위한 정보에 기초한 결정을 내리려면, 전달할 도구와 인수를 신중하게 검토하세요.
승인 제출
승인하기로 결정한 경우 이전 도구 호출에 대한 approve 값으로 true 매개 변수를 id로 설정합니다.
curl --request POST \
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs/run_abc123/submit_tool_outputs?api-version=$API_VERSION \
-H "Authorization: Bearer $AGENT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tool_approvals": [
{
"tool_call_id": "call_abc123",
"approve": true,
"headers": {
}
}
]
}
에이전트 응답 검색
curl --request GET \
--url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/messages?api-version=$API_VERSION \
-H "Authorization: Bearer $AGENT_TOKEN"