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)

1. Python 3.9+ with azure-ai-projects >= 2.0.0 and azure-identity
2. Azure CLI authenticated via az login (or DefaultAzureCredential)
3. Foundry User role on the AI Services account (GUID

53ca6127-db72-4b80-b1b0-d745d6d5456d) — same role as hosted agents

pip install "azure-ai-projects~=2.1.0" azure-identity

---

1 · Create a prompt agent

A prompt agent is created with PromptAgentDefinition — just a model name and instructions. No container, no Dockerfile, no ACR.

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

PROJECT_ENDPOINT = ""
# Format: https://.services.ai.azure.com/api/projects/

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

curl -X POST "https://.services.ai.azure.com/api/projects//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

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)

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 > 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=...).

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.

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="")],
)

Requires a Fabric workspace + a project-scoped connection (Microsoft.CognitiveServices/accounts/.../connections/). See the Fabric IQ tool docs.

WorkIQTool

Grounds a prompt agent in Microsoft 365 / Graph (mail, calendar, SharePoint, Teams) via a Work IQ connection.

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="")],
)

Requires an M365 / Graph connection on the Foundry project. The connection contract is identical to Fabric IQ — see the Work IQ tool docs for tenant-admin consent + scope guidance.

ToolSearchTool

Lets a prompt agent dynamically discover and call tools registered in a Foundry toolbox (server-side MCP bundle) without enumerating every tool in tools=[...].

from azure.ai.projects.models import ToolSearchTool, PromptAgentDefinition

definition = PromptAgentDefinition(
    model="gpt-5-mini",
    instructions="Use the most appropriate tool for the user's task.",
    tools=[ToolSearchTool(toolbox_ids=[""])],
)

Toolbox registration is server-side — see the foundry-toolboxes skill (forthcoming in this catalog) for the toolbox lifecycle. ToolSearchTool is the consumption side; foundry-toolboxes is the production side.

SkillReferenceTool

Lets a prompt agent invoke a published Foundry Skill (a declarative tool pack) by reference, the same way a hosted agent does.

from azure.ai.projects.models import SkillReferenceTool, PromptAgentDefinition

definition = PromptAgentDefinition(
    model="gpt-5-mini",
    instructions="Use the published payments-lookup skill when asked about transactions.",
    tools=[SkillReferenceTool(skill_id="")],
)

Foundry Skills are managed in the same catalog as Toolboxes — see the foundry-toolboxes skill (forthcoming) for publishing + versioning.

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.

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="")],
)

For the decision of when to use GuardrailTool vs full in-process governance (AGT) vs raw ACS API calls, see the foundry-agt skill — it carries the canonical decision table.

A2ATool

Lets a prompt agent invoke a peer hosted agent (Agent-to-Agent protocol, GA at //build 2026).

from azure.ai.projects.models import A2ATool, PromptAgentDefinition

definition = PromptAgentDefinition(
    model="gpt-5-mini",
    instructions="When asked for current weather, delegate to the weather-bot agent.",
    tools=[A2ATool(target_agent_id="")],
)

Identity propagation, peer-agent RBAC, and the project-MI Cog-roles gotcha (AGENTS.md §9.7 Pattern 23) are documented under the a2a_preview tool type in the foundry-toolbox skill.

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.

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="")],
)

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.

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

project = AIProjectClient(
    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

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.

# 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

# List all agents in the project
for agent in project.agents.list():
    latest = agent.versions.get("latest", {})
    print(f"{agent.name}  v{latest.get('version', '?')}  {latest.get('status', '?')}")

# Delete a specific version (positional args: agent_name, agent_version)
project.agents.delete_version("my-assistant", "1")

> list() returns AgentDetails, not AgentVersionResponse. The list > objects have a .versions dict (keyed by "latest", "1", etc.), not a > single .version attribute. Use .versions["latest"]["version"] for the > current version number.

---

5 · Structured inputs (runtime tool customization)

Override tool configuration at runtime without creating a new agent version. Useful when different users need different vector stores, MCP endpoints, or file sets.

Define template variables

agent = project.agents.create_version(
    agent_name="support-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="Answer support questions using the customer's knowledge base.",
        tools=[
            FileSearchTool(vector_store_ids=["vs_base_kb", "{{customer_kb}}"]),
        ],
        structured_inputs={
            "customer_kb": {
                "description": "Vector store ID for the customer's knowledge base",
                "required": True,
                "schema": {"type": "string"},
            }
        },
    ),
)

Provide values at invocation

response = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {"name": "support-agent", "type": "agent_reference"},
        "structured_inputs": {"customer_kb": "vs_premium_kb"},
    },
    input="How do I upgrade my account?",
)

Supported template properties:

| Tool | Property | Description | |------|----------|-------------| | file_search | vector_store_ids | Array of vector store IDs | | code_interpreter | container, container.file_ids | Container or file IDs | | mcp | server_label, server_url, headers | MCP server config |

---

6 · Publish as an agent application

After testing, publish a version to get a stable endpoint that can be shared or embedded in applications.

Publishing is done in the Foundry portal:

1. Open your agent in the Agents playground
2. Select a saved version
3. Click Publish
4. Get the endpoint URL for integration

> Identity changes on publish. The published agent application gets its > own identity. Permissions assigned to the project identity do NOT > automatically transfer. Reassign RBAC (Foundry User, Cognitive Services > OpenAI User, etc.) to the agent application's managed identity after > publishing.

---

7 · Identity & RBAC

Prompt agents run under the project identity during development and under the agent application identity after publishing.

| Phase | Identity | RBAC needed | |-------|----------|-------------| | Development | Your user (via az login) | Foundry User on AI Services account | | Published | Agent application managed identity | Foundry User + tool-specific roles |

Required role:

• Foundry User (`53ca6127-db72-4b80-b1b0-d745d

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aiappsgbb
• Source: aiappsgbb/awesome-gbb
• License: MIT

Install and usage instructions live in the source repository linked above.