{"slug":"azure-ai-projects-py","title":"azure-ai-projects-py","summary":"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-compatibl","platform":"GitHub Copilot","tags":[],"authorName":"Ciza","authorSlug":"ciza","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-12T21:05:05.073271Z","repo":{"url":"https://github.com/microsoft/skills","stars":3052,"forks":351,"license":"MIT","updatedAt":"2026-09-24T16:38:17Z"},"bodyHtml":"
\n

name: azure-ai-projects-py\ndescription: 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.\nlicense: MIT\nmetadata:\nauthor: Microsoft\nversion: \"1.0.0\"\npackage: azure-ai-projects

\n

Azure AI Projects Python SDK (Foundry SDK)

\n

Build AI applications on Microsoft Foundry using the azure-ai-projects SDK.

\n

Installation

\n
pip install azure-ai-projects azure-identity\n
\n

Environment Variables

\n
AZURE_AI_PROJECT_ENDPOINT=\"https://<resource>.services.ai.azure.com/api/projects/<project>\"  # Required for all auth methods\nAZURE_AI_MODEL_DEPLOYMENT_NAME=\"gpt-4o-mini\"  # Required for all auth methods\nAZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production\n
\n

Authentication & Lifecycle

\n
\n

\uD83D\uDD11 Two rules apply to every code sample below:

\n
    \n
  1. Prefer DefaultAzureCredential. It works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.\n
      \n
    • Local dev: DefaultAzureCredential works as-is.
      • \n
    • Production: set AZURE_TOKEN_CREDENTIALS=prod (or AZURE_TOKEN_CREDENTIALS=<specific_credential>) to constrain the credential chain to production-safe credentials.
      • \n
    \n
    2. \n
  2. Wrap every client in a context manager so HTTP transports, sockets, and token caches are released deterministically:\n
      \n
    • Sync: with <Client>(...) as client:
      • \n
    • Async: async with <Client>(...) as client: and async with DefaultAzureCredential() as credential: (from azure.identity.aio)
      • \n
    \n
    3. \n
\n

Snippets may abbreviate this setup, but production code should always follow both rules.

\n
\n
import os\nfrom azure.identity import DefaultAzureCredential, ManagedIdentityCredential\nfrom azure.ai.projects import AIProjectClient\n\n# Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>\ncredential = DefaultAzureCredential()\n# Or use a specific credential directly in production:\n# See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes\n# credential = ManagedIdentityCredential()\nwith AIProjectClient(\n    endpoint=os.environ[\"AZURE_AI_PROJECT_ENDPOINT\"],\n    credential=credential,\n) as client:\n    deployments = list(client.deployments.list())\n
\n

Client Operations Overview

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OperationAccessPurpose
client.agents.agents.*Agent CRUD, versions, threads, runs
client.connections.connections.*List/get project connections
client.deployments.deployments.*List model deployments
client.datasets.datasets.*Dataset management
client.indexes.indexes.*Index management
client.evaluations.evaluations.*Run evaluations
client.red_teams.red_teams.*Red team operations
\n

Two Client Approaches

\n

1. AIProjectClient (Native Foundry)

\n
from azure.ai.projects import AIProjectClient\n\nwith AIProjectClient(\n    endpoint=os.environ[\"AZURE_AI_PROJECT_ENDPOINT\"],\n    credential=DefaultAzureCredential(),\n) as client:\n    # Use Foundry-native operations\n    agent = client.agents.create_agent(\n        model=os.environ[\"AZURE_AI_MODEL_DEPLOYMENT_NAME\"],\n        name=\"my-agent\",\n        instructions=\"You are helpful.\",\n    )\n
\n

2. OpenAI-Compatible Client

\n
# Get OpenAI-compatible client from project\nopenai_client = client.get_openai_client()\n\n# Use standard OpenAI API\nresponse = openai_client.chat.completions.create(\n    model=os.environ[\"AZURE_AI_MODEL_DEPLOYMENT_NAME\"],\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}],\n)\n
\n

Agent Operations

\n

Create Agent (Basic)

\n
agent = client.agents.create_agent(\n    model=os.environ[\"AZURE_AI_MODEL_DEPLOYMENT_NAME\"],\n    name=\"my-agent\",\n    instructions=\"You are a helpful assistant.\",\n)\n
\n

Create Agent with Tools

\n
from azure.ai.agents.models import CodeInterpreterTool, FileSearchTool\n\nagent = client.agents.create_agent(\n    model=os.environ[\"AZURE_AI_MODEL_DEPLOYMENT_NAME\"],\n    name=\"tool-agent\",\n    instructions=\"You can execute code and search files.\",\n    tools=[CodeInterpreterTool(), FileSearchTool()],\n)\n
\n

Versioned Agents with PromptAgentDefinition

\n
from azure.ai.projects.models import PromptAgentDefinition\n\n# Create a versioned agent\nagent_version = client.agents.create_version(\n    agent_name=\"customer-support-agent\",\n    definition=PromptAgentDefinition(\n        model=os.environ[\"AZURE_AI_MODEL_DEPLOYMENT_NAME\"],\n        instructions=\"You are a customer support specialist.\",\n        tools=[],  # Add tools as needed\n    ),\n    version_label=\"v1.0\",\n)\n
\n

See references/agents.md for detailed agent patterns.

\n

Tools Overview

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ToolClassUse Case
Code InterpreterCodeInterpreterToolExecute Python, generate files
File SearchFileSearchToolRAG over uploaded documents
Bing GroundingBingGroundingToolWeb search (requires connection)
Azure AI SearchAzureAISearchToolSearch your indexes
Function CallingFunctionToolCall your Python functions
OpenAPIOpenApiToolCall REST APIs
MCPMcpToolModel Context Protocol servers
Memory SearchMemorySearchToolSearch agent memory stores
SharePointSharepointGroundingToolSearch SharePoint content
\n

See references/tools.md for all tool patterns.

\n

Thread and Message Flow

\n
# 1. Create thread\nthread = client.agents.threads.create()\n\n# 2. Add message\nclient.agents.messages.create(\n    thread_id=thread.id,\n    role=\"user\",\n    content=\"What's the weather like?\",\n)\n\n# 3. Create and process run\nrun = client.agents.runs.create_and_process(\n    thread_id=thread.id,\n    agent_id=agent.id,\n)\n\n# 4. Get response\nif run.status == \"completed\":\n    messages = client.agents.messages.list(thread_id=thread.id)\n    for msg in messages:\n        if msg.role == \"assistant\":\n            print(msg.content[0].text.value)\n
\n

Connections

\n
# List all connections\nconnections = client.connections.list()\nfor conn in connections:\n    print(f\"{conn.name}: {conn.connection_type}\")\n\n# Get specific connection\nconnection = client.connections.get(connection_name=\"my-search-connection\")\n
\n

See references/connections.md for connection patterns.

\n

Deployments

\n
# List available model deployments\ndeployments = client.deployments.list()\nfor deployment in deployments:\n    print(f\"{deployment.name}: {deployment.model}\")\n
\n

See references/deployments.md for deployment patterns.

\n

Datasets and Indexes

\n
# List datasets\ndatasets = client.datasets.list()\n\n# List indexes\nindexes = client.indexes.list()\n
\n

See references/datasets-indexes.md for data operations.

\n

Evaluation

\n
# Using OpenAI client for evals\nopenai_client = client.get_openai_client()\n\n# Create evaluation with built-in evaluators\neval_run = openai_client.evals.runs.create(\n    eval_id=\"my-eval\",\n    name=\"quality-check\",\n    data_source={\n        \"type\": \"custom\",\n        \"item_references\": [{\"item_id\": \"test-1\"}],\n    },\n    testing_criteria=[\n        {\"type\": \"fluency\"},\n        {\"type\": \"task_adherence\"},\n    ],\n)\n
\n

See references/evaluation.md for evaluation patterns.

\n

Async Client

\n
from azure.ai.projects.aio import AIProjectClient\n\nasync with AIProjectClient(\n    endpoint=os.environ[\"AZURE_AI_PROJECT_ENDPOINT\"],\n    credential=DefaultAzureCredential(),\n) as client:\n    agent = await client.agents.create_agent(...)\n    # ... async operations\n
\n

See references/async-patterns.md for async patterns.

\n

Memory Stores

\n
# Create memory store for agent\nmemory_store = client.agents.create_memory_store(\n    name=\"conversation-memory\",\n)\n\n# Attach to agent for persistent memory\nagent = client.agents.create_agent(\n    model=os.environ[\"AZURE_AI_MODEL_DEPLOYMENT_NAME\"],\n    name=\"memory-agent\",\n    tools=[MemorySearchTool()],\n    tool_resources={\"memory\": {\"store_ids\": [memory_store.id]}},\n)\n
\n

Best Practices

\n
    \n
  1. Pick sync OR async and stay consistent. Do not mix azure.ai.projects sync clients with azure.ai.projects.aio async clients in the same call path. Choose one mode per module.
    2. \n
  2. Always use context managers for clients and async credentials. Wrap every client in with AIProjectClient(...) as client: (sync) or async with AIProjectClient(...) as client: (async). For async DefaultAzureCredential from azure.identity.aio, also use async with credential: so tokens and transports are cleaned up.
    3. \n
  3. Clean up agents when done: client.agents.delete_agent(agent.id)
    4. \n
  4. Use create_and_process for simple runs, streaming for real-time UX
    5. \n
  5. Use versioned agents for production deployments
    6. \n
  6. Prefer connections for external service integration (AI Search, Bing, etc.)
    7. \n
\n

SDK Comparison

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Featureazure-ai-projectsazure-ai-agents
LevelHigh-level (Foundry)Low-level (Agents)
ClientAIProjectClientAgentsClient
Versioningcreate_version()Not available
ConnectionsYesNo
DeploymentsYesNo
Datasets/IndexesYesNo
EvaluationVia OpenAI clientNo
When to useFull Foundry integrationStandalone agent apps
\n

Reference Files

\n\n","files":[{"path":"references/agents.md","sizeBytes":6869,"isText":true},{"path":"references/api-reference.md","sizeBytes":27988,"isText":true},{"path":"references/async-patterns.md","sizeBytes":7009,"isText":true},{"path":"references/built-in-evaluators.md","sizeBytes":11759,"isText":true},{"path":"references/connections.md","sizeBytes":4767,"isText":true},{"path":"references/custom-evaluators.md","sizeBytes":14411,"isText":true},{"path":"references/datasets-indexes.md","sizeBytes":4272,"isText":true},{"path":"references/deployments.md","sizeBytes":3569,"isText":true},{"path":"references/evaluation.md","sizeBytes":10975,"isText":true},{"path":"references/tools.md","sizeBytes":12016,"isText":true},{"path":"scripts/run_batch_evaluation.py","sizeBytes":12507,"isText":true},{"path":"SKILL.md","sizeBytes":11058,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-08-12T21:49:43.689265Z","sha256":"D5504FF8116A4CB0F9A06998A82A4953FD4298056691BAFB56C4AE4084C82BD8","sizeBytes":35773},"review":null,"source":{"repositoryUrl":"https://github.com/microsoft/skills","path":".github/plugins/azure-sdk-python/skills/azure-ai-projects-py","license":"MIT","commit":"23d0dac5f83f268166a17f0bc7dc6c73dc348a33","subtreeSha":"127ABA26D3A0796A4AB552D9C90468D78E433119F249EBF3E558733D7D1EF360","lastSyncedAt":"2026-09-25T06:48:53.330584Z"},"reviewedAt":"2026-08-12T21:51:41.895233Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-python/skills/azure-ai-projects-py"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart"},{"target":"git","command":"git clone https://github.com/microsoft/skills.git"}]}