Create Prompt Agent

Create and manage prompt agents in Azure Foundry Agent Service using MCP tools or Python SDK. For hosted agents (container-based), see create.md.

Quick Reference

Workflow

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 result

Step 1: Resolve Project Context

The user needs a Foundry project endpoint. Check for:

1. PROJECT_ENDPOINT environment variable
2. Ask the user for their project endpoint
3. Use foundry_resource_get MCP tool to discover it

Endpoint format: https://<resource>.services.ai.azure.com/api/projects/<project>

Step 2: Create Agent (MCP — Preferred)

For a prompt agent:

• Provide: agent name, model deployment name, instructions
• Optional: tools (code interpreter, file search, function calling, web search, Bing grounding, memory)

For a workflow:

• Workflows are created in the Foundry portal visual builder
• Use MCP to create the individual agents that participate in the workflow
• Direct the user to the Foundry portal for workflow assembly

Step 3: SDK Fallback

If MCP tools are unavailable, use the azure-ai-projects SDK:

• See SDK Operations for create, list, update, delete code samples
• See Agent Tools for adding tools to agents

Step 4: Add Tools (Optional)

⚠️ 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.

⚠️ Web Search Default: Use WebSearchPreviewTool for web search. Only use BingGroundingAgentTool when the user explicitly requests Bing Grounding.

Error Handling