1# Create Prompt Agent
2 
3Create and manage prompt agents in Azure Foundry Agent Service using MCP tools or Python SDK. For hosted agents (container-based), see [create-hosted.md](create-hosted.md).
4 
5## Quick Reference
6 
7| Property | Value |
8|----------|-------|
9| **Agent Type** | Prompt (`kind: "prompt"`) |
10| **Primary Tool** | Foundry MCP server (`foundry_agents_*`) |
11| **Fallback SDK** | `azure-ai-projects` v2.x preview |
12| **Auth** | `DefaultAzureCredential` / `az login` |
13 
14## Workflow
15 
16```
17User Request (create/list/get/update/delete agent)
18    │
19    ▼
20Step 1: Resolve project context (endpoint + credentials)
21    │
22    ▼
23Step 2: Try MCP tool for the operation
24    │  ├─ ✅ MCP available → Execute via MCP tool → Done
25    │  └─ ❌ MCP unavailable → Continue to Step 3
26    │
27    ▼
28Step 3: Fall back to SDK
29    │  Read references/sdk-operations.md for code
30    │
31    ▼
32Step 4: Execute and confirm result
33```
34 
35### Step 1: Resolve Project Context
36 
37The user needs a Foundry project endpoint. Check for:
38 
391. `PROJECT_ENDPOINT` environment variable
402. Ask the user for their project endpoint
413. Use `foundry_resource_get` MCP tool to discover it
42 
43Endpoint format: `https://<resource>.services.ai.azure.com/api/projects/<project>`
44 
45### Step 2: Create Agent (MCP — Preferred)
46 
47For a **prompt agent**:
48- Provide: agent name, model deployment name, instructions
49- Optional: tools (code interpreter, file search, function calling, web search, Bing grounding, memory)
50 
51For a **workflow**:
52- Workflows are created in the Foundry portal visual builder
53- Use MCP to create the individual agents that participate in the workflow
54- Direct the user to the Foundry portal for workflow assembly
55 
56### Step 3: SDK Fallback
57 
58If MCP tools are unavailable, use the `azure-ai-projects` SDK:
59- See [SDK Operations](references/sdk-operations.md) for create, list, update, delete code samples
60- See [Agent Tools](references/agent-tools.md) for adding tools to agents
61 
62### Step 4: Add Tools (Optional)
63 
64> ⚠️ **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.
65 
66| Tool Category | Reference |
67|---------------|-----------|
68| Code Interpreter, Function Calling | [Simple Tools](references/agent-tools.md) |
69| File Search (requires vector store) | [File Search](references/tool-file-search.md) |
70| Web Search (default, no setup needed) | [Web Search](references/tool-web-search.md) |
71| Bing Grounding (explicit request only) | [Bing Grounding](references/tool-bing-grounding.md) |
72| Azure AI Search (private data) | [Azure AI Search](references/tool-azure-ai-search.md) |
73| MCP Servers | [MCP Tool](references/tool-mcp.md) |
74| Memory (persistent across sessions) | [Memory](references/tool-memory.md) |
75| Connections (for tools that need them) | [Project Connections](../../project/connections.md) |
76 
77> ⚠️ **Web Search Default:** Use `WebSearchPreviewTool` for web search. Only use `BingGroundingAgentTool` when the user explicitly requests Bing Grounding.
78 
79## Error Handling
80 
81| Error | Cause | Resolution |
82|-------|-------|------------|
83| Agent creation fails | Missing model deployment | Deploy a model first via `foundry_models_deploy` or portal |
84| MCP tool not found | MCP server not running | Fall back to SDK — see [SDK Operations](references/sdk-operations.md) |
85| Permission denied | Insufficient RBAC | Need `Foundry User` role on the project |
86| Agent name conflict | Name already exists | Use a unique name or update the existing agent |
87| Tool not available | Tool not configured for project | Verify tool prerequisites (e.g., Bing resource for grounding) |
88| SDK version mismatch | Using 1.x instead of 2.x | Install `azure-ai-projects --pre` for v2.x preview |
89| Tenant mismatch | MCP token tenant differs from resource tenant | Fall back to SDK — `DefaultAzureCredential` resolves the correct tenant |
90