foundry-prompt-agents

# Microsoft Foundry Prompt Agents — Reference Guide Create declarative agents in Foundry Agent Service using only a model, instructions, and tools — **no containers, no custom code, no build step**. Prompt agents are the fastest path from zero to a working agent. --- ## When to use prompt agents vs hosted agents | | Prompt agents | Hosted agents | |---|---|---| | **Definition** | Declarative (model + instructions + tools) | Code-first (Python/C#/TS in container) | | **Runtime** | Foundry Agent Service manages everything | You build & deploy a container image | | **SDK** | `azure-ai-projects` (`PromptAgentDefinition`) | MAF (`agent-framework` + `agent-framework-foundry-hosting`) | | **Build step** | None — create via SDK, REST, or portal | Dockerfile → ACR → ACA or Foundry hosting | | **Tools** | Built-in catalog + MCP + OpenAPI + functions | Full programmatic control (any Python library) | | **Customization** | Instructions + tool config only | Unlimited (custom middleware, state, orchestration) | | **Best for** | Q&A bots, RAG assistants, tool-using agents with standard tools | Complex orchestration, custom business logic, multi-agent systems | **Rule of thumb:** Start with a prompt agent. Upgrade to a hosted agent only when you need custom code that can't be expressed as a tool. --- ## Prerequisites 1. **Microsoft Foundry project** with a deployed model (e.g., `gpt-5-mini`, `gpt-5.4-mini`, `gpt-4.1`) 2. **Python 3.9+** with `azure-ai-projects ~= 2.4.0`, `azure-identity ~= 1.25.3`, and `httpx ~= 0.28.1` 3. **Azure CLI** authenticated via `az login` (or `DefaultAzureCredential`) 4. **Foundry User role** on the AI Services account (GUID `53ca6127-db72-4b80-b1b0-d745d6d5456d`) — same role as hosted agents ```bash pip install "azure-ai-projects~=2.4.0" "azure-identity~=1.25.3" "httpx~=0.28.1" ``` --- ## 1 · Create a prompt agent A prompt agent is created with `PromptAgentDefinition` — just a model name and instructions. No container, no Dockerfile, no ACR. ```python from azure.identity import DefaultAzureCredential from azure.ai.projects import AIProjectClient from azure.ai.projects.models import PromptAgentDefinition PROJECT_ENDPOINT = "<your-project-endpoint>" # Format: https://<resource>.services.ai.azure.com/api/projects/<project> project = AIProjectClient( endpoint=PROJECT_ENDPOINT, credential=DefaultAzureCredential(), ) agent = project.agents.create_version( agent_name="my-assistant", definition=PromptAgentDefinition( model="gpt-5-mini", instructions="You are a helpful assistant that answers general questions.", ), ) print(f"Agent created: {agent.name} v{agent.version} (id: {agent.id})") ``` ### REST equivalent ```bash curl -X POST "https://<resource>.services.ai.azure.com/api/projects/<project>/agents/my-assistant/versions?api-version=v1" \ -H "Authorization: Bearer $(az account get-access-token --resource https://cognitiveservices.azure.com --query accessToken -o tsv)" \ -H "Content-Type: application/json" \ -d '{ "definition": { "type": "prompt", "model": "gpt-5-mini", "instructions": "You are a helpful assistant." } }' ``` --- ## 2 · Add tools Prompt agents support all tools from the Foundry tool catalog. Add them via the `tools` parameter on `PromptAgentDefinition`. ### Built-in tools ```python from azure.ai.projects.models import ( PromptAgentDefinition, WebSearchTool, CodeInterpreterTool, FileSearchTool, ) agent = project.agents.create_version( agent_name="research-assistant", definition=PromptAgentDefinition( model="gpt-5-mini", instructions="You are a research assistant. Search the web and analyze data.", tools=[ WebSearchTool(), # real-time web search CodeInterpreterTool(), # sandboxed Python execution FileSearchTool(vector_store_ids=["vs_docs"]), # RAG over uploaded files ], ), ) ``` ### Available built-in tools | Tool | Class | Purpose | |------|-------|---------| | Web Search | `WebSearchTool` | Real-time web grounding with citations | | Code Interpreter | `CodeInterpreterTool` | Sandboxed Python for data analysis, charts | | File Search | `FileSearchTool` | Vector search over uploaded documents | | Function Calling | via `tools` spec | Agent calls your functions, you execute & return | | Azure AI Search | via connections | Enterprise search index grounding | | Bing Grounding | `BingGroundingTool` | Market-specific Bing search | | SharePoint | via connections | Search SharePoint content | ### Custom tools (MCP, OpenAPI) For per-user custom OAuth, use the connection-backed builders in the [foundry-mcp-auth candidate](../foundry-mcp-auth/SKILL.md). It owns delegated scope enforcement and consent setup; the plain MCP example below is not a delegation proof. The candidate's live Playground acceptance is still pending. ```python from azure.ai.projects.models import MCPTool # MCP server (remote tools) mcp_tool = MCPTool( server_label="my-tools", server_url="https://my-mcp-server.azurecontainerapps.io/mcp", require_approval="never", ) agent = project.agents.create_version( agent_name="tool-agent", definition=PromptAgentDefinition( model="gpt-5-mini", instructions="Use available tools to answer questions.", tools=[mcp_tool], ), ) ``` > **OpenAPI tools** (`OpenApiTool`) require an `OpenApiFunctionDefinition` > with a full spec dict and auth configuration. See the > [Foundry OpenAPI tool docs](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/openapi) > for the complete schema. > **MCP servers for prompt agents** are hosted remotely (not in-process). > Use `foundry-mcp-aca` skill to deploy MCP servers on Azure Container Apps, > then wire them here via `MCPTool(server_url=...)`. > If the tool work needs durable result claims, external callbacks, or > execution that must outlive one request, fall back to > [foundry-mcp-aca-jobs](../foundry-mcp-aca-jobs/SKILL.md) for the worker > path and keep the prompt agent as the orchestrator. ### Build 2026 additions (preview) The //build 2026 wave shipped seven additional first-class prompt-agent tools. Each is exposed in `azure-ai-projects ≥ 2.0.0` and wired the same way as the GA tools above. Cross-references point to the dedicated skills that cover the connection setup, server-side resources, or governance contract for each tool — some of those skills are forthcoming in this catalog (tracked in the //build 2026 update wave); use the upstream Foundry docs in the meantime. #### FabricIQTool Grounds a prompt agent in Microsoft Fabric data via a Fabric workspace connection. ```python from azure.ai.projects.models import FabricIQTool, PromptAgentDefinition definition = PromptAgentDefinition( model="gpt-5-mini", instructions="Answer questions about Q3 revenue using Fabric data.", tools=[FabricIQTool(connection_id="<fabric-connection-id>")], ) ``` Requires a Fabric workspace + a project-scoped connection (`Microsoft.CognitiveServices/accounts/.../connections/<name>`). See the [Fabric IQ tool docs](https://learn.microsoft.com/azure/ai-foundry/tools/fabric-iq). #### WorkIQTool Grounds a prompt agent in Microsoft 365 / Graph (mail, calendar, SharePoint, Teams) via a Work IQ connection. ```python from azure.ai.projects.models import WorkIQTool, PromptAgentDefinition definition = PromptAgentDefinition( model="gpt-5-mini", instructions="Summarize my unread email threads about Project Hummingbird.", tools=[WorkIQTool(connection_id="<work-iq-connection-id>")], ) ``` Requires an M365 / Graph connection on the Foundry project. The connection contract is identical to Fabric IQ — see the [Work IQ tool docs](https://learn.microsoft.com/azure/ai-foundry/tools/work-iq) for tenant-admin consent + scope guidance. #### ToolSearchTool For Toolbox discovery, do not use the obsolete `toolbox_ids` constructor. Configure `ToolSearchToolboxTool` in a **Toolbox version**, then connect the Prompt Agent through the documented `MCPTool` bridge to that version's MCP endpoint. See [`foundry-toolbox` — Prompt Agent bridge](../foundry-toolbox/SKILL.md#prompt-agent-bridge) for the canonical wiring and token/approval boundary. Tool Search and Toolbox management are GA; **Prompt/Toolbox integration remains preview**. A live synthetic test on SDK 2.6.1 verified the Prompt agent actually called `tool_search` and `call_tool` and returned the public documentation result. This does not prove delegated-user passthrough. Request-scoped Responses API deferred-tool search is a different API, not a substitute Toolbox identifier. #### SkillReferenceTool This historical heading is retained for navigation, not an available tool constructor. Do not instantiate `SkillReferenceTool(skill_id=...)`. Foundry Skills are versioned instruction packages, not a Prompt Agent tool pack. Use [`foundry-skill-catalog`](../foundry-skill-catalog/SKILL.md) for native versions, explicit download/injection and resource-aware Toolbox consumers. SDK 2.7 schema fields alone do not prove native Prompt/harness support; this skill does not enable that unvalidated route or change the existing SDK pin. #### GuardrailTool Wires Azure Content Safety (ACS) as a server-side policy check around the agent's input and output, expressed as a tool the agent can invoke. ```python from azure.ai.projects.models import GuardrailTool, PromptAgentDefinition definition = PromptAgentDefinition( model="gpt-5-mini", instructions="Be helpful, but always run the user message through GuardrailTool first.", tools=[GuardrailTool(connection_id="<acs-connection-id>")], ) ``` Keep the routing decision in this skill: - Use `GuardrailTool` in `PromptAgentDefinition` when the prompt agent should invoke its configured Azure Content Safety connection as a server-side check. - Call the raw ACS API directly when application code must select classifiers, thresholds, and response handling itself. - Use [`foundry-agt`](../foundry-agt/SKILL.md#why-action-governance-matters) only for a MAF hosted-agent process that needs deterministic allow/deny by tool name before the tool body executes. You cannot insert AGT's in-process middleware into `PromptAgentDefinition`. AGT does not replace Azure Content Safety; combine the two planes when a workload needs both content scanning and tool-action governance. #### A2ATool Use the GA **protocol 1.0** contract, not `target_agent_id`. The direct SDK model uses `A2ATool(a2a_version=A2AProtocolVersion.V1_0, project_connection_id=...)`; the Toolbox model is `A2AToolboxTool`. Protocol 0.3 / `a2a_preview` remains preview. See [`foundry-toolbox` — A2A management](../foundry-toolbox/SKILL.md#a2a-10-management-without-a-runtime-upgrade) for the isolated SDK environment, connection audience, actual caller access and tested Toolbox invocation path. Do not silently upgrade this skill's existing SDK runtime to import newer models, or assume a hosted peer supports incoming A2A because its container deployed. #### BrowserAutomationTool Lets a prompt agent drive a Playwright-backed remote browser session (GA Nov 2026) — useful for forms, multi-page workflows, and pages that require interactive navigation. ```python from azure.ai.projects.models import BrowserAutomationTool, PromptAgentDefinition definition = PromptAgentDefinition( model="gpt-5-mini", instructions="When asked to fill a form, use BrowserAutomationTool.", tools=[BrowserAutomationTool(connection_id="<browser-connection-id>")], ) ``` Connection setup, deterministic-page testing patterns, and Pattern 25 soft-PASS teardown for ephemeral browser sessions are covered in the `foundry-browser-automation` skill (forthcoming in this catalog). --- ## 3 · Chat with the agent Prompt agents use the **Conversations API** via the OpenAI-compatible client. This is the same invocation path used by hosted agents. ```python from azure.identity import DefaultAzureCredential from azure.ai.projects import AIProjectClient project = AIProjectClient( endpoint="<your-project-endpoint>", credential=DefaultAzureCredential(), ) openai = project.get_openai_client() # Create a conversation (multi-turn session) conversation = openai.conversations.create() # First turn response = openai.responses.create( conversation=conversation.id, extra_body={"agent_reference": {"name": "my-assistant", "type": "agent_reference"}}, input="What is the population of Tokyo?", ) print(response.output_text) # Follow-up (same conversation → history is maintained) response = openai.responses.create( conversation=conversation.id, extra_body={"agent_reference": {"name": "my-assistant", "type": "agent_reference"}}, input="How does that compare to New York?", ) print(response.output_text) ``` ### Targeting a specific version ```python response = openai.responses.create( conversation=conversation.id, extra_body={ "agent_reference": { "name": "my-assistant", "version": "3", # pin to version 3 "type": "agent_reference", } }, input="Hello!", ) ``` --- ## 4 · Versioning Every `create_version` call creates an **immutable** version. You cannot modify a saved version — create a new one instead. ```python # Create version 1 v1 = project.agents.create_version( agent_name="my-assistant", definition=PromptAgentDefinition( model="gpt-5-mini", instructions="You are a helpful assistant.", ), ) print(f"v{v1.version}") # → v1 # Create version 2 with improved instructions v2 = project.agents.create_version( agent_name="my-assistant", definition=PromptAgentDefinition( model="gpt-5-mini", instructions="You are a helpful assistant. Be concise and cite sources.", tools=[WebSearchTool()], ), ) print(f"v{v2.version}") # → v2 ``` Version history is visible in the Foundry portal playground. You can compare setup, chat output, and YAML definitions between versions. > **Agent names are permanent.** Once created, an agent's name cannot be > changed. Use descriptive, stable names from the start. ### List and delete agents ```python # List all agents in the project for agent in project.agents.list():