Build AI applications using the Azure AI Projects Python SDK (azure-ai-projects). Use when working with Foundry project clients, creating versioned agents with PromptAgentDefinition, running evaluations, managing connections/deployments/datasets/indexes, or using OpenAI-compatible clients. This is the high-level Foundry SDK - for low-level agent operations, use azure-ai-agents-python skill.
Add this skill
npx mdskills install sickn33/azure-ai-projects-pyComprehensive Azure AI Foundry SDK reference with excellent structure, clear examples, and proper scoping
1---2name: azure-ai-projects-py3description: Build AI applications using the Azure AI Projects Python SDK (azure-ai-projects). Use when working with Foundry project clients, creating versioned agents with PromptAgentDefinition, running evaluations, managing connections/deployments/datasets/indexes, or using OpenAI-compatible clients. This is the high-level Foundry SDK - for low-level agent operations, use azure-ai-agents-python skill.4package: azure-ai-projects5---67# Azure AI Projects Python SDK (Foundry SDK)89Build AI applications on Microsoft Foundry using the `azure-ai-projects` SDK.1011## Installation1213```bash14pip install azure-ai-projects azure-identity15```1617## Environment Variables1819```bash20AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"21AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"22```2324## Authentication2526```python27import os28from azure.identity import DefaultAzureCredential29from azure.ai.projects import AIProjectClient3031credential = DefaultAzureCredential()32client = AIProjectClient(33 endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],34 credential=credential,35)36```3738## Client Operations Overview3940| Operation | Access | Purpose |41|-----------|--------|---------|42| `client.agents` | `.agents.*` | Agent CRUD, versions, threads, runs |43| `client.connections` | `.connections.*` | List/get project connections |44| `client.deployments` | `.deployments.*` | List model deployments |45| `client.datasets` | `.datasets.*` | Dataset management |46| `client.indexes` | `.indexes.*` | Index management |47| `client.evaluations` | `.evaluations.*` | Run evaluations |48| `client.red_teams` | `.red_teams.*` | Red team operations |4950## Two Client Approaches5152### 1. AIProjectClient (Native Foundry)5354```python55from azure.ai.projects import AIProjectClient5657client = AIProjectClient(58 endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],59 credential=DefaultAzureCredential(),60)6162# Use Foundry-native operations63agent = client.agents.create_agent(64 model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],65 name="my-agent",66 instructions="You are helpful.",67)68```6970### 2. OpenAI-Compatible Client7172```python73# Get OpenAI-compatible client from project74openai_client = client.get_openai_client()7576# Use standard OpenAI API77response = openai_client.chat.completions.create(78 model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],79 messages=[{"role": "user", "content": "Hello!"}],80)81```8283## Agent Operations8485### Create Agent (Basic)8687```python88agent = client.agents.create_agent(89 model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],90 name="my-agent",91 instructions="You are a helpful assistant.",92)93```9495### Create Agent with Tools9697```python98from azure.ai.agents import CodeInterpreterTool, FileSearchTool99100agent = client.agents.create_agent(101 model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],102 name="tool-agent",103 instructions="You can execute code and search files.",104 tools=[CodeInterpreterTool(), FileSearchTool()],105)106```107108### Versioned Agents with PromptAgentDefinition109110```python111from azure.ai.projects.models import PromptAgentDefinition112113# Create a versioned agent114agent_version = client.agents.create_version(115 agent_name="customer-support-agent",116 definition=PromptAgentDefinition(117 model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],118 instructions="You are a customer support specialist.",119 tools=[], # Add tools as needed120 ),121 version_label="v1.0",122)123```124125See [references/agents.md](references/agents.md) for detailed agent patterns.126127## Tools Overview128129| Tool | Class | Use Case |130|------|-------|----------|131| Code Interpreter | `CodeInterpreterTool` | Execute Python, generate files |132| File Search | `FileSearchTool` | RAG over uploaded documents |133| Bing Grounding | `BingGroundingTool` | Web search (requires connection) |134| Azure AI Search | `AzureAISearchTool` | Search your indexes |135| Function Calling | `FunctionTool` | Call your Python functions |136| OpenAPI | `OpenApiTool` | Call REST APIs |137| MCP | `McpTool` | Model Context Protocol servers |138| Memory Search | `MemorySearchTool` | Search agent memory stores |139| SharePoint | `SharepointGroundingTool` | Search SharePoint content |140141See [references/tools.md](references/tools.md) for all tool patterns.142143## Thread and Message Flow144145```python146# 1. Create thread147thread = client.agents.threads.create()148149# 2. Add message150client.agents.messages.create(151 thread_id=thread.id,152 role="user",153 content="What's the weather like?",154)155156# 3. Create and process run157run = client.agents.runs.create_and_process(158 thread_id=thread.id,159 agent_id=agent.id,160)161162# 4. Get response163if run.status == "completed":164 messages = client.agents.messages.list(thread_id=thread.id)165 for msg in messages:166 if msg.role == "assistant":167 print(msg.content[0].text.value)168```169170## Connections171172```python173# List all connections174connections = client.connections.list()175for conn in connections:176 print(f"{conn.name}: {conn.connection_type}")177178# Get specific connection179connection = client.connections.get(connection_name="my-search-connection")180```181182See [references/connections.md](references/connections.md) for connection patterns.183184## Deployments185186```python187# List available model deployments188deployments = client.deployments.list()189for deployment in deployments:190 print(f"{deployment.name}: {deployment.model}")191```192193See [references/deployments.md](references/deployments.md) for deployment patterns.194195## Datasets and Indexes196197```python198# List datasets199datasets = client.datasets.list()200201# List indexes202indexes = client.indexes.list()203```204205See [references/datasets-indexes.md](references/datasets-indexes.md) for data operations.206207## Evaluation208209```python210# Using OpenAI client for evals211openai_client = client.get_openai_client()212213# Create evaluation with built-in evaluators214eval_run = openai_client.evals.runs.create(215 eval_id="my-eval",216 name="quality-check",217 data_source={218 "type": "custom",219 "item_references": [{"item_id": "test-1"}],220 },221 testing_criteria=[222 {"type": "fluency"},223 {"type": "task_adherence"},224 ],225)226```227228See [references/evaluation.md](references/evaluation.md) for evaluation patterns.229230## Async Client231232```python233from azure.ai.projects.aio import AIProjectClient234235async with AIProjectClient(236 endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],237 credential=DefaultAzureCredential(),238) as client:239 agent = await client.agents.create_agent(...)240 # ... async operations241```242243See [references/async-patterns.md](references/async-patterns.md) for async patterns.244245## Memory Stores246247```python248# Create memory store for agent249memory_store = client.agents.create_memory_store(250 name="conversation-memory",251)252253# Attach to agent for persistent memory254agent = client.agents.create_agent(255 model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],256 name="memory-agent",257 tools=[MemorySearchTool()],258 tool_resources={"memory": {"store_ids": [memory_store.id]}},259)260```261262## Best Practices2632641. **Use context managers** for async client: `async with AIProjectClient(...) as client:`2652. **Clean up agents** when done: `client.agents.delete_agent(agent.id)`2663. **Use `create_and_process`** for simple runs, **streaming** for real-time UX2674. **Use versioned agents** for production deployments2685. **Prefer connections** for external service integration (AI Search, Bing, etc.)269270## SDK Comparison271272| Feature | `azure-ai-projects` | `azure-ai-agents` |273|---------|---------------------|-------------------|274| Level | High-level (Foundry) | Low-level (Agents) |275| Client | `AIProjectClient` | `AgentsClient` |276| Versioning | `create_version()` | Not available |277| Connections | Yes | No |278| Deployments | Yes | No |279| Datasets/Indexes | Yes | No |280| Evaluation | Via OpenAI client | No |281| When to use | Full Foundry integration | Standalone agent apps |282283## Reference Files284285- [references/agents.md](references/agents.md): Agent operations with PromptAgentDefinition286- [references/tools.md](references/tools.md): All agent tools with examples287- [references/evaluation.md](references/evaluation.md): Evaluation operations overview288- [references/built-in-evaluators.md](references/built-in-evaluators.md): Complete built-in evaluator reference289- [references/custom-evaluators.md](references/custom-evaluators.md): Code and prompt-based evaluator patterns290- [references/connections.md](references/connections.md): Connection operations291- [references/deployments.md](references/deployments.md): Deployment enumeration292- [references/datasets-indexes.md](references/datasets-indexes.md): Dataset and index operations293- [references/async-patterns.md](references/async-patterns.md): Async client usage294- [references/api-reference.md](references/api-reference.md): Complete API reference for all 373 SDK exports (v2.0.0b4)295- [scripts/run_batch_evaluation.py](scripts/run_batch_evaluation.py): CLI tool for batch evaluations296
Full transparency — inspect the skill content before installing.