Setting the file. One moment.
Chapter 36 · Microsoft Foundry
Subchapter 36.18
foundry-agent/create/create-prompt.mdMarkdown4 KBView on GitHub
Create and manage prompt agents in Azure Foundry Agent Service using MCP tools or Python SDK. For hosted agents (container-based), see create-hosted.md.
| Property | Value |
|---|---|
| Agent Type | Prompt (kind: "prompt") |
| Primary Tool | Foundry MCP server (foundry_agents_*) |
| Fallback SDK | azure-ai-projects v2.x preview |
| Auth | DefaultAzureCredential / az login |
User Request (create/list/get/update/delete agent)
│
▼
Step 1: Resolve project context (endpoint + credentials)
│
▼
Step 2: Try MCP tool for the operation
│ ├─ ✅ MCP available → Execute via MCP tool → Done
│ └─ ❌ MCP unavailable → Continue to Step 3
│
▼
Step 3: Fall back to SDK
│ Read references/sdk-operations.md for code
│
▼
Step 4: Execute and confirm resultThe user needs a Foundry project endpoint. Check for:
PROJECT_ENDPOINT environment variablefoundry_resource_get MCP tool to discover itEndpoint format: https://<resource>.services.ai.azure.com/api/projects/<project>
For a prompt agent:
For a workflow:
If MCP tools are unavailable, use the azure-ai-projects SDK:
⚠️ MANDATORY: Before configuring any tool, read its reference documentation linked below to understand prerequisites, required parameters, and setup steps. Do not attempt to add a tool without first reviewing its reference.
| Tool Category | Reference |
|---|---|
| Code Interpreter, Function Calling | Simple Tools |
| File Search (requires vector store) | File Search |
| Web Search (default, no setup needed) | Web Search |
| Bing Grounding (explicit request only) | Bing Grounding |
| Azure AI Search (private data) | Azure AI Search |
| MCP Servers | MCP Tool |
| Memory (persistent across sessions) | Memory |
| Connections (for tools that need them) | Project Connections |
⚠️ Web Search Default: Use
WebSearchPreviewToolfor web search. Only useBingGroundingToolwhen the user explicitly requests Bing Grounding.
| Error | Cause | Resolution |
|---|---|---|
| Agent creation fails | Missing model deployment | Deploy a model first via foundry_models_deploy or portal |
| MCP tool not found | MCP server not running | Fall back to SDK — see SDK Operations |
MCP agent operation returns 403 Forbidden | Insufficient RBAC | Need Foundry User role on the project |
| Permission denied | Insufficient RBAC | Need Foundry User role on the project |
| Agent name conflict | Name already exists | Use a unique name or update the existing agent |
| Tool not available | Tool not configured for project | Verify tool prerequisites (e.g., Bing resource for grounding) |
| SDK version mismatch | Using 1.x instead of 2.x | Install azure-ai-projects --pre for v2.x preview |
| Tenant mismatch | MCP token tenant differs from resource tenant | Fall back to SDK — DefaultAzureCredential resolves the correct tenant |