Building Your First Prompt Agent in Microsoft Foundry

What a prompt agent actually is

A prompt agent is the simplest thing in Foundry Agent Service that still deserves the name "agent". It is declarative: you describe what it should be rather than writing the loop that makes it behave. Four ingredients go into that description — a model drawn from the Foundry model catalogue, instructions, tools, and the natural-language prompts that drive behaviour.

The word to dwell on is declarative. There is no orchestration code to write, no container to build, no server to run. You state a definition, the service holds it, and you send messages to it. That is why the prompt agent is the right starting point for this topic: it isolates the ideas of instruction, model choice and conversation from the machinery of hosting.

What you need before you start

The prerequisites are short but strict. You need a model already deployed in Microsoft Foundry — the agent references a deployment, it does not create one. You need your development environment prepared with the appropriate language runtimes, global tools and editor extensions. And you need your project endpoint, which follows the form https://resource_name.ai.azure.com/api/projects/project_name.

Two values do most of the work in the quickstart and are usually stored as environment variables: the project endpoint and the agent name. Authentication is not key-based in the examples. You sign in with the az login command before running your scripts, and the code picks up that identity through DefaultAzureCredential. Understanding that chain — CLI sign-in, credential object, project client — explains most first-run failures.

There is one version trap worth memorising. The current packages use the Foundry projects API and are not compatible with the older 1.x generation of the Azure AI Projects libraries. In Python that means azure-ai-projects at 2.3.0 or later; the JavaScript and .NET equivalents are @azure/ai-projects and Azure.AI.Projects. Sample code written against the previous generation will not run, and the error it produces rarely points at the version as the cause.

Creating the agent

Creation is a single call against a project client. You construct that client from the endpoint and a credential, then create a version of the agent by supplying a prompt agent definition containing a model and instructions. The instructions are ordinary prose — something like telling the agent it is a helpful assistant that answers general questions. That prose is the agent's behaviour specification, so it deserves more care than its brevity suggests.

Notice what comes back. The created agent has an id, a name, and a version. Versioning is present from the very first call, not added later when you get serious. Agents can be updated or deleted at any time.

Notice also what does not happen. Nothing is deployed. Creating an agent registers a definition against your project; the model deployment it points at was already there.

Talking to the agent

Conversation works through two objects, and separating them is the key insight of this quickstart.

A conversation is the container that holds history. You create one explicitly.

A response is a single turn. You send input, referencing the conversation, and read the output text.

Because the conversation carries the state, a follow-up turn understands what came before. The quickstart demonstrates this deliberately: ask how large France is in square miles, then ask only "And what is the capital city?" The second question contains no mention of France, yet it is answered correctly, because the conversation supplies the missing context.

That is worth stating as a principle. The agent definition is stateless and reusable; the conversation is where memory of a particular exchange lives. Reuse the agent across users, create a conversation per exchange.

In the code paths you obtain a client bound to your agent and call the conversations and responses APIs through it. Over REST the same idea appears as an agent_reference object carrying the agent's name — and optionally a version — alongside the input, posted to the responses endpoint. A REST caller first obtains a temporary access token scoped to Foundry; that token expires within roughly sixty to ninety minutes and must be refreshed.

Portal or code

The same agent can be built either way. The Foundry portal requires no installation at all, which makes it the fastest route to seeing an agent answer a question. Code gives you the identical object through Python, C#, TypeScript, Java or plain REST. For the exam, recognise that these are alternative surfaces onto one service rather than different products, and that the concepts — definition, instructions, model, version, conversation, response — are identical across all of them.

What to watch out for

Three things trip people up. First, forgetting that the model must already be deployed; an agent definition naming a model you have not deployed has nothing to run on. Second, mixing package generations, as described above. Third, expecting statelessness or statefulness in the wrong place — the definition persists, an unreferenced conversation does not carry forward, and history only accumulates where you deliberately create a conversation and keep passing it.

Finally, remember to clean up. Because the agent lives inside a project backed by Azure resources, the tidy-up step is deleting the resource group associated with the project when you no longer need it.