1# Microsoft Foundry - Python SDK Guide
2 
3Python-specific implementations for working with Microsoft Foundry.
4 
5**Table of Contents:** [Prerequisites](#prerequisites) · [Model Discovery and Deployment](#model-discovery-and-deployment-mcp) · [RAG Agent with Azure AI Search](#rag-agent-with-azure-ai-search) · [Creating Agents](#creating-agents) · [Agent Evaluation](#agent-evaluation) · [Knowledge Index Operations](#knowledge-index-operations-mcp) · [Best Practices](#best-practices) · [Error Handling](#error-handling)
6 
7## Prerequisites
8 
9```bash
10pip install azure-ai-projects azure-identity azure-ai-inference openai azure-ai-evaluation python-dotenv
11```
12 
13### Environment Variables
14 
15```bash
16PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
17MODEL_DEPLOYMENT_NAME=gpt-4o
18AZURE_AI_SEARCH_CONNECTION_NAME=my-search-connection
19AI_SEARCH_INDEX_NAME=my-index
20AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com
21AZURE_OPENAI_DEPLOYMENT=gpt-4o
22```
23 
24## Model Discovery and Deployment (MCP)
25 
26```python
27foundry_models_list()                              # All models
28foundry_models_list(publisher="OpenAI")             # Filter by publisher
29foundry_models_list(search_for_free_playground=True) # Free playground models
30 
31foundry_models_deploy(
32    resource_group="my-rg", deployment="gpt-4o-deployment",
33    model_name="gpt-4o", model_format="OpenAI",
34    azure_ai_services="my-foundry-resource",
35    model_version="2024-05-13", sku_capacity=10, scale_type="Standard"
36)
37```
38 
39## RAG Agent with Azure AI Search
40 
41> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](../auth-best-practices.md) for production patterns.
42 
43```python
44import os
45from azure.ai.projects import AIProjectClient
46from azure.identity import DefaultAzureCredential
47from azure.ai.agents.models import (
48    AzureAISearchToolDefinition, AzureAISearchToolResource,
49    AISearchIndexResource, AzureAISearchQueryType,
50)
51 
52project_client = AIProjectClient(
53    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
54    credential=DefaultAzureCredential(),
55)
56 
57azs_connection = project_client.connections.get(
58    os.environ["AZURE_AI_SEARCH_CONNECTION_NAME"]
59)
60 
61agent = project_client.agents.create_agent(
62    model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
63    name="RAGAgent",
64    instructions="You are a helpful assistant. Use the knowledge base to answer. "
65        "Provide citations as: `[message_idx:search_idx†source]`.",
66    tools=[AzureAISearchToolDefinition(
67        azure_ai_search=AzureAISearchToolResource(indexes=[
68            AISearchIndexResource(
69                index_connection_id=azs_connection.id,
70                index_name=os.environ["AI_SEARCH_INDEX_NAME"],
71                query_type=AzureAISearchQueryType.HYBRID,
72            ),
73        ])
74    )],
75)
76```
77 
78### Querying a RAG Agent (Streaming)
79 
80```python
81openai_client = project_client.get_openai_client()
82 
83stream = openai_client.responses.create(
84    stream=True, tool_choice="required", input="Your question here",
85    extra_body={"agent": {"name": agent.name, "type": "agent_reference"}},
86)
87for event in stream:
88    if event.type == "response.output_text.delta":
89        print(event.delta, end="", flush=True)
90    elif event.type == "response.output_item.done":
91        if event.item.type == "message" and event.item.content[-1].type == "output_text":
92            for ann in event.item.content[-1].annotations:
93                if ann.type == "url_citation":
94                    print(f"\nCitation: {ann.url}")
95```
96 
97## Creating Agents
98 
99### Basic Agent
100 
101```python
102agent = project_client.agents.create_agent(
103    model=os.environ["MODEL_DEPLOYMENT_NAME"],
104    name="my-agent",
105    instructions="You are a helpful assistant.",
106)
107```
108 
109### Agent with Custom Function Tools
110 
111```python
112from azure.ai.agents.models import FunctionTool, ToolSet
113 
114def get_weather(location: str, unit: str = "celsius") -> str:
115    """Get the current weather for a location."""
116    return f"Sunny and 22°{unit[0].upper()} in {location}"
117 
118functions = FunctionTool([get_weather])
119toolset = ToolSet()
120toolset.add(functions)
121 
122agent = project_client.agents.create_agent(
123    model=os.environ["MODEL_DEPLOYMENT_NAME"],
124    name="function-agent",
125    instructions="You are a helpful assistant with tool access.",
126    toolset=toolset,
127)
128```
129 
130### Agent with Web Search
131 
132```python
133from azure.ai.projects.models import (
134    PromptAgentDefinition, WebSearchPreviewTool, ApproximateLocation,
135)
136 
137agent = project_client.agents.create_version(
138    agent_name="WebSearchAgent",
139    definition=PromptAgentDefinition(
140        model=os.environ["MODEL_DEPLOYMENT_NAME"],
141        instructions="Search the web for current information. Provide sources.",
142        tools=[
143            WebSearchPreviewTool(
144                user_location=ApproximateLocation(
145                    country="US", city="Seattle", region="Washington"
146                )
147            )
148        ],
149    ),
150)
151```
152 
153> 💡 **Tip:** `WebSearchPreviewTool` requires no external resource or connection. For Bing Grounding (which requires a dedicated Bing resource and project connection), see [Bing Grounding reference](../../foundry-agent/create/references/tool-bing-grounding.md).
154 
155### Interacting with Agents
156 
157```python
158from azure.ai.agents.models import ListSortOrder
159 
160thread = project_client.agents.threads.create()
161project_client.agents.messages.create(thread_id=thread.id, role="user", content="Hello")
162 
163run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
164if run.status == "failed":
165    print(f"Run failed: {run.last_error}")
166 
167messages = project_client.agents.messages.list(thread_id=thread.id, order=ListSortOrder.ASCENDING)
168for msg in messages:
169    if msg.text_messages:
170        print(f"{msg.role}: {msg.text_messages[-1].text.value}")
171 
172project_client.agents.delete_agent(agent.id)
173```
174 
175## Agent Evaluation
176 
177### Single Response Evaluation (MCP)
178 
179```python
180foundry_agents_query_and_evaluate(
181    agent_id="<agent-id>", query="What's the weather?",
182    endpoint="https://my-foundry.services.ai.azure.com/api/projects/my-project",
183    azure_openai_endpoint="https://my-openai.openai.azure.com",
184    azure_openai_deployment="gpt-4o",
185    evaluators="intent_resolution,task_adherence,tool_call_accuracy"
186)
187 
188foundry_agents_evaluate(
189    query="What's the weather?", response="Sunny and 22°C.",
190    evaluator="intent_resolution",
191    azure_openai_endpoint="https://my-openai.openai.azure.com",
192    azure_openai_deployment="gpt-4o"
193)
194```
195 
196### Batch Evaluation
197 
198```python
199from azure.ai.evaluation import AIAgentConverter, IntentResolutionEvaluator, evaluate
200 
201converter = AIAgentConverter(project_client)
202converter.prepare_evaluation_data(thread_ids=["t1", "t2", "t3"], filename="eval_data.jsonl")
203 
204result = evaluate(
205    data="eval_data.jsonl",
206    evaluators={
207        "intent_resolution": IntentResolutionEvaluator(
208            azure_openai_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
209            azure_openai_deployment=os.environ["AZURE_OPENAI_DEPLOYMENT"]
210        ),
211    },
212    output_path="./eval_results"
213)
214print(f"Results: {result['studio_url']}")
215```
216 
217> 💡 **Tip:** Continuous evaluation requires project managed identity with **Azure AI User** role and Application Insights connected to the project.
218 
219## Knowledge Index Operations (MCP)
220 
221```python
222foundry_knowledge_index_list(endpoint="<project-endpoint>")
223foundry_knowledge_index_schema(endpoint="<project-endpoint>", index="my-index")
224```
225 
226## Best Practices
227 
2281. **Never hardcode credentials** — use environment variables and `python-dotenv`
2292. **Check `run.status`** and handle `HttpResponseError` exceptions
2303. **Reuse `AIProjectClient`** instances — don't create new ones per request
2314. **Use type hints** in custom functions for better tool integration
2325. **Use context managers** for agent cleanup
233 
234## Error Handling
235 
236```python
237from azure.core.exceptions import HttpResponseError
238 
239try:
240    agent = project_client.agents.create_agent(
241        model=os.environ["MODEL_DEPLOYMENT_NAME"],
242        name="my-agent", instructions="You are helpful."
243    )
244except HttpResponseError as e:
245    if e.status_code == 429:
246        print("Rate limited — wait and retry with exponential backoff.")
247    elif e.status_code == 401:
248        print("Authentication failed — check credentials.")
249    else:
250        print(f"Error: {e.message}")
251```
252 
253### Context Manager for Agent Cleanup
254 
255```python
256from contextlib import contextmanager
257 
258@contextmanager
259def temporary_agent(project_client, **kwargs):
260    agent = project_client.agents.create_agent(**kwargs)
261    try:
262        yield agent
263    finally:
264        project_client.agents.delete_agent(agent.id)
265```
266