|
| 1 | +After you understand the capabilities of the Azure Language MCP server, the next step is to connect it to an agent and start using it. This involves creating an agent in Microsoft Foundry, connecting the Language MCP tool, testing it in the agent playground, and optionally building a client application to interact with the agent programmatically. |
| 2 | + |
| 3 | +## Create a Foundry project and agent |
| 4 | + |
| 5 | +To use the Azure Language MCP server, you first need a Microsoft Foundry project with a deployed model. |
| 6 | + |
| 7 | +1. In the [Microsoft Foundry portal](https://ai.azure.com), create a new project (or use an existing one). |
| 8 | +1. Deploy a model (such as **gpt-4.1**) that your agent will use for reasoning and generating responses. |
| 9 | +1. Create an agent and give it instructions that describe its purpose. For example: |
| 10 | + |
| 11 | + ``` |
| 12 | + You are an AI agent that assists users by helping them analyze and summarize text. |
| 13 | + ``` |
| 14 | +
|
| 15 | +The agent is now ready to receive tool connections. |
| 16 | +
|
| 17 | +## Connect the Azure Language MCP server |
| 18 | +
|
| 19 | +You connect the Azure Language MCP server to your agent through the **Tools** page in the Foundry portal. |
| 20 | +
|
| 21 | +1. In the navigation pane, select the **Tools** page. |
| 22 | +1. Select **Connect a tool** and choose **Azure Language in Foundry Tools** from the catalog. |
| 23 | +1. Configure the connection with the following settings: |
| 24 | + - **Foundry resource name**: The name of your Foundry resource (for example, `myproject-resource`). |
| 25 | + - **Authentication**: Key-based. |
| 26 | + - **Credential** (`Ocp-Apim-Subscription-Key`): The key for your Foundry project. |
| 27 | +
|
| 28 | +1. Wait for the connection to be created, then select **Use in an agent** and choose your agent. |
| 29 | +
|
| 30 | +:::image type="content" source="../media/azure-language-tool-catalog.png" alt-text="Screenshot of the Tools catalog in the Foundry portal showing the Azure Language in Foundry Tools connection configuration."::: |
| 31 | +
|
| 32 | +The agent now has access to all the text analysis tools exposed by the Azure Language MCP server. |
| 33 | +
|
| 34 | +> [!TIP] |
| 35 | +> You can find the project key on the project home page in the Foundry portal. |
| 36 | +
|
| 37 | +## Update agent instructions |
| 38 | +
|
| 39 | +After connecting the Language MCP tool, update the agent's instructions to direct it to use the tool: |
| 40 | +
|
| 41 | +``` |
| 42 | +You are an AI agent that assists users by helping them analyze and summarize text. Use the Azure Language tool to perform text analysis tasks. |
| 43 | +``` |
| 44 | +
|
| 45 | +This instruction helps the agent understand that it should use the connected tool when processing text analysis requests. |
| 46 | +
|
| 47 | +## Test in the agent playground |
| 48 | +
|
| 49 | +The agent playground in the Foundry portal provides an interactive environment for testing your agent before deploying it in an application. |
| 50 | +
|
| 51 | +When you send a prompt that requires text analysis, the agent: |
| 52 | +
|
| 53 | +1. Identifies the tasks needed (for example, summarization and entity recognition). |
| 54 | +1. Calls the appropriate Azure Language MCP tool(s). |
| 55 | +1. Returns a combined response. |
| 56 | +
|
| 57 | +The first time the agent uses an MCP tool, you're prompted to **approve** the tool usage. You can approve the tool for a single use, or select **Always approve all Azure Language in Foundry Tools tools** to skip future approval prompts. |
| 58 | +
|
| 59 | +After the agent responds, you can review the **Logs** pane to verify which tools were used. The logs show each MCP tool call, the input that was sent, and the result that was returned. |
| 60 | +
|
| 61 | +## Build a client application |
| 62 | +
|
| 63 | +While the agent playground is useful for testing, you typically want to build a client application that uses the agent programmatically. The Microsoft Foundry SDK supports this through the OpenAI Responses API. |
| 64 | +
|
| 65 | +To build a client application, you use the `azure-ai-projects` and `azure-identity` packages. The general pattern is: |
| 66 | +
|
| 67 | +1. Create an `AIProjectClient` using your Foundry project endpoint and `DefaultAzureCredential` (which uses your Azure CLI credentials in development). |
| 68 | +1. Get an OpenAI client from the project client by calling `get_openai_client()`. |
| 69 | +1. Call `responses.create()` to send a user prompt to the agent. |
| 70 | +
|
| 71 | +The key part is how you reference the agent — you specify it by name in the `extra_body` parameter: |
| 72 | +
|
| 73 | +```python |
| 74 | +response = openai_client.responses.create( |
| 75 | + input=[{"role": "user", "content": user_prompt}], |
| 76 | + extra_body={ |
| 77 | + "agent_reference": { |
| 78 | + "name": "Text-Analysis-Agent", |
| 79 | + "type": "agent_reference" |
| 80 | + } |
| 81 | + }, |
| 82 | +) |
| 83 | +
|
| 84 | +print(response.output_text) |
| 85 | +``` |
| 86 | + |
| 87 | +The agent processes the prompt, calls the appropriate MCP tools, and returns the result in `output_text`. You can also inspect the full response JSON (using `response.model_dump_json()`) to see which tools the agent called — for example, `extract_named_entities_from_text` or `detect_sentiment_from_text` — along with the arguments and results for each tool call. |
| 88 | + |
| 89 | +### Connect the MCP server in code |
| 90 | + |
| 91 | +Instead of connecting the Azure Language MCP server through the Foundry portal, you can also define the MCP tool connection directly in code when you create an agent. Use the `MCPTool` class from the `azure-ai-projects` SDK to specify the server label, URL, and allowed tools: |
| 92 | + |
| 93 | +```python |
| 94 | +from azure.ai.projects.models import MCPTool |
| 95 | + |
| 96 | +mcp_tool = MCPTool( |
| 97 | + server_label="azure-language", |
| 98 | + server_url="https://{foundry-resource-name}.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview", |
| 99 | + require_approval="always", |
| 100 | +) |
| 101 | +``` |
| 102 | + |
| 103 | +You then pass the `mcp_tool` when creating the agent through the SDK. This approach is useful when you want to manage tool connections as part of your application code rather than configuring them manually in the portal. You can also use the `allowed_tools` property on `MCPTool` to restrict which specific Language tools the agent can call. |
| 104 | + |
| 105 | +## Tool selection with multi-task prompts |
| 106 | + |
| 107 | +When a user's prompt involves multiple text analysis tasks, the agent can call multiple tools in a single turn. For example, the prompt: |
| 108 | + |
| 109 | +> "Tell me what entities and dates are mentioned in this review, and whether it is positive or negative." |
| 110 | +
|
| 111 | +This prompt requires both entity recognition and sentiment analysis. The agent identifies both tasks, calls the appropriate tools (`extract_named_entities_from_text` and `detect_sentiment_from_text`), and combines the results into a single response. |
| 112 | + |
| 113 | +Each tool call goes through the MCP server independently, and the agent synthesizes the outputs into a coherent answer for the user. |
0 commit comments