---

name: ms-foundry description: Build GenAI applications with Microsoft Foundry (Azure AI Foundry). Use when creating chat completions, agents, file search, code interpreter, Bing grounding, or AI model deployments using the Foundry SDK (azure-ai-projects). Covers AIProjectClient, agent service, threads, runs, messages, tools, and OpenAI-compatible endpoints.

Microsoft Foundry Skill

Build production GenAI applications using Microsoft Foundry SDK (Python).

Prerequisites

• Python 3.10+
• Azure account with Foundry resource
• Azure CLI authenticated (az login)
• Role: Azure AI User or Contributor on Foundry project

Installation

Copypip install azure-ai-projects azure-identity openai

Environment Variables

Copy# Foundry project endpoint (from portal Overview > Libraries > Foundry)
export PROJECT_ENDPOINT="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>"

# Model deployment name (from Models + Endpoints in portal)
export MODEL_DEPLOYMENT_NAME="gpt-4o"

Quick Start: Chat Completion

Copyfrom azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project = AIProjectClient(
    endpoint="https://<resource-name>.ai.azure.com/api/projects/<project-name>",
    credential=DefaultAzureCredential(),
)

# Get OpenAI client from project
models = project.get_openai_client(api_version="2024-10-21")

response = models.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant"},
        {"role": "user", "content": "Explain quantum computing in simple terms"},
    ],
)

print(response.choices[0].message.content)

Quick Start: Create Agent

Copyfrom azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import ListSortOrder

project = AIProjectClient(
    endpoint="https://<resource-name>.ai.azure.com/api/projects/<project-name>",
    credential=DefaultAzureCredential(),
)

# Create agent
agent = project.agents.create_agent(
    model="gpt-4o",
    name="my-agent",
    instructions="You are a helpful writing assistant"
)

# Create thread and message
thread = project.agents.threads.create()
project.agents.messages.create(
    thread_id=thread.id,
    role="user",
    content="Write me a poem about flowers"
)

# Run agent
run = project.agents.runs.create_and_process(
    thread_id=thread.id,
    agent_id=agent.id
)

# Get response
messages = project.agents.messages.list(
    thread_id=thread.id,
    order=ListSortOrder.ASCENDING
)
for message in messages:
    if message.run_id == run.id and message.text_messages:
        print(f"{message.role}: {message.text_messages[-1].text.value}")

# Cleanup
project.agents.delete_agent(agent.id)

Core Concepts

AIProjectClient

Central client for all Foundry operations:

Agent Tools

Extend agents with built-in tools. See references/agent-tools.md for details:

Threads, Runs, Messages

Agent conversation model:

CopyThread (conversation container)
├── Message (user input)
├── Run (agent execution)
│   └── Run Steps (tool calls, responses)
└── Message (agent response)

Example Scripts

Execute without loading into context when possible:

Code Generation Guidelines

1. Use AIProjectClient - Central entry point for all operations
2. DefaultAzureCredential - Works locally (CLI) and in production (managed identity)
3. Always cleanup - Delete agents after use to avoid resource leaks
4. Check run status - Handle run.status == "failed" cases
5. Use ListSortOrder - Get messages in correct order
6. Project endpoint format - https://<resource>.services.ai.azure.com/api/projects/<project>

Project Structure

Copymy-foundry-app/
├── src/
│   ├── __init__.py
│   ├── main.py           # Entry point
│   ├── client.py         # AIProjectClient setup
│   └── agents/
│       ├── __init__.py
│       └── assistant.py  # Agent definitions
├── requirements.txt
├── .env.example
└── azure.yaml            # Azure deployment config

Reference Documentation

• Agent Tools - Code Interpreter, File Search, Bing, Functions
• SDK Reference - AIProjectClient API details
• Troubleshooting - Common issues and solutions