Foundry Agent Platform

Foundry Agent Platform Skill

> Deploy, orchestrate, and manage AI agents on Microsoft Foundry — the unified Azure PaaS for enterprise AI.

> Staleness Watch: See [EXTERNAL-API-REGISTRY.md](../../EXTERNAL-API-REGISTRY.md) for source URLs and recheck cadence

Rapid Evolution Domain

Foundry is in active preview (February 2026). SDK versions change frequently.

Refresh triggers:

• azure-ai-projects SDK version bump (currently 2.0.0b3)
• Foundry portal feature releases
• Hosted Agents GA
• Memory API changes

Last validated: February 2026

---

Platform Overview

Microsoft Foundry (formerly Azure AI Foundry) unifies model hosting, agent orchestration, tool management, observability, and multi-channel publishing.

| Concept | Description | |---------|-------------| | Portal | | | Endpoint | https://.services.ai.azure.com/api/projects/ | | MCP Server | (cloud-hosted, Entra ID) | | VS Code Extension | TeamsDevApp.vscode-ai-foundry | | Key Distinction | Infrastructure platform (backend), not a surface |

Foundry vs Other Platforms

| Aspect | VS Code Extension | M365 Copilot | Foundry | |--------|------------------|-------------|---------| | Type | IDE plugin | Declarative agent | Cloud PaaS | | Runtime | Desktop app | M365 cloud | Azure managed | | Users | Single developer | Single user | Multi-user | | Availability | When IDE open | When M365 open | Always-on (24/7) | | Memory | File-based synapses | OneDrive | Platform-managed | | Tools | MCP (manual config) | Web/SP/Graph | 1,400+ catalog | | Agents | .agent.md files | Single agent | Multi-agent fleet | | Observability | Manual | None | Full OpenTelemetry |

---

Four SDK Types

This is the most common source of confusion. Foundry has four distinct SDK types, each with different endpoints and use cases:

| SDK | Endpoint | When to Use | |-----|----------|-------------| | Foundry SDK | .services.ai.azure.com/api/projects/ | Agent management, evaluations, deployments | | OpenAI SDK | .openai.azure.com/openai/v1 | Chat completions, embeddings (OpenAI-compatible) | | Foundry Tools SDKs | Service-specific | Speech, Vision, Language, Search, etc. | | Agent Framework | Framework-specific | Multi-agent orchestration (cloud-agnostic) |

SDK Packages

| Language | Foundry SDK | OpenAI SDK | |----------|-------------|------------| | Python | azure-ai-projects>=2.0.0b3 (use --pre) | openai | | C# | Azure.AI.Projects (preview) | Azure.AI.OpenAI | | JS/TS | @azure/ai-projects (beta) | openai | | Java | com.azure:azure-ai-projects (preview) | — |

> Breaking Change: Python 2.x is incompatible with 1.x. The 2.x uses .services.ai.azure.com endpoints.

---

Agent Service Patterns

Create Agent

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

client = AIProjectClient(
    endpoint="https://.services.ai.azure.com/api/projects/",
    credential=DefaultAzureCredential()
)

agent = client.agents.create_agent(
    model="gpt-4.1-mini",
    name="my-agent",
    instructions="System prompt here."
)

Versioned Agents

from azure.ai.projects.models import PromptAgentDefinition

definition = PromptAgentDefinition(
    model="gpt-4.1-mini",
    instructions="System prompt",
    tools=[bing_tool, file_search_tool]
)

version = client.agents.create_agent_version(
    agent_id=agent.id,
    definition=definition
)

Conversations (Multi-Turn)

conversation = client.agents.create_conversation(agent_id=agent.id)

client.agents.create_message(
    conversation_id=conversation.id,
    role="user",
    content="Hello"
)

run = client.agents.create_run(
    conversation_id=conversation.id,
    agent_id=agent.id
)

Key Concepts

| Concept | Meaning | |---------|---------| | Agent | Stateless definition (model + instructions + tools) | | Conversation | Stateful multi-turn context | | Run | Single execution within a conversation | | Version | Immutable snapshot of agent definition |

---

Tool Categories

| Tool | Use Case | Setup | |------|----------|-------| | Bing Grounding | Real-time web search | Bing Search resource | | File Search | RAG over documents (vector stores) | Upload files → vector store | | Code Interpreter | Python sandbox execution | Automatic | | SharePoint | Enterprise document grounding | SP site + permissions | | OpenAPI | Any REST API via spec | Provide spec + auth | | MCP Servers | Remote Model Context Protocol | Server URL + auth | | A2A | Agent-to-Agent communication | Target URL + auth |

File Search Setup

vector_store = client.agents.create_vector_store(name="knowledge")
client.agents.upload_file_and_poll(
    vector_store_id=vector_store.id,
    file_path="skills.pdf"
)
file_search_tool = FileSearchTool(vector_store_ids=[vector_store.id])

---

Memory & Foundry IQ

| Feature | Description | |---------|-------------| | Memory | Cross-session context retention, per-user, automatic | | Foundry IQ | Enterprise knowledge base with citations + web grounding | | Priority Chain | Instructions → IQ → File Search → Tool results → Training data |

Memory is the cloud-native equivalent of the AI's synapse architecture — automatic, persistent, cross-surface.

---

Hosted Agents (Preview)

Containerized agents on managed infrastructure:

pip install azure-ai-agentserver-agentframework
agentserver run --interactive   # local test
agentserver run                 # container mode (port 8080)
azd deploy                      # deploy to Foundry

Supports any framework: LangGraph, MS Agent Framework, Semantic Kernel, custom.

---

Observability Stack

Agent → OpenTelemetry → Application Insights → Agent Dashboard

from azure.ai.agentserver import setup_observability
setup_observability(vs_code_extension_port=4319)  # local dev

Built-in Evaluators

Relevance, Groundedness, Coherence, Safety, F1, BLEU, ROUGE

---

Publishing Channels

One agent, many surfaces:

| Channel | Transport | |---------|-----------| | M365 Copilot | Teams manifest + Entra app | | Teams | Bot Framework | | BizChat | Via M365 publish | | Web Preview | Auto-generated URL | | REST API | Standard HTTP | | Container | Docker (Hosted Agent) |

---

Realtime API (Voice)

| Transport | Latency | Use Case | |-----------|---------|----------| | WebRTC | ~100ms | Browser voice | | WebSocket | ~200ms | Server-side | | SIP | Varies | Telephony |

Models: gpt-realtime (GA), gpt-realtime-mini (GA). Supports MCP tools during voice sessions, semantic VAD, image input. 30-min session limit, PCM16 mono 24kHz.

---

Authentication

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()  # Keyless (recommended)
client = AIProjectClient(endpoint=endpoint, credential=credential)

| RBAC Role | Scope | |-----------|-------| | Azure AI User | Least privilege — call agents, use models | | Azure AI Owner | Create/manage agents, deploy models | | Contributor | Create Foundry projects and resources |

---

Anti-Patterns

| Anti-Pattern | Why It Fails | Instead | |-------------|-------------|---------| | Using Python SDK 1.x with 2.x docs | Incompatible APIs, wrong endpoints | Always install --pre for 2.x | | Treating Foundry as "just another heir" | It's a backend, not a surface | Design as shared infrastructure | | Hardcoding API keys | Security risk, doesn't scale | Use DefaultAzureCredential | | One giant agent | Context overload, poor routing | Multi-agent with orchestrator | | Skipping evaluation | No quality baseline | Run evaluators before shipping | | Ignoring cost | Pay-per-use can surprise | Use efficient models (4.1-mini) for most agents |

---

Decision Checklist

When designing a Foundry-based agent:

• [ ] Which SDK type? (Foundry SDK for agents, OpenAI SDK for completions)
• [ ] Which model tier? (Premium for orchestrator, efficient for specialists)
• [ ] Agent Service or Hosted Agent? (Start with Agent Service; migrate later)
• [ ] What tools? (Bing, File Search, Code Interpreter, MCP, OpenAPI)
• [ ] Memory strategy? (Foundry Memory, File Search, or hybrid)
• [ ] Publishing targets? (API first, then Teams, then Web, then Voice)
• [ ] Evaluation plan? (Which evaluators, what dataset, what baseline)
• [ ] Auth model? (Entra ID keyless via DefaultAzureCredential)

---

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fabioc-aloha
• Source: fabioc-aloha/AlexSkill_Mall
• License: MIT

Install and usage instructions live in the source repository linked above.