Skip to lesson

MicrosoftMicrosoft Certified: Multi-Agent AI Solutions Expert2026-100 Prerequisites

Locate the right Foundry object first

Completed by the knowledge check

Learning objective

Navigate Microsoft Foundry (formerly Azure AI Foundry), projects, models, prompt/hosted agents, versions, conversations, and Responses API concepts.

Core idea

Microsoft Foundry is the product name used in this guide; the objective also names its former Azure AI Foundry branding. Navigate it by identifying the object you need: a project organizes work, a model supplies inference, an agent defines behavior, an agent version records a definition, and a conversation carries interaction history. A response is one execution result, not another name for all those objects.

For an architect preparing for AI-500, this map prevents an API mismatch before implementation starts. Documentation for Foundry (classic) and Azure AI Projects 1.x does not describe the same interface as the prompt-agent quickstart for Azure AI Projects 2.x. Read the product surface, endpoint, and SDK generation together. See 1.2.1 for the deeper hosting decision and 0.7 for the ownership of different kinds of state.

How it works

Start with the project and endpoint

The Foundry portal is available at https://ai.azure.com. A project organizes agents, evaluations, and files. Project creation belongs to resource administration, while an application’s subsequent calls use the appropriate runtime API. Knowing where an object appears in the portal is useful, but your integration also needs the endpoint that addresses it.

The Python prompt-agent quickstart gives the project endpoint shape as https://RESOURCE_NAME.services.ai.azure.com/api/projects/PROJECT_NAME. RESOURCE_NAME and PROJECT_NAME identify the Foundry resource and project. AIProjectClient connects to that project using an Azure credential. The project name is not the name of a deployed model or an agent.

The project Responses endpoint adds project-scoped data and Foundry capabilities. The Responses quickstart identifies its path as {project_endpoint}/openai/v1/responses. It distinguishes that surface from an Azure OpenAI endpoint used for OpenAI models and standard tools. Choose the endpoint from the capabilities you need, rather than assuming every OpenAI-compatible endpoint exposes the same Foundry tools.

Distinguish a model from its agent configuration

The model catalog presents available model choices, but an application still needs a supported target for its request. In the prompt-agent quickstart, you create the agent using a deployed model and place the model selection in PromptAgentDefinition.model. Instructions and tools belong to the agent definition around that model.

Model choice determines inference capabilities; agent configuration determines the task instructions and exposed tools. A strong reasoning model does not create a storage connection or authorize a tool. Conversely, changing an agent’s instructions does not change the model’s context limit or modality support. See 0.1 and 0.2 for those model-level decisions.

Foundry Agent Service supports many models from the catalog, but a catalog listing is not a claim that every model supports every agent feature. Verify the model and feature combination for the intended deployment. This lesson maps the objects rather than supplying an availability matrix that would conceal those conditions.

Choose prompt configuration or hosted code

A prompt agent is declaratively defined through instructions, model selection, and tools. Foundry runs that configuration. You can author it in the portal or through SDK and REST interfaces. The Python mechanism is PromptAgentDefinition, passed to project.agents.create_version(agent_name=..., definition=...).

A hosted agent is your agent code packaged as a container image. The hosted-agent documentation describes pushing that image to Azure Container Registry; Agent Service runs the container and supplies its endpoint, identity, and session infrastructure. Your code owns orchestration inside that runtime. A prompt agent’s configuration and a hosted agent’s container are therefore different deployment artifacts.

Microsoft Foundry Hosted Agents, the managed hosting service, is generally available. The Python agent-framework-foundry-hosting integration is prerelease; see 1.2.1 for the service and integration distinction. Hosted agents run in per-session VM-isolated sandboxes, which are distinct from conversation records containing messages.

Separate versions, stable routing, and conversations

project.agents.create_version creates an agent or an additional version under the specified agent name. The returned details include id, name, and version. Record these separately when diagnosing which definition a request used. A conversation ID is not an agent version and does not select a model deployment.

The agent object-model migration documentation describes agent-owned stable endpoints and a version_selector that selects the version exposed through that endpoint. It replaces the separate Agent Application and Deployment arrangement for agents created under that model. Microsoft describes Agent Applications as deprecated with advance notice and a migration period. Existing applications continue serving traffic, so an application endpoint in a reference sample can indicate a deprecated integration rather than an object you must create for every agent.

This migration surface includes api-version=2025-11-15-preview and the Foundry-Features: AgentEndpoints=V1Preview header in its documented REST example. Do not present that API as generally available. Keep the distinction between endpoint routing and definition versioning, even when using the portal instead of that REST example.

For multi-turn interaction, the Python quickstart obtains a bound client with project.get_openai_client(agent_name=FOUNDRY_AGENT_NAME). It calls openai.conversations.create() and then supplies conversation=conversation.id to openai.responses.create, alongside input. A follow-up uses the same conversation ID so history remains associated with the interaction. The result exposes response.output_text for text output.

Understand direct Responses calls

You can call the Responses API without creating a persisted agent resource. The Responses quickstart calls this an ephemeral agent: instructions, tools, and model selection live in application code. The application ships and versions that definition with its own code instead of maintaining a Foundry agent resource. The Python quickstart constructs an Agent Framework Agent over FoundryChatClient(project_endpoint=..., model=..., credential=...).

An ephemeral definition does not mean every component runs locally. The documented example executes a custom function locally, while the built-in web-search tool supplied by FoundryChatClient.get_web_search_tool() executes server-side through the project Responses API. Distinguish definition ownership from tool execution location; see 0.4 for the tool control loop.

Key distinctions and trade-offs

Project versus agent: The project organizes resources and data. The agent defines behavior and has versions. A project endpoint and an agent-specific endpoint address different integration surfaces.

Version versus conversation: A version identifies a definition. A conversation carries interaction history. Reusing conversation history does not prove that an endpoint still routes to the same definition.

Persisted versus ephemeral definition: A persisted prompt agent is managed as a Foundry object. An ephemeral definition lives in application code. Both can use Responses; the API name alone does not identify lifecycle ownership.

Architecture / decision scenario

A support team opens its Foundry project, chooses a supported deployed model, and creates a prompt-agent version using PromptAgentDefinition. The application uses the agent-bound OpenAI client, creates a conversation, and sends follow-up inputs with the same conversation.id. Its operational record keeps the agent name, version information, conversation ID, and response identity distinct.

A second service needs custom orchestration. The team assesses hosted-agent containers instead of trying to express arbitrary runtime code inside prompt configuration. A lightweight third integration uses Agent over FoundryChatClient to keep its definition in application code and call project Responses directly. Before rollout, the team checks whether any existing endpoint uses the Agent Application model and verifies version selection for the agent-owned stable endpoint it intends to use.

Common exam traps

  • Mixing Azure AI Projects 1.x examples with 2.x prompt-agent calls.
  • Treating project, deployment, agent, and conversation names as interchangeable.
  • Assuming every Responses endpoint exposes identical Foundry capabilities.
  • Treating a conversation ID as an agent version selector.
  • Assuming a direct Responses call requires a persisted agent resource.
  • Applying the hosted service’s GA status to the api-version=2025-11-15-preview agent-endpoint REST surface.

What to remember

Locate the project, model target, agent definition, version, and conversation separately. Responses is an execution interface shared by different ownership models. Match the endpoint and SDK generation to the documented surface, and keep preview and migration conditions visible.

Knowledge check

References