Build a prompt agent with tools

A prompt agent is an agent you define through settings rather than by shipping your own server code. In Foundry Agent Service it brings together a model from the Foundry model catalog, written instructions, optional tools, and the natural language prompts users send. The model still generates text, but tools let it pull facts from your data or trigger actions your application performs.

Concept 6 showed how to ground answers in your documents with file search and Azure AI Search. This concept adds the rest of the picture: attach the tools the job needs, control when the model may call them, save testable versions, and check that each turn behaved as you expect. You can create and update prompt agents in the Microsoft Foundry portal or from your app with the SDK or REST API. With a prompt agent, you set up the model, instructions, and tools in settings. With a hosted agent, you deploy code you write and package it in a container; here the service runs the model and tools you configured.

You need a model deployed in your Foundry project before you create an agent. Copy the project endpoint from the welcome screen in the Microsoft Foundry portal. It looks like https://<resource-name>.services.ai.azure.com/api/projects/<project-name> and is what your code uses to reach the project.

• Choose a name for the agent. After you name it in the portal, you cannot rename it. In code you refer to the agent as name plus version once versions exist.
• Set the model deployment and instructions that describe tone, scope, and when to use each tool.
• Create the agent (for example with create_version in the SDK). The service returns an id, name, and version number.
• Open a conversation, send user input, and read the agent's reply. Multi-turn chat keeps history in the same conversation so follow-up questions can use earlier context.
• You can update or delete agents when requirements change; each saved configuration milestone should become a new version rather than overwriting an old one.
• When you run SDK samples locally, sign in with the Azure CLI (az login) first so DefaultAzureCredential can authenticate to your project.

The prompt-agent quickstart walks through the same flow: create the agent with a model and instructions, bind an OpenAI client to that agent, create a conversation, and call responses.create for the first question and for follow-ups in that conversation.

Tools extend what the agent can do beyond the model's training data. Add only what the scenario needs. Each tool adds behavior to test, possible latency, and cost to watch. In agent instructions, say what each tool is for and when to prefer it. If two tools overlap, add a simple rule (for example, use file search for uploaded policies before calling a custom API). Also tell the agent what to do when a tool fails or returns no results: explain the issue briefly and ask a clarifying question instead of guessing.

• File search and Azure AI Search retrieve text from documents you control. Use them when answers must cite your content rather than general knowledge.
• Code interpreter runs Python in a sandbox so the agent can analyze files, do math, and produce charts.
• Function calling lets the model request a function your application runs locally or in your backend, then continue the conversation with the result.
• Before you save an agent with a tool attached, the tool must be fully configured (connections, authentication, or uploaded files as required). You can reuse a configured tool on other agents.

Function calling follows a repeating pattern whether you use the SDK or REST API. First you describe each function tool (name, parameters, and purpose) and register those tools on the agent. When the user sends a prompt, the model may respond with a function_call item instead of final text. Your application executes the matching function, then sends a function_call_output back with the same call id. The agent uses that output to finish the answer in natural language.

• Define function tools with accurate parameter schemas and descriptions.
• Create or update the agent so those tools are attached.
• Send the user message through responses.create (optionally tied to a conversation id).
• If the response output includes function_call items, run your code and collect results.
• Call responses.create again with the function_call_output items so the model can produce the final reply.

Runs expire ten minutes after creation. Submit tool outputs before they expire. You can run agents that use function tools in the Microsoft Foundry portal, but the portal does not support adding, removing, or updating function definitions on an agent; configure function tools with the SDK or REST API. Treat tool arguments and tool outputs as untrusted input, validate values before side effects, and do not return secrets in tool output. Code interpreter uses separate sessions with its own charges beyond model tokens; each active conversation can create its own session, with session lifetime and idle limits described in the Code Interpreter documentation.

The tool_choice setting controls how deterministically the model uses tools on a given turn. Set it on purpose, especially for opening turns or other moments where a tool must run (or must not run) before the user hears or sees a reply.

• Use none when the agent should respond from instructions alone (for example a short greeting).
• Use auto for most flexible chat where the model picks tools when needed.
• Use required when a specific turn must invoke a tool before the answer is complete.
• If the agent skips a tool you expected, confirm the tool is attached, the model and region support it, and review traces to see whether a tool call was produced.

Each saved version of a prompt-based agent is immutable. To change configuration, save a new version and keep older ones so you can compare setup, chat output, or definition differences and roll back if needed. You can try unsaved changes in the agent playground, but unsaved work is lost if you leave the portal, and full conversation history, monitoring, and evaluations require a saved version.

• Save a version after meaningful tool or instruction changes instead of relying on draft state.
• Use tracing (preview) to confirm which tools ran, inspect inputs and outputs, and spot latency across model and tool steps.
• Do not assume the portal configured function tools; verify function calling in SDK or REST tests.
• Return function outputs within the ten-minute run window so the conversation can complete.
• Match model deployment and region to tool support; a tool can fail if either the model or the region does not support it.

You can also customize some tool settings at runtime with structured inputs (handlebar placeholders in instructions or tool resources) so one agent version can serve slightly different file lists or instruction text without creating a new version for every variant. Do not pass secrets as structured input values because logs or traces may capture them.

Imagine a support assistant for an online shop. Instructions tell the agent to check return policy text before promising refunds, to look up orders only when the customer gives an order id, and to refuse to guess shipping dates. You attach file search over uploaded policy PDFs, a function tool get_order_status that your app implements against the order database, and optionally code interpreter when the user uploads a spreadsheet of line items. In the playground you save version 1, ask known policy questions to see citations, then ask for order 88231 and confirm tracing shows get_order_status with the expected arguments before the polite summary reply. When behavior is stable, Concept 8 covers measuring and improving quality with evaluations rather than guessing from a few manual chats.

• Step-by-step setup for your first prompt agent and multi-turn chat. Quickstart: Create a prompt agent
• Define function tools, handle function_call output, and troubleshoot the ten-minute run limit. Use function calling with Microsoft Foundry agents
• Enable sandboxed Python, session charges, and file upload patterns for analysis and charts. Code Interpreter tool for Microsoft Foundry agents
• Instructions, tool_choice, security practices, and regional support checks. Tool best practices for Microsoft Foundry Agent Service