Microsoft AI-901: Build a Foundry Chat App and Agent

Microsoft AI-901 is not a software-engineering certification, yet it expects more than the ability to recognize a generative AI model. The official syllabus includes deploying a model in Microsoft Foundry, creating a lightweight chat client with the Foundry SDK, building and testing a single agent, and connecting to that agent from a small application. The difference between knowing those terms and actually following the request path is one of the largest preparation gaps for new candidates.

This walkthrough turns those objectives into a bounded lab. It uses Python and the current Microsoft Foundry project model, focuses on one deployed chat-capable model and one deliberately simple prompt agent, and keeps permissions and cost visible. It complements the broader AI-901 preparation plan without duplicating its domain overview. The application is a learning exercise, not a hardened enterprise agent or a claim that an untested environment will run identically in every Azure region.

Know what you’re building before opening the portal

A model deployment exposes the inference capability. A Foundry project organizes the resource access and interfaces the application uses. A chat client supplies instructions and a user message, sends the request, and processes the response. An agent adds a named definition—its model, instructions and optional tools—so requests can be sent through the agent rather than directly to a model. These components may work together, but they are not synonyms.

For a beginner scenario, imagine a help-desk assistant that explains a synthetic return policy. The direct chat model answers a short question. The prompt agent enforces an intended scope and preserves a conversation so the user can ask a follow-up. Neither has permission to issue refunds or read private customer records. That constraint is deliberate: it lets you understand the client and agent path before tackling tools that can alter state.

Microsoft distinguishes the Foundry project endpoint, which commonly follows https://<resource>.services.ai.azure.com/api/projects/<project>, from OpenAI-compatible and specialized Foundry Tools endpoints. The Foundry SDK 2.x works with the newer project API. Examples written for the classic Azure AI Projects 1.x SDK may use different shapes. Mixing a classic endpoint with new-client code is a source of avoidable errors, not a useful exam trick.

Use the Microsoft Foundry capabilities material to place the model, agent, speech, vision and extraction tools in context. The lab here needs only model and agent services. Building everything in the catalog would obscure the narrower learning objective.

Prepare a project, model and approved identity

You need an Azure subscription, a Foundry project and access to a supported model deployed for that project. The account performing day-to-day development should have a Foundry role appropriate for the operation; creating resources or granting permissions can require different administrative rights. Use an authorized subscription and check whether your intended model and region are available. Models, quotas and service costs can vary. A tutorial that selects a model by name cannot guarantee it is deployed in your project.

Open the current Foundry portal and confirm the project endpoint shown for the intended project. Create a supported chat-capable model deployment, record its exact deployment name and test a harmless prompt in the portal. If the portal call fails, debug it there before introducing Python. A working portal request establishes that at least one identity and deployment path function, but it does not prove that a separate script has equivalent permissions.

For Python, create a virtual environment and install a supported Foundry Projects 2.x package and Azure Identity. The command below illustrates the published SDK family. Versions can evolve, so review the installed version and the current official examples when running the lab. Authenticate through your organization’s approved Microsoft Entra sign-in method. Avoid placing passwords or static service credentials inside source code.

python -m venv .venv
# Activate the environment using your operating system's command
pip install "azure-ai-projects>=2.0.0" azure-identity
az login

Set environment variables for the project endpoint and model deployment. A name such as AZURE_AI_PROJECT_ENDPOINT is simply a local variable convention in this example; it is not the name of a required Azure configuration object. A developer might use an IDE run configuration or local environment file for these non-secret values. Secrets and credential configuration belong in approved environment or identity tooling and must never be published.

Call a deployed model from a minimal chat client

The first application should do only three things: authenticate, make a short model request and display the output. In the Foundry SDK 2.x, AIProjectClient connects to the project endpoint with DefaultAzureCredential. The project client can provide the OpenAI-compatible interface used by the Responses API. Use the deployment name actually created in the project, not a model label copied from a tutorial screenshot.

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


project = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
client = project.get_openai_client()


response = client.responses.create(
    model=os.environ["AZURE_MODEL_DEPLOYMENT"],
    input=[
        {"role": "system", "content": "Explain a fictitious store policy clearly. Ask when facts are missing."},
        {"role": "user", "content": "Can a customer return an unused item after 14 days?"},
    ],
)
print(response.output_text)

This is a small illustrative sample based on Microsoft’s current project-client and Responses API pattern. It has not been run against your subscription; you must supply a supported deployment and permissions. The example intentionally does not pretend the model knows the store’s policy. Without approved policy context, the correct behavior is to ask for the missing rule or clearly explain uncertainty, not fabricate an eligibility period.

Next, provide a short, fictional policy as part of the prompt and repeat the question. Does the response rely on the supplied evidence or invent extra conditions? What if the policy says returns are allowed within 14 days except for final-sale items? Try a final-sale example and check whether the exception survives summarization. These are better learning tests than getting one reassuring answer in the chat window.

Keep the prompt and output in a local test record, but avoid logging production personal data. If you change a model setting, note which setting and why. The prompting and grounding concepts become much clearer when you can compare a response with and without relevant evidence.

Create a single prompt agent and test it

A prompt agent is a defined assistant with instructions and a model that can be reused through an endpoint. For AI-901, keep the purpose small. Create an agent whose job is to answer only questions about a fictitious store policy, request clarification if important facts are absent and avoid inventing a refund decision. In the Foundry portal, inspect the definition and try both an in-scope and an out-of-scope request. The goal is not to build an entire customer-service department.

Microsoft’s current Python SDK supports creating a versioned prompt agent with PromptAgentDefinition. Versioning is important: changing an agent’s instructions can change its behavior even if the underlying model is unchanged. The following code expresses the concept using the same project client. Run it only in a project where the signed-in identity is permitted to create an agent; repeated runs can create new versions, so treat this as a controlled lab action.

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
from azure.identity import DefaultAzureCredential


project = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
agent_name = "ai901-policy-assistant"


agent = project.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(
        model=os.environ["AZURE_MODEL_DEPLOYMENT"],
        instructions="Explain only the supplied fictitious policy. Ask when evidence is missing.",
    ),
)
print(agent.name, agent.version)

Notice what is not present: an unrestricted database connection, refund action or tool allowed to write to external systems. The agent can be useful without any such capability. Understanding why a narrow role is safer is an important bridge between the agentic AI concepts and a real implementation.

Connect an application to the agent

After creating the agent, send a message through an agent-scoped client. Microsoft’s Foundry SDK can supply an OpenAI-compatible client bound to the agent name. A conversation object maintains context across turns. Ask one question, then a follow-up that refers to the first answer, and inspect whether the agent maintains the intended thread. This is more informative than invoking unrelated single prompts and assuming they share state.

agent_client = project.get_openai_client(agent_name=agent_name)
conversation = agent_client.conversations.create()


first = agent_client.responses.create(
    conversation=conversation.id,
    input="What information do you need to check a return?",
)
print(first.output_text)


follow_up = agent_client.responses.create(
    conversation=conversation.id,
    input="And if the item is final sale?",
)
print(follow_up.output_text)

The client reuses the project object and agent name from the preceding example. The exact method names reflect current Microsoft Foundry SDK documentation and can change as the platform evolves; verify your installed version. Do not assume the agent has a secret policy document merely because it is named “policy assistant.” You must supply or connect approved evidence. Agent instructions specify desired behavior, not data access or real-world authority.

Examine the follow-up’s relevance. If it loses the earlier topic, check conversation identity. If it invents a condition, examine grounding and instructions. If it fails to execute, distinguish model or agent deployment issues from identity and endpoint failures. A well-controlled lab is one in which you can name the layer responsible for each kind of result.

Troubleshoot the usual Foundry client failures

These checks also teach an operational lesson: a model error is not always a model-quality error. A permissions problem cannot be fixed by increasing a token limit. A missing model deployment cannot be fixed by rewriting a system prompt. A correct network response can still contain wrong content. Debugging succeeds when you identify whether the failure is in the identity, service, data, orchestration or validation layer.

Use only the complexity the requirement justifies. A second agent does not make a simple task more correct; it creates another set of state, permissions and failure cases. A tool that can modify records should have independent authorization and idempotent recovery. For this AI-901 exercise, a simple prompt agent and conversation are sufficient to understand the relevant implementation objective.

Turn the lab into AI-901 exam reasoning

When an exam scenario describes a company that needs a simple model-backed chat experience, start with a supported Foundry deployment and a lightweight client. If the scenario mentions an agent that must preserve context and potentially use tools, think agent definition, conversation and controlled tool boundary. If a question describes a prompt that ignores company policy, ask whether the failure lies in instruction wording, missing approved context or an access rule that should be enforced outside the model.

A good self-test is to narrate a request from start to finish: the caller authenticates, the client targets a project and deployment or an agent, the application sends a system/user message, the service returns output, and the application validates or displays it. For the agent case, explain how conversation state and instructions modify the path. Name the logs and versions you would preserve to reproduce a bad answer.

Also know where this lab stops. It does not teach speech recognition, visual input or structured extraction in detail. Those have their own Foundry Tools or multimodal requirements in the current AI-901 syllabus. Use a second narrow exercise for those rather than expanding this chat agent into an untestable all-purpose application. The technical objective is controlled fluency with one model and one agent, not maximum infrastructure.

Before you consider this lab complete, deliberately trigger a wrong deployment-name error, test an out-of-scope prompt and check a policy answer against source facts. If you can explain the first as configuration, the second as an instruction/authorization issue and the third as an evidence-validation task, you are practicing the reasoning Microsoft expects from a beginning AI solution developer.