Tutorial: Idea to prototype - Build and evaluate an enterprise agent

Prototype an enterprise agent: build a single agent with SharePoint grounding and Model Context Protocol (MCP) tools, run batch evaluation, extend to multi-agent, and deploy to Microsoft Foundry.

Tutorial: Idea to prototype - Build and evaluate an enterprise agent

This tutorial covers the first stage of the Microsoft Foundry developer journey: from an initial idea to a working prototype. You build a modern workplace assistant that combines internal company knowledge with external technical guidance by using the Microsoft Foundry SDK.

Business scenario: Create an AI assistant that helps employees by combining:

• Company policies (from SharePoint documents)
• Technical implementation guidance (from Microsoft Learn via MCP)
• Complete solutions (combining both sources for business implementation)
• Batch evaluation to validate agent performance on realistic business scenarios

Tutorial outcome: By the end you have a running Modern Workplace Assistant that can answer policy, technical, and combined implementation questions; a repeatable batch evaluation script; and clear extension points (other tools, multi‑agent patterns, richer evaluation).

You will:

Code in this article uses packages that are currently in preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Prerequisites

• Azure subscription and CLI authentication (az login)
• Azure CLI 2.67.0 or later (check with az version)
• A Foundry project with a deployed model (for example, gpt-4o-mini). If you don’t have one: Create a project and then deploy a model (see model overview: Model catalog).
• Python 3.10 or later
• .NET SDK (for the C# sample)
• SharePoint connection configured in your project (SharePoint tool documentation)

To configure your Foundry project for SharePoint connectivity, see the SharePoint tool documentation.

• (Optional) Git installed for cloning the sample repository

Step 1: Get the sample code

Instead of navigating a large repository tree, use one of these approaches:

Option A (clone entire samples repo)

Code uses Azure AI Projects 2.x (preview) and is incompatible with Azure AI Projects 1.x.

Python

    git clone --depth 1 https://github.com/microsoft-foundry/foundry-samples.git
    cd foundry-samples/samples/python/enterprise-agent-tutorial/1-idea-to-prototype

Option B (sparse checkout only this tutorial - reduced download)

Python

    git clone --no-checkout https://github.com/microsoft-foundry/foundry-samples.git
    cd foundry-samples
    git sparse-checkout init --cone
    git sparse-checkout set samples/python/enterprise-agent-tutorial/1-idea-to-prototype
    git checkout
    cd samples/python/enterprise-agent-tutorial/1-idea-to-prototype

Option C (Download ZIP of repository)

Download the repository ZIP, extract it to your local environment, and go to the tutorial folder.

For production adoption, use a standalone repository. This tutorial uses the shared samples repo. Sparse checkout minimizes local noise.

Python

Download the Python code now

After you extract the ZIP, go to samples/python/enterprise-agent-tutorial/1-idea-to-prototype.

C#

Download the C# code now

After you extract the ZIP, go to samples/csharp/enterprise-agent-tutorial/1-idea-to-prototype.

The minimal structure contains only essential files:

Python

    enterprise-agent-tutorial/
    └── 1-idea-to-prototype/
       ├── .env                             # Create this file (local environment variables)
       ├── .gitkeep
       ├── evaluate.py                      # Business evaluation framework
       ├── evaluation_results.json
       ├── main.py                          # Modern Workplace Assistant
       ├── questions.jsonl                  # Business test scenarios (4 questions)
       ├── requirements.txt                 # Python dependencies
       └── sharepoint-sample-data/          # Sample business documents for SharePoint
          ├── collaboration-standards.docx
          ├── data-governance-policy.docx
          ├── remote-work-policy.docx
          └── security-guidelines.docx

Step 2: Run the sample immediately

Start by running the agent so you see working functionality before diving into implementation details.

Environment setup and virtual environment

1. Install the required language runtimes, global tools, and VS Code extensions as described in Prepare your development environment.

2. Verify that your requirements.txt uses these published package versions:

   azure-ai-projects==2.0.0b3
   azure-identity
   python-dotenv
   openai
   

3. Install dependencies:

   Python

   python -m pip install -r requirements.txt
   

   C#

   cd ModernWorkplaceAssistant
   dotnet restore
   
   cd ../Evaluate
   dotnet restore
   

   ---

4. Find your project endpoint on the welcome screen of the project.

1. Configure .env.

   Set the environment values required for your language.

Python

Copy .env.template to .env.

C#

Create a .env file in the ModernWorkplaceAssistant directory.

Python

    # Foundry configuration
    PROJECT_ENDPOINT=https://<your-project>.aiservices.azure.com
    MODEL_DEPLOYMENT_NAME=gpt-4o-mini

    # The Microsoft Learn MCP Server (optional)
    MCP_SERVER_URL=https://learn.microsoft.com/api/mcp

    # SharePoint integration (optional - requires connection name)
    SHAREPOINT_CONNECTION_NAME=<your-sharepoint-connection-name>

To get your tenant ID, run:

# Get tenant ID
az account show --query tenantId -o tsv

To get your project endpoint, open your project in the Foundry portal and copy the value shown there.

Run agent and evaluation

Python

    python main.py
    python evaluate.py

Expected output (agent first run)

Successful run with SharePoint:

🤖 Creating Modern Workplace Assistant...
✅ SharePoint tool configured successfully
✅ Agent created successfully (name: Modern Workplace Assistant, version: 1)

Graceful degradation without SharePoint:

📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_NAME not set)
✅ Agent created successfully (name: Modern Workplace Assistant, version: 1)

Now that you have a working agent, the next sections explain how it works. You don’t need to take any action while reading these sections—they’re for explanation.

Step 3: Set up sample SharePoint business documents

1. Go to your SharePoint site (configured in the connection).
2. Create document library “Company Policies” (or use existing “Documents”).
3. Upload the four sample Word documents provided in the sharepoint-sample-data folder:
   • remote-work-policy.docx
   • security-guidelines.docx
   • collaboration-standards.docx
   • data-governance-policy.docx

Sample structure

📁 Company Policies/
├── remote-work-policy.docx      # VPN, MFA, device requirements
├── security-guidelines.docx     # Azure security standards
├── collaboration-standards.docx # Teams, SharePoint usage
└── data-governance-policy.docx  # Data classification, retention

Step 4: Understand the assistant implementation

This section explains the core code in main.py (Python) or ModernWorkplaceAssistant/Program.cs (C#). You already ran the agent. This section is conceptual and requires no changes. After reading it, you can:

• Add new internal and external data tools.
• Extend dynamic instructions.
• Introduce multi-agent orchestration.
• Enhance observability and diagnostics.

The code breaks down into the following main sections, ordered as they appear in the full sample code:

1. Configure imports and authentication
2. Configure authentication to Azure
3. Configure the SharePoint tool
4. Configure MCP tool
5. Create the agent and connect the tools
6. Converse with the agent

Code in this article uses packages that are currently in preview. This preview is provided without a service-level agreement, and we don’t recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Imports and authentication setup

The code uses several client libraries from the Microsoft Foundry SDK to create a robust enterprise agent.

Python

    #!/usr/bin/env python3
    """
    Microsoft Foundry Agent Sample - Tutorial 1: Modern Workplace Assistant

    This sample demonstrates a complete business scenario using the Microsoft Foundry SDK:
    - Agent creation with PromptAgentDefinition
    - Conversation management via the Responses API
    - Robust error handling and graceful degradation

    Educational Focus:
    - Enterprise AI patterns with the Microsoft Foundry SDK
    - Real-world business scenarios that enterprises face daily
    - Production-ready error handling and diagnostics
    - Foundation for governance, evaluation, and monitoring (Tutorials 2-3)

    Business Scenario:
    An employee needs to implement Azure AD multi-factor authentication. They need:
    1. Company security policy requirements
    2. Technical implementation steps
    3. Combined guidance showing how policy requirements map to technical implementation
    """

    # <imports_and_includes>
    import os
    import time
    from azure.ai.projects import AIProjectClient
    from azure.ai.projects.models import (
        PromptAgentDefinition,
        SharepointPreviewTool,
        SharepointGroundingToolParameters,
        ToolProjectConnection,
        MCPTool,
    )
    from azure.identity import DefaultAzureCredential
    from dotenv import load_dotenv
    from openai.types.responses.response_input_param import (
        McpApprovalResponse,
    )
    # </imports_and_includes>

    load_dotenv()

    # ============================================================================
    # AUTHENTICATION SETUP
    # ============================================================================
    endpoint = os.environ["PROJECT_ENDPOINT"]

    def create_workplace_assistant(project_client):
        """
        Create a Modern Workplace Assistant using the Microsoft Foundry SDK.

        This demonstrates enterprise AI patterns:
        1. Agent creation with PromptAgentDefinition
        2. Robust error handling with graceful degradation
        3. Dynamic agent capabilities based on available resources
        4. Clear diagnostic information for troubleshooting

        Returns:
            agent: The created agent object
        """

        print("🤖 Creating Modern Workplace Assistant...")

        # ========================================================================
        # SHAREPOINT INTEGRATION SETUP
        # ========================================================================
        # <sharepoint_tool_setup>
        sharepoint_connection_id = os.environ.get("SHAREPOINT_CONNECTION_ID")
        sharepoint_tool = None

        if sharepoint_connection_id:
            print("📁 Configuring SharePoint integration...")
            print(f"   Connection ID: {sharepoint_connection_id}")

            try:
                sharepoint_tool = SharepointPreviewTool(
                    sharepoint_grounding_preview=SharepointGroundingToolParameters(
                        project_connections=[
                            ToolProjectConnection(
                                project_connection_id=sharepoint_connection_id
                            )
                        ]
                    )
                )
                print("✅ SharePoint tool configured successfully")
            except Exception as e:
                print(f"⚠️  SharePoint tool unavailable: {e}")
                print("   Agent will operate without SharePoint access")
                sharepoint_tool = None
        else:
            print("📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_ID not set)")
        # </sharepoint_tool_setup>

        # ========================================================================
        # MICROSOFT LEARN MCP INTEGRATION SETUP
        # ========================================================================
        # <mcp_tool_setup>
        mcp_server_url = os.environ.get("MCP_SERVER_URL")
        mcp_tool = None

        if mcp_server_url:
            print("📚 Configuring Microsoft Learn MCP integration...")
            print(f"   Server URL: {mcp_server_url}")

            try:
                mcp_tool = MCPTool(
                    server_url=mcp_server_url,
                    server_label="Microsoft_Learn_Documentation",
                    require_approval="always",
                )
                print("✅ MCP tool configured successfully")
            except Exception as e:
                print(f"⚠️  MCP tool unavailable: {e}")
                print("   Agent will operate without Microsoft Learn access")
                mcp_tool = None
        else:
            print("📚 MCP integration skipped (MCP_SERVER_URL not set)")
        # </mcp_tool_setup>

        # ========================================================================
        # AGENT CREATION WITH DYNAMIC CAPABILITIES
        # ========================================================================
        if sharepoint_tool and mcp_tool:
            instructions = """You are a Modern Workplace Assistant for Contoso Corporation.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide comprehensive solutions combining internal requirements with external implementation

    RESPONSE STRATEGY:
    - For policy questions: Search SharePoint for company-specific requirements and guidelines
    - For technical questions: Use Microsoft Learn for current Azure/M365 documentation
    - For implementation questions: Combine both sources to show how company policies map to technical implementation
    - Always cite your sources and provide step-by-step guidance"""
        elif sharepoint_tool:
            instructions = """You are a Modern Workplace Assistant with access to Contoso Corporation's SharePoint.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Provide detailed technical guidance based on your knowledge
    - Combine company policies with general best practices"""
        elif mcp_tool:
            instructions = """You are a Technical Assistant with access to Microsoft Learn documentation.

    CAPABILITIES:
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide detailed implementation steps and best practices
    - Explain Azure services, features, and configuration options"""
        else:
            instructions = """You are a Technical Assistant specializing in Azure and Microsoft 365 guidance.

    CAPABILITIES:
    - Provide detailed Azure and Microsoft 365 technical guidance
    - Explain implementation steps and best practices
    - Help with Azure AD, Conditional Access, MFA, and security configurations"""

        # <create_agent_with_tools>
        print(f"🛠️  Creating agent with model: {os.environ['MODEL_DEPLOYMENT_NAME']}")

        tools = []
        if sharepoint_tool:
            tools.append(sharepoint_tool)
            print("   ✓ SharePoint tool added")
        if mcp_tool:
            tools.append(mcp_tool)
            print("   ✓ MCP tool added")

        print(f"   Total tools: {len(tools)}")

        agent = project_client.agents.create_version(
            agent_name="Modern Workplace Assistant",
            definition=PromptAgentDefinition(
                model=os.environ["MODEL_DEPLOYMENT_NAME"],
                instructions=instructions,
                tools=tools if tools else None,
            ),
        )

        print(f"✅ Agent created successfully (name: {agent.name}, version: {agent.version})")
        return agent
        # </create_agent_with_tools>

    def demonstrate_business_scenarios(agent, openai_client):
        """
        Demonstrate realistic business scenarios with the Microsoft Foundry SDK.

        This function showcases the practical value of the Modern Workplace Assistant
        by walking through scenarios that enterprise employees face regularly.
        """

        scenarios = [
            {
                "title": "📋 Company Policy Question (SharePoint Only)",
                "question": "What is Contoso's remote work policy?",
                "context": "Employee needs to understand company-specific remote work requirements",
                "learning_point": "SharePoint tool retrieves internal company policies",
            },
            {
                "title": "📚 Technical Documentation Question (MCP Only)",
                "question": (
                    "According to Microsoft Learn, what is the correct way to implement "
                    "Azure AD Conditional Access policies? Please include reference links "
                    "to the official documentation."
                ),
                "context": "IT administrator needs authoritative Microsoft technical guidance",
                "learning_point": "MCP tool accesses Microsoft Learn for official documentation with links",
            },
            {
                "title": "🔄 Combined Implementation Question (SharePoint + MCP)",
                "question": (
                    "Based on our company's remote work security policy, how should I configure "
                    "my Azure environment to comply? Please include links to Microsoft "
                    "documentation showing how to implement each requirement."
                ),
                "context": "Need to map company policy to technical implementation with official guidance",
                "learning_point": "Both tools work together: SharePoint for policy + MCP for implementation docs",
            },
        ]

        print("\n" + "=" * 70)
        print("🏢 MODERN WORKPLACE ASSISTANT - BUSINESS SCENARIO DEMONSTRATION")
        print("=" * 70)
        print("This demonstration shows how AI agents solve real business problems")
        print("using the Microsoft Foundry SDK.")
        print("=" * 70)

        for i, scenario in enumerate(scenarios, 1):
            print(f"\n📊 SCENARIO {i}/3: {scenario['title']}")
            print("-" * 50)
            print(f"❓ QUESTION: {scenario['question']}")
            print(f"🎯 BUSINESS CONTEXT: {scenario['context']}")
            print(f"🎓 LEARNING POINT: {scenario['learning_point']}")
            print("-" * 50)

            # <agent_conversation>
            print("🤖 AGENT RESPONSE:")
            response, status = create_agent_response(agent, scenario["question"], openai_client)
            # </agent_conversation>

            if status == "completed" and response and len(response.strip()) > 10:
                print(f"✅ SUCCESS: {response[:300]}...")
                if len(response) > 300:
                    print(f"   📏 Full response: {len(response)} characters")
            else:
                print(f"⚠️  RESPONSE: {response}")

            print(f"📈 STATUS: {status}")
            print("-" * 50)

            time.sleep(1)

        print("\n✅ DEMONSTRATION COMPLETED!")
        print("🎓 Key Learning Outcomes:")
        print("   • Microsoft Foundry SDK usage for enterprise AI")
        print("   • Conversation management via the Responses API")
        print("   • Real business value through AI assistance")
        print("   • Foundation for governance and monitoring (Tutorials 2-3)")

        return True

    def create_agent_response(agent, message, openai_client):
        """
        Create a response from the workplace agent using the Responses API.

        This function demonstrates the response pattern for the Microsoft Foundry SDK
        including MCP tool approval handling.

        Args:
            agent: The agent object (with .name attribute)
            message: The user's message

        Returns:
            tuple: (response_text, status)
        """

        try:
            response = openai_client.responses.create(
                input=message,
                extra_body={
                    "agent": {"name": agent.name, "type": "agent_reference"}
                },
            )

            # Handle MCP approval requests if present
            approval_list = []
            for item in response.output:
                if item.type == "mcp_approval_request" and item.id:
                    approval_list.append(
                        McpApprovalResponse(
                            type="mcp_approval_response",
                            approve=True,
                            approval_request_id=item.id,
                        )
                    )

            if approval_list:
                response = openai_client.responses.create(
                    input=approval_list,
                    previous_response_id=response.id,
                    extra_body={
                        "agent": {"name": agent.name, "type": "agent_reference"}
                    },
                )

            return response.output_text, "completed"

        except Exception as e:
            return f"Error in conversation: {str(e)}", "failed"

    def interactive_mode(agent, openai_client):
        """Interactive mode for testing the workplace agent."""

        print("\n" + "=" * 60)
        print("💬 INTERACTIVE MODE - Test Your Workplace Agent!")
        print("=" * 60)
        print("Ask questions about Azure, M365, security, and technical implementation.")
        print("Type 'quit' to exit.")
        print("-" * 60)

        while True:
            try:
                question = input("\n❓ Your question: ").strip()

                if question.lower() in ["quit", "exit", "bye"]:
                    break

                if not question:
                    print("💡 Please ask a question about Azure or M365 technical implementation.")
                    continue

                print("\n🤖 Workplace Agent: ", end="", flush=True)
                response, status = create_agent_response(agent, question, openai_client)
                print(response)

                if status != "completed":
                    print(f"\n⚠️  Response status: {status}")

                print("-" * 60)

            except KeyboardInterrupt:
                break
            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("-" * 60)

        print("\n👋 Thank you for testing the Modern Workplace Agent!")

    def main():
        """Main execution flow demonstrating the complete sample."""

        print("🚀 Foundry - Modern Workplace Assistant")
        print("Tutorial 1: Building Enterprise Agents with Microsoft Foundry SDK")
        print("=" * 70)

        # <agent_authentication>
        with (
            DefaultAzureCredential() as credential,
            AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
            project_client.get_openai_client() as openai_client,
        ):
            print(f"✅ Connected to Foundry: {endpoint}")
        # </agent_authentication>

            try:
                agent = create_workplace_assistant(project_client)
                demonstrate_business_scenarios(agent, openai_client)

                print("\n🎯 Try interactive mode? (y/n): ", end="")
                try:
                    if input().lower().startswith("y"):
                        interactive_mode(agent, openai_client)
                except EOFError:
                    print("n")

                print("\n🎉 Sample completed successfully!")
                print("📚 This foundation supports Tutorial 2 (Governance) and Tutorial 3 (Production)")
                print("🔗 Next: Add evaluation metrics, monitoring, and production deployment")

            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("Please check your .env configuration and ensure:")
                print("  - PROJECT_ENDPOINT is correct")
                print("  - MODEL_DEPLOYMENT_NAME is deployed")
                print("  - Azure credentials are configured (az login)")

    if __name__ == "__main__":
        main()

Configure authentication in Azure

Before you create your agent, set up authentication to the Foundry.

Python

    #!/usr/bin/env python3
    """
    Microsoft Foundry Agent Sample - Tutorial 1: Modern Workplace Assistant

    This sample demonstrates a complete business scenario using the Microsoft Foundry SDK:
    - Agent creation with PromptAgentDefinition
    - Conversation management via the Responses API
    - Robust error handling and graceful degradation

    Educational Focus:
    - Enterprise AI patterns with the Microsoft Foundry SDK
    - Real-world business scenarios that enterprises face daily
    - Production-ready error handling and diagnostics
    - Foundation for governance, evaluation, and monitoring (Tutorials 2-3)

    Business Scenario:
    An employee needs to implement Azure AD multi-factor authentication. They need:
    1. Company security policy requirements
    2. Technical implementation steps
    3. Combined guidance showing how policy requirements map to technical implementation
    """

    # <imports_and_includes>
    import os
    import time
    from azure.ai.projects import AIProjectClient
    from azure.ai.projects.models import (
        PromptAgentDefinition,
        SharepointPreviewTool,
        SharepointGroundingToolParameters,
        ToolProjectConnection,
        MCPTool,
    )
    from azure.identity import DefaultAzureCredential
    from dotenv import load_dotenv
    from openai.types.responses.response_input_param import (
        McpApprovalResponse,
    )
    # </imports_and_includes>

    load_dotenv()

    # ============================================================================
    # AUTHENTICATION SETUP
    # ============================================================================
    endpoint = os.environ["PROJECT_ENDPOINT"]

    def create_workplace_assistant(project_client):
        """
        Create a Modern Workplace Assistant using the Microsoft Foundry SDK.

        This demonstrates enterprise AI patterns:
        1. Agent creation with PromptAgentDefinition
        2. Robust error handling with graceful degradation
        3. Dynamic agent capabilities based on available resources
        4. Clear diagnostic information for troubleshooting

        Returns:
            agent: The created agent object
        """

        print("🤖 Creating Modern Workplace Assistant...")

        # ========================================================================
        # SHAREPOINT INTEGRATION SETUP
        # ========================================================================
        # <sharepoint_tool_setup>
        sharepoint_connection_id = os.environ.get("SHAREPOINT_CONNECTION_ID")
        sharepoint_tool = None

        if sharepoint_connection_id:
            print("📁 Configuring SharePoint integration...")
            print(f"   Connection ID: {sharepoint_connection_id}")

            try:
                sharepoint_tool = SharepointPreviewTool(
                    sharepoint_grounding_preview=SharepointGroundingToolParameters(
                        project_connections=[
                            ToolProjectConnection(
                                project_connection_id=sharepoint_connection_id
                            )
                        ]
                    )
                )
                print("✅ SharePoint tool configured successfully")
            except Exception as e:
                print(f"⚠️  SharePoint tool unavailable: {e}")
                print("   Agent will operate without SharePoint access")
                sharepoint_tool = None
        else:
            print("📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_ID not set)")
        # </sharepoint_tool_setup>

        # ========================================================================
        # MICROSOFT LEARN MCP INTEGRATION SETUP
        # ========================================================================
        # <mcp_tool_setup>
        mcp_server_url = os.environ.get("MCP_SERVER_URL")
        mcp_tool = None

        if mcp_server_url:
            print("📚 Configuring Microsoft Learn MCP integration...")
            print(f"   Server URL: {mcp_server_url}")

            try:
                mcp_tool = MCPTool(
                    server_url=mcp_server_url,
                    server_label="Microsoft_Learn_Documentation",
                    require_approval="always",
                )
                print("✅ MCP tool configured successfully")
            except Exception as e:
                print(f"⚠️  MCP tool unavailable: {e}")
                print("   Agent will operate without Microsoft Learn access")
                mcp_tool = None
        else:
            print("📚 MCP integration skipped (MCP_SERVER_URL not set)")
        # </mcp_tool_setup>

        # ========================================================================
        # AGENT CREATION WITH DYNAMIC CAPABILITIES
        # ========================================================================
        if sharepoint_tool and mcp_tool:
            instructions = """You are a Modern Workplace Assistant for Contoso Corporation.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide comprehensive solutions combining internal requirements with external implementation

    RESPONSE STRATEGY:
    - For policy questions: Search SharePoint for company-specific requirements and guidelines
    - For technical questions: Use Microsoft Learn for current Azure/M365 documentation
    - For implementation questions: Combine both sources to show how company policies map to technical implementation
    - Always cite your sources and provide step-by-step guidance"""
        elif sharepoint_tool:
            instructions = """You are a Modern Workplace Assistant with access to Contoso Corporation's SharePoint.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Provide detailed technical guidance based on your knowledge
    - Combine company policies with general best practices"""
        elif mcp_tool:
            instructions = """You are a Technical Assistant with access to Microsoft Learn documentation.

    CAPABILITIES:
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide detailed implementation steps and best practices
    - Explain Azure services, features, and configuration options"""
        else:
            instructions = """You are a Technical Assistant specializing in Azure and Microsoft 365 guidance.

    CAPABILITIES:
    - Provide detailed Azure and Microsoft 365 technical guidance
    - Explain implementation steps and best practices
    - Help with Azure AD, Conditional Access, MFA, and security configurations"""

        # <create_agent_with_tools>
        print(f"🛠️  Creating agent with model: {os.environ['MODEL_DEPLOYMENT_NAME']}")

        tools = []
        if sharepoint_tool:
            tools.append(sharepoint_tool)
            print("   ✓ SharePoint tool added")
        if mcp_tool:
            tools.append(mcp_tool)
            print("   ✓ MCP tool added")

        print(f"   Total tools: {len(tools)}")

        agent = project_client.agents.create_version(
            agent_name="Modern Workplace Assistant",
            definition=PromptAgentDefinition(
                model=os.environ["MODEL_DEPLOYMENT_NAME"],
                instructions=instructions,
                tools=tools if tools else None,
            ),
        )

        print(f"✅ Agent created successfully (name: {agent.name}, version: {agent.version})")
        return agent
        # </create_agent_with_tools>

    def demonstrate_business_scenarios(agent, openai_client):
        """
        Demonstrate realistic business scenarios with the Microsoft Foundry SDK.

        This function showcases the practical value of the Modern Workplace Assistant
        by walking through scenarios that enterprise employees face regularly.
        """

        scenarios = [
            {
                "title": "📋 Company Policy Question (SharePoint Only)",
                "question": "What is Contoso's remote work policy?",
                "context": "Employee needs to understand company-specific remote work requirements",
                "learning_point": "SharePoint tool retrieves internal company policies",
            },
            {
                "title": "📚 Technical Documentation Question (MCP Only)",
                "question": (
                    "According to Microsoft Learn, what is the correct way to implement "
                    "Azure AD Conditional Access policies? Please include reference links "
                    "to the official documentation."
                ),
                "context": "IT administrator needs authoritative Microsoft technical guidance",
                "learning_point": "MCP tool accesses Microsoft Learn for official documentation with links",
            },
            {
                "title": "🔄 Combined Implementation Question (SharePoint + MCP)",
                "question": (
                    "Based on our company's remote work security policy, how should I configure "
                    "my Azure environment to comply? Please include links to Microsoft "
                    "documentation showing how to implement each requirement."
                ),
                "context": "Need to map company policy to technical implementation with official guidance",
                "learning_point": "Both tools work together: SharePoint for policy + MCP for implementation docs",
            },
        ]

        print("\n" + "=" * 70)
        print("🏢 MODERN WORKPLACE ASSISTANT - BUSINESS SCENARIO DEMONSTRATION")
        print("=" * 70)
        print("This demonstration shows how AI agents solve real business problems")
        print("using the Microsoft Foundry SDK.")
        print("=" * 70)

        for i, scenario in enumerate(scenarios, 1):
            print(f"\n📊 SCENARIO {i}/3: {scenario['title']}")
            print("-" * 50)
            print(f"❓ QUESTION: {scenario['question']}")
            print(f"🎯 BUSINESS CONTEXT: {scenario['context']}")
            print(f"🎓 LEARNING POINT: {scenario['learning_point']}")
            print("-" * 50)

            # <agent_conversation>
            print("🤖 AGENT RESPONSE:")
            response, status = create_agent_response(agent, scenario["question"], openai_client)
            # </agent_conversation>

            if status == "completed" and response and len(response.strip()) > 10:
                print(f"✅ SUCCESS: {response[:300]}...")
                if len(response) > 300:
                    print(f"   📏 Full response: {len(response)} characters")
            else:
                print(f"⚠️  RESPONSE: {response}")

            print(f"📈 STATUS: {status}")
            print("-" * 50)

            time.sleep(1)

        print("\n✅ DEMONSTRATION COMPLETED!")
        print("🎓 Key Learning Outcomes:")
        print("   • Microsoft Foundry SDK usage for enterprise AI")
        print("   • Conversation management via the Responses API")
        print("   • Real business value through AI assistance")
        print("   • Foundation for governance and monitoring (Tutorials 2-3)")

        return True

    def create_agent_response(agent, message, openai_client):
        """
        Create a response from the workplace agent using the Responses API.

        This function demonstrates the response pattern for the Microsoft Foundry SDK
        including MCP tool approval handling.

        Args:
            agent: The agent object (with .name attribute)
            message: The user's message

        Returns:
            tuple: (response_text, status)
        """

        try:
            response = openai_client.responses.create(
                input=message,
                extra_body={
                    "agent": {"name": agent.name, "type": "agent_reference"}
                },
            )

            # Handle MCP approval requests if present
            approval_list = []
            for item in response.output:
                if item.type == "mcp_approval_request" and item.id:
                    approval_list.append(
                        McpApprovalResponse(
                            type="mcp_approval_response",
                            approve=True,
                            approval_request_id=item.id,
                        )
                    )

            if approval_list:
                response = openai_client.responses.create(
                    input=approval_list,
                    previous_response_id=response.id,
                    extra_body={
                        "agent": {"name": agent.name, "type": "agent_reference"}
                    },
                )

            return response.output_text, "completed"

        except Exception as e:
            return f"Error in conversation: {str(e)}", "failed"

    def interactive_mode(agent, openai_client):
        """Interactive mode for testing the workplace agent."""

        print("\n" + "=" * 60)
        print("💬 INTERACTIVE MODE - Test Your Workplace Agent!")
        print("=" * 60)
        print("Ask questions about Azure, M365, security, and technical implementation.")
        print("Type 'quit' to exit.")
        print("-" * 60)

        while True:
            try:
                question = input("\n❓ Your question: ").strip()

                if question.lower() in ["quit", "exit", "bye"]:
                    break

                if not question:
                    print("💡 Please ask a question about Azure or M365 technical implementation.")
                    continue

                print("\n🤖 Workplace Agent: ", end="", flush=True)
                response, status = create_agent_response(agent, question, openai_client)
                print(response)

                if status != "completed":
                    print(f"\n⚠️  Response status: {status}")

                print("-" * 60)

            except KeyboardInterrupt:
                break
            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("-" * 60)

        print("\n👋 Thank you for testing the Modern Workplace Agent!")

    def main():
        """Main execution flow demonstrating the complete sample."""

        print("🚀 Foundry - Modern Workplace Assistant")
        print("Tutorial 1: Building Enterprise Agents with Microsoft Foundry SDK")
        print("=" * 70)

        # <agent_authentication>
        with (
            DefaultAzureCredential() as credential,
            AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
            project_client.get_openai_client() as openai_client,
        ):
            print(f"✅ Connected to Foundry: {endpoint}")
        # </agent_authentication>

            try:
                agent = create_workplace_assistant(project_client)
                demonstrate_business_scenarios(agent, openai_client)

                print("\n🎯 Try interactive mode? (y/n): ", end="")
                try:
                    if input().lower().startswith("y"):
                        interactive_mode(agent, openai_client)
                except EOFError:
                    print("n")

                print("\n🎉 Sample completed successfully!")
                print("📚 This foundation supports Tutorial 2 (Governance) and Tutorial 3 (Production)")
                print("🔗 Next: Add evaluation metrics, monitoring, and production deployment")

            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("Please check your .env configuration and ensure:")
                print("  - PROJECT_ENDPOINT is correct")
                print("  - MODEL_DEPLOYMENT_NAME is deployed")
                print("  - Azure credentials are configured (az login)")

    if __name__ == "__main__":
        main()

Create the SharePoint tool for the agent

The agent uses SharePoint and can access company policy and procedure documents stored there. Set up the connection to SharePoint in your code.

Python

    #!/usr/bin/env python3
    """
    Microsoft Foundry Agent Sample - Tutorial 1: Modern Workplace Assistant

    This sample demonstrates a complete business scenario using the Microsoft Foundry SDK:
    - Agent creation with PromptAgentDefinition
    - Conversation management via the Responses API
    - Robust error handling and graceful degradation

    Educational Focus:
    - Enterprise AI patterns with the Microsoft Foundry SDK
    - Real-world business scenarios that enterprises face daily
    - Production-ready error handling and diagnostics
    - Foundation for governance, evaluation, and monitoring (Tutorials 2-3)

    Business Scenario:
    An employee needs to implement Azure AD multi-factor authentication. They need:
    1. Company security policy requirements
    2. Technical implementation steps
    3. Combined guidance showing how policy requirements map to technical implementation
    """

    # <imports_and_includes>
    import os
    import time
    from azure.ai.projects import AIProjectClient
    from azure.ai.projects.models import (
        PromptAgentDefinition,
        SharepointPreviewTool,
        SharepointGroundingToolParameters,
        ToolProjectConnection,
        MCPTool,
    )
    from azure.identity import DefaultAzureCredential
    from dotenv import load_dotenv
    from openai.types.responses.response_input_param import (
        McpApprovalResponse,
    )
    # </imports_and_includes>

    load_dotenv()

    # ============================================================================
    # AUTHENTICATION SETUP
    # ============================================================================
    endpoint = os.environ["PROJECT_ENDPOINT"]

    def create_workplace_assistant(project_client):
        """
        Create a Modern Workplace Assistant using the Microsoft Foundry SDK.

        This demonstrates enterprise AI patterns:
        1. Agent creation with PromptAgentDefinition
        2. Robust error handling with graceful degradation
        3. Dynamic agent capabilities based on available resources
        4. Clear diagnostic information for troubleshooting

        Returns:
            agent: The created agent object
        """

        print("🤖 Creating Modern Workplace Assistant...")

        # ========================================================================
        # SHAREPOINT INTEGRATION SETUP
        # ========================================================================
        # <sharepoint_tool_setup>
        sharepoint_connection_id = os.environ.get("SHAREPOINT_CONNECTION_ID")
        sharepoint_tool = None

        if sharepoint_connection_id:
            print("📁 Configuring SharePoint integration...")
            print(f"   Connection ID: {sharepoint_connection_id}")

            try:
                sharepoint_tool = SharepointPreviewTool(
                    sharepoint_grounding_preview=SharepointGroundingToolParameters(
                        project_connections=[
                            ToolProjectConnection(
                                project_connection_id=sharepoint_connection_id
                            )
                        ]
                    )
                )
                print("✅ SharePoint tool configured successfully")
            except Exception as e:
                print(f"⚠️  SharePoint tool unavailable: {e}")
                print("   Agent will operate without SharePoint access")
                sharepoint_tool = None
        else:
            print("📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_ID not set)")
        # </sharepoint_tool_setup>

        # ========================================================================
        # MICROSOFT LEARN MCP INTEGRATION SETUP
        # ========================================================================
        # <mcp_tool_setup>
        mcp_server_url = os.environ.get("MCP_SERVER_URL")
        mcp_tool = None

        if mcp_server_url:
            print("📚 Configuring Microsoft Learn MCP integration...")
            print(f"   Server URL: {mcp_server_url}")

            try:
                mcp_tool = MCPTool(
                    server_url=mcp_server_url,
                    server_label="Microsoft_Learn_Documentation",
                    require_approval="always",
                )
                print("✅ MCP tool configured successfully")
            except Exception as e:
                print(f"⚠️  MCP tool unavailable: {e}")
                print("   Agent will operate without Microsoft Learn access")
                mcp_tool = None
        else:
            print("📚 MCP integration skipped (MCP_SERVER_URL not set)")
        # </mcp_tool_setup>

        # ========================================================================
        # AGENT CREATION WITH DYNAMIC CAPABILITIES
        # ========================================================================
        if sharepoint_tool and mcp_tool:
            instructions = """You are a Modern Workplace Assistant for Contoso Corporation.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide comprehensive solutions combining internal requirements with external implementation

    RESPONSE STRATEGY:
    - For policy questions: Search SharePoint for company-specific requirements and guidelines
    - For technical questions: Use Microsoft Learn for current Azure/M365 documentation
    - For implementation questions: Combine both sources to show how company policies map to technical implementation
    - Always cite your sources and provide step-by-step guidance"""
        elif sharepoint_tool:
            instructions = """You are a Modern Workplace Assistant with access to Contoso Corporation's SharePoint.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Provide detailed technical guidance based on your knowledge
    - Combine company policies with general best practices"""
        elif mcp_tool:
            instructions = """You are a Technical Assistant with access to Microsoft Learn documentation.

    CAPABILITIES:
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide detailed implementation steps and best practices
    - Explain Azure services, features, and configuration options"""
        else:
            instructions = """You are a Technical Assistant specializing in Azure and Microsoft 365 guidance.

    CAPABILITIES:
    - Provide detailed Azure and Microsoft 365 technical guidance
    - Explain implementation steps and best practices
    - Help with Azure AD, Conditional Access, MFA, and security configurations"""

        # <create_agent_with_tools>
        print(f"🛠️  Creating agent with model: {os.environ['MODEL_DEPLOYMENT_NAME']}")

        tools = []
        if sharepoint_tool:
            tools.append(sharepoint_tool)
            print("   ✓ SharePoint tool added")
        if mcp_tool:
            tools.append(mcp_tool)
            print("   ✓ MCP tool added")

        print(f"   Total tools: {len(tools)}")

        agent = project_client.agents.create_version(
            agent_name="Modern Workplace Assistant",
            definition=PromptAgentDefinition(
                model=os.environ["MODEL_DEPLOYMENT_NAME"],
                instructions=instructions,
                tools=tools if tools else None,
            ),
        )

        print(f"✅ Agent created successfully (name: {agent.name}, version: {agent.version})")
        return agent
        # </create_agent_with_tools>

    def demonstrate_business_scenarios(agent, openai_client):
        """
        Demonstrate realistic business scenarios with the Microsoft Foundry SDK.

        This function showcases the practical value of the Modern Workplace Assistant
        by walking through scenarios that enterprise employees face regularly.
        """

        scenarios = [
            {
                "title": "📋 Company Policy Question (SharePoint Only)",
                "question": "What is Contoso's remote work policy?",
                "context": "Employee needs to understand company-specific remote work requirements",
                "learning_point": "SharePoint tool retrieves internal company policies",
            },
            {
                "title": "📚 Technical Documentation Question (MCP Only)",
                "question": (
                    "According to Microsoft Learn, what is the correct way to implement "
                    "Azure AD Conditional Access policies? Please include reference links "
                    "to the official documentation."
                ),
                "context": "IT administrator needs authoritative Microsoft technical guidance",
                "learning_point": "MCP tool accesses Microsoft Learn for official documentation with links",
            },
            {
                "title": "🔄 Combined Implementation Question (SharePoint + MCP)",
                "question": (
                    "Based on our company's remote work security policy, how should I configure "
                    "my Azure environment to comply? Please include links to Microsoft "
                    "documentation showing how to implement each requirement."
                ),
                "context": "Need to map company policy to technical implementation with official guidance",
                "learning_point": "Both tools work together: SharePoint for policy + MCP for implementation docs",
            },
        ]

        print("\n" + "=" * 70)
        print("🏢 MODERN WORKPLACE ASSISTANT - BUSINESS SCENARIO DEMONSTRATION")
        print("=" * 70)
        print("This demonstration shows how AI agents solve real business problems")
        print("using the Microsoft Foundry SDK.")
        print("=" * 70)

        for i, scenario in enumerate(scenarios, 1):
            print(f"\n📊 SCENARIO {i}/3: {scenario['title']}")
            print("-" * 50)
            print(f"❓ QUESTION: {scenario['question']}")
            print(f"🎯 BUSINESS CONTEXT: {scenario['context']}")
            print(f"🎓 LEARNING POINT: {scenario['learning_point']}")
            print("-" * 50)

            # <agent_conversation>
            print("🤖 AGENT RESPONSE:")
            response, status = create_agent_response(agent, scenario["question"], openai_client)
            # </agent_conversation>

            if status == "completed" and response and len(response.strip()) > 10:
                print(f"✅ SUCCESS: {response[:300]}...")
                if len(response) > 300:
                    print(f"   📏 Full response: {len(response)} characters")
            else:
                print(f"⚠️  RESPONSE: {response}")

            print(f"📈 STATUS: {status}")
            print("-" * 50)

            time.sleep(1)

        print("\n✅ DEMONSTRATION COMPLETED!")
        print("🎓 Key Learning Outcomes:")
        print("   • Microsoft Foundry SDK usage for enterprise AI")
        print("   • Conversation management via the Responses API")
        print("   • Real business value through AI assistance")
        print("   • Foundation for governance and monitoring (Tutorials 2-3)")

        return True

    def create_agent_response(agent, message, openai_client):
        """
        Create a response from the workplace agent using the Responses API.

        This function demonstrates the response pattern for the Microsoft Foundry SDK
        including MCP tool approval handling.

        Args:
            agent: The agent object (with .name attribute)
            message: The user's message

        Returns:
            tuple: (response_text, status)
        """

        try:
            response = openai_client.responses.create(
                input=message,
                extra_body={
                    "agent": {"name": agent.name, "type": "agent_reference"}
                },
            )

            # Handle MCP approval requests if present
            approval_list = []
            for item in response.output:
                if item.type == "mcp_approval_request" and item.id:
                    approval_list.append(
                        McpApprovalResponse(
                            type="mcp_approval_response",
                            approve=True,
                            approval_request_id=item.id,
                        )
                    )

            if approval_list:
                response = openai_client.responses.create(
                    input=approval_list,
                    previous_response_id=response.id,
                    extra_body={
                        "agent": {"name": agent.name, "type": "agent_reference"}
                    },
                )

            return response.output_text, "completed"

        except Exception as e:
            return f"Error in conversation: {str(e)}", "failed"

    def interactive_mode(agent, openai_client):
        """Interactive mode for testing the workplace agent."""

        print("\n" + "=" * 60)
        print("💬 INTERACTIVE MODE - Test Your Workplace Agent!")
        print("=" * 60)
        print("Ask questions about Azure, M365, security, and technical implementation.")
        print("Type 'quit' to exit.")
        print("-" * 60)

        while True:
            try:
                question = input("\n❓ Your question: ").strip()

                if question.lower() in ["quit", "exit", "bye"]:
                    break

                if not question:
                    print("💡 Please ask a question about Azure or M365 technical implementation.")
                    continue

                print("\n🤖 Workplace Agent: ", end="", flush=True)
                response, status = create_agent_response(agent, question, openai_client)
                print(response)

                if status != "completed":
                    print(f"\n⚠️  Response status: {status}")

                print("-" * 60)

            except KeyboardInterrupt:
                break
            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("-" * 60)

        print("\n👋 Thank you for testing the Modern Workplace Agent!")

    def main():
        """Main execution flow demonstrating the complete sample."""

        print("🚀 Foundry - Modern Workplace Assistant")
        print("Tutorial 1: Building Enterprise Agents with Microsoft Foundry SDK")
        print("=" * 70)

        # <agent_authentication>
        with (
            DefaultAzureCredential() as credential,
            AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
            project_client.get_openai_client() as openai_client,
        ):
            print(f"✅ Connected to Foundry: {endpoint}")
        # </agent_authentication>

            try:
                agent = create_workplace_assistant(project_client)
                demonstrate_business_scenarios(agent, openai_client)

                print("\n🎯 Try interactive mode? (y/n): ", end="")
                try:
                    if input().lower().startswith("y"):
                        interactive_mode(agent, openai_client)
                except EOFError:
                    print("n")

                print("\n🎉 Sample completed successfully!")
                print("📚 This foundation supports Tutorial 2 (Governance) and Tutorial 3 (Production)")
                print("🔗 Next: Add evaluation metrics, monitoring, and production deployment")

            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("Please check your .env configuration and ensure:")
                print("  - PROJECT_ENDPOINT is correct")
                print("  - MODEL_DEPLOYMENT_NAME is deployed")
                print("  - Azure credentials are configured (az login)")

    if __name__ == "__main__":
        main()

Create the MCP tool for the agent

Python

    #!/usr/bin/env python3
    """
    Microsoft Foundry Agent Sample - Tutorial 1: Modern Workplace Assistant

    This sample demonstrates a complete business scenario using the Microsoft Foundry SDK:
    - Agent creation with PromptAgentDefinition
    - Conversation management via the Responses API
    - Robust error handling and graceful degradation

    Educational Focus:
    - Enterprise AI patterns with the Microsoft Foundry SDK
    - Real-world business scenarios that enterprises face daily
    - Production-ready error handling and diagnostics
    - Foundation for governance, evaluation, and monitoring (Tutorials 2-3)

    Business Scenario:
    An employee needs to implement Azure AD multi-factor authentication. They need:
    1. Company security policy requirements
    2. Technical implementation steps
    3. Combined guidance showing how policy requirements map to technical implementation
    """

    # <imports_and_includes>
    import os
    import time
    from azure.ai.projects import AIProjectClient
    from azure.ai.projects.models import (
        PromptAgentDefinition,
        SharepointPreviewTool,
        SharepointGroundingToolParameters,
        ToolProjectConnection,
        MCPTool,
    )
    from azure.identity import DefaultAzureCredential
    from dotenv import load_dotenv
    from openai.types.responses.response_input_param import (
        McpApprovalResponse,
    )
    # </imports_and_includes>

    load_dotenv()

    # ============================================================================
    # AUTHENTICATION SETUP
    # ============================================================================
    endpoint = os.environ["PROJECT_ENDPOINT"]

    def create_workplace_assistant(project_client):
        """
        Create a Modern Workplace Assistant using the Microsoft Foundry SDK.

        This demonstrates enterprise AI patterns:
        1. Agent creation with PromptAgentDefinition
        2. Robust error handling with graceful degradation
        3. Dynamic agent capabilities based on available resources
        4. Clear diagnostic information for troubleshooting

        Returns:
            agent: The created agent object
        """

        print("🤖 Creating Modern Workplace Assistant...")

        # ========================================================================
        # SHAREPOINT INTEGRATION SETUP
        # ========================================================================
        # <sharepoint_tool_setup>
        sharepoint_connection_id = os.environ.get("SHAREPOINT_CONNECTION_ID")
        sharepoint_tool = None

        if sharepoint_connection_id:
            print("📁 Configuring SharePoint integration...")
            print(f"   Connection ID: {sharepoint_connection_id}")

            try:
                sharepoint_tool = SharepointPreviewTool(
                    sharepoint_grounding_preview=SharepointGroundingToolParameters(
                        project_connections=[
                            ToolProjectConnection(
                                project_connection_id=sharepoint_connection_id
                            )
                        ]
                    )
                )
                print("✅ SharePoint tool configured successfully")
            except Exception as e:
                print(f"⚠️  SharePoint tool unavailable: {e}")
                print("   Agent will operate without SharePoint access")
                sharepoint_tool = None
        else:
            print("📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_ID not set)")
        # </sharepoint_tool_setup>

        # ========================================================================
        # MICROSOFT LEARN MCP INTEGRATION SETUP
        # ========================================================================
        # <mcp_tool_setup>
        mcp_server_url = os.environ.get("MCP_SERVER_URL")
        mcp_tool = None

        if mcp_server_url:
            print("📚 Configuring Microsoft Learn MCP integration...")
            print(f"   Server URL: {mcp_server_url}")

            try:
                mcp_tool = MCPTool(
                    server_url=mcp_server_url,
                    server_label="Microsoft_Learn_Documentation",
                    require_approval="always",
                )
                print("✅ MCP tool configured successfully")
            except Exception as e:
                print(f"⚠️  MCP tool unavailable: {e}")
                print("   Agent will operate without Microsoft Learn access")
                mcp_tool = None
        else:
            print("📚 MCP integration skipped (MCP_SERVER_URL not set)")
        # </mcp_tool_setup>

        # ========================================================================
        # AGENT CREATION WITH DYNAMIC CAPABILITIES
        # ========================================================================
        if sharepoint_tool and mcp_tool:
            instructions = """You are a Modern Workplace Assistant for Contoso Corporation.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide comprehensive solutions combining internal requirements with external implementation

    RESPONSE STRATEGY:
    - For policy questions: Search SharePoint for company-specific requirements and guidelines
    - For technical questions: Use Microsoft Learn for current Azure/M365 documentation
    - For implementation questions: Combine both sources to show how company policies map to technical implementation
    - Always cite your sources and provide step-by-step guidance"""
        elif sharepoint_tool:
            instructions = """You are a Modern Workplace Assistant with access to Contoso Corporation's SharePoint.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Provide detailed technical guidance based on your knowledge
    - Combine company policies with general best practices"""
        elif mcp_tool:
            instructions = """You are a Technical Assistant with access to Microsoft Learn documentation.

    CAPABILITIES:
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide detailed implementation steps and best practices
    - Explain Azure services, features, and configuration options"""
        else:
            instructions = """You are a Technical Assistant specializing in Azure and Microsoft 365 guidance.

    CAPABILITIES:
    - Provide detailed Azure and Microsoft 365 technical guidance
    - Explain implementation steps and best practices
    - Help with Azure AD, Conditional Access, MFA, and security configurations"""

        # <create_agent_with_tools>
        print(f"🛠️  Creating agent with model: {os.environ['MODEL_DEPLOYMENT_NAME']}")

        tools = []
        if sharepoint_tool:
            tools.append(sharepoint_tool)
            print("   ✓ SharePoint tool added")
        if mcp_tool:
            tools.append(mcp_tool)
            print("   ✓ MCP tool added")

        print(f"   Total tools: {len(tools)}")

        agent = project_client.agents.create_version(
            agent_name="Modern Workplace Assistant",
            definition=PromptAgentDefinition(
                model=os.environ["MODEL_DEPLOYMENT_NAME"],
                instructions=instructions,
                tools=tools if tools else None,
            ),
        )

        print(f"✅ Agent created successfully (name: {agent.name}, version: {agent.version})")
        return agent
        # </create_agent_with_tools>

    def demonstrate_business_scenarios(agent, openai_client):
        """
        Demonstrate realistic business scenarios with the Microsoft Foundry SDK.

        This function showcases the practical value of the Modern Workplace Assistant
        by walking through scenarios that enterprise employees face regularly.
        """

        scenarios = [
            {
                "title": "📋 Company Policy Question (SharePoint Only)",
                "question": "What is Contoso's remote work policy?",
                "context": "Employee needs to understand company-specific remote work requirements",
                "learning_point": "SharePoint tool retrieves internal company policies",
            },
            {
                "title": "📚 Technical Documentation Question (MCP Only)",
                "question": (
                    "According to Microsoft Learn, what is the correct way to implement "
                    "Azure AD Conditional Access policies? Please include reference links "
                    "to the official documentation."
                ),
                "context": "IT administrator needs authoritative Microsoft technical guidance",
                "learning_point": "MCP tool accesses Microsoft Learn for official documentation with links",
            },
            {
                "title": "🔄 Combined Implementation Question (SharePoint + MCP)",
                "question": (
                    "Based on our company's remote work security policy, how should I configure "
                    "my Azure environment to comply? Please include links to Microsoft "
                    "documentation showing how to implement each requirement."
                ),
                "context": "Need to map company policy to technical implementation with official guidance",
                "learning_point": "Both tools work together: SharePoint for policy + MCP for implementation docs",
            },
        ]

        print("\n" + "=" * 70)
        print("🏢 MODERN WORKPLACE ASSISTANT - BUSINESS SCENARIO DEMONSTRATION")
        print("=" * 70)
        print("This demonstration shows how AI agents solve real business problems")
        print("using the Microsoft Foundry SDK.")
        print("=" * 70)

        for i, scenario in enumerate(scenarios, 1):
            print(f"\n📊 SCENARIO {i}/3: {scenario['title']}")
            print("-" * 50)
            print(f"❓ QUESTION: {scenario['question']}")
            print(f"🎯 BUSINESS CONTEXT: {scenario['context']}")
            print(f"🎓 LEARNING POINT: {scenario['learning_point']}")
            print("-" * 50)

            # <agent_conversation>
            print("🤖 AGENT RESPONSE:")
            response, status = create_agent_response(agent, scenario["question"], openai_client)
            # </agent_conversation>

            if status == "completed" and response and len(response.strip()) > 10:
                print(f"✅ SUCCESS: {response[:300]}...")
                if len(response) > 300:
                    print(f"   📏 Full response: {len(response)} characters")
            else:
                print(f"⚠️  RESPONSE: {response}")

            print(f"📈 STATUS: {status}")
            print("-" * 50)

            time.sleep(1)

        print("\n✅ DEMONSTRATION COMPLETED!")
        print("🎓 Key Learning Outcomes:")
        print("   • Microsoft Foundry SDK usage for enterprise AI")
        print("   • Conversation management via the Responses API")
        print("   • Real business value through AI assistance")
        print("   • Foundation for governance and monitoring (Tutorials 2-3)")

        return True

    def create_agent_response(agent, message, openai_client):
        """
        Create a response from the workplace agent using the Responses API.

        This function demonstrates the response pattern for the Microsoft Foundry SDK
        including MCP tool approval handling.

        Args:
            agent: The agent object (with .name attribute)
            message: The user's message

        Returns:
            tuple: (response_text, status)
        """

        try:
            response = openai_client.responses.create(
                input=message,
                extra_body={
                    "agent": {"name": agent.name, "type": "agent_reference"}
                },
            )

            # Handle MCP approval requests if present
            approval_list = []
            for item in response.output:
                if item.type == "mcp_approval_request" and item.id:
                    approval_list.append(
                        McpApprovalResponse(
                            type="mcp_approval_response",
                            approve=True,
                            approval_request_id=item.id,
                        )
                    )

            if approval_list:
                response = openai_client.responses.create(
                    input=approval_list,
                    previous_response_id=response.id,
                    extra_body={
                        "agent": {"name": agent.name, "type": "agent_reference"}
                    },
                )

            return response.output_text, "completed"

        except Exception as e:
            return f"Error in conversation: {str(e)}", "failed"

    def interactive_mode(agent, openai_client):
        """Interactive mode for testing the workplace agent."""

        print("\n" + "=" * 60)
        print("💬 INTERACTIVE MODE - Test Your Workplace Agent!")
        print("=" * 60)
        print("Ask questions about Azure, M365, security, and technical implementation.")
        print("Type 'quit' to exit.")
        print("-" * 60)

        while True:
            try:
                question = input("\n❓ Your question: ").strip()

                if question.lower() in ["quit", "exit", "bye"]:
                    break

                if not question:
                    print("💡 Please ask a question about Azure or M365 technical implementation.")
                    continue

                print("\n🤖 Workplace Agent: ", end="", flush=True)
                response, status = create_agent_response(agent, question, openai_client)
                print(response)

                if status != "completed":
                    print(f"\n⚠️  Response status: {status}")

                print("-" * 60)

            except KeyboardInterrupt:
                break
            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("-" * 60)

        print("\n👋 Thank you for testing the Modern Workplace Agent!")

    def main():
        """Main execution flow demonstrating the complete sample."""

        print("🚀 Foundry - Modern Workplace Assistant")
        print("Tutorial 1: Building Enterprise Agents with Microsoft Foundry SDK")
        print("=" * 70)

        # <agent_authentication>
        with (
            DefaultAzureCredential() as credential,
            AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
            project_client.get_openai_client() as openai_client,
        ):
            print(f"✅ Connected to Foundry: {endpoint}")
        # </agent_authentication>

            try:
                agent = create_workplace_assistant(project_client)
                demonstrate_business_scenarios(agent, openai_client)

                print("\n🎯 Try interactive mode? (y/n): ", end="")
                try:
                    if input().lower().startswith("y"):
                        interactive_mode(agent, openai_client)
                except EOFError:
                    print("n")

                print("\n🎉 Sample completed successfully!")
                print("📚 This foundation supports Tutorial 2 (Governance) and Tutorial 3 (Production)")
                print("🔗 Next: Add evaluation metrics, monitoring, and production deployment")

            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("Please check your .env configuration and ensure:")
                print("  - PROJECT_ENDPOINT is correct")
                print("  - MODEL_DEPLOYMENT_NAME is deployed")
                print("  - Azure credentials are configured (az login)")

    if __name__ == "__main__":
        main()

Create the agent and connect the tools

Create the agent and connect the SharePoint and MCP tools.

Python

    #!/usr/bin/env python3
    """
    Microsoft Foundry Agent Sample - Tutorial 1: Modern Workplace Assistant

    This sample demonstrates a complete business scenario using the Microsoft Foundry SDK:
    - Agent creation with PromptAgentDefinition
    - Conversation management via the Responses API
    - Robust error handling and graceful degradation

    Educational Focus:
    - Enterprise AI patterns with the Microsoft Foundry SDK
    - Real-world business scenarios that enterprises face daily
    - Production-ready error handling and diagnostics
    - Foundation for governance, evaluation, and monitoring (Tutorials 2-3)

    Business Scenario:
    An employee needs to implement Azure AD multi-factor authentication. They need:
    1. Company security policy requirements
    2. Technical implementation steps
    3. Combined guidance showing how policy requirements map to technical implementation
    """

    # <imports_and_includes>
    import os
    import time
    from azure.ai.projects import AIProjectClient
    from azure.ai.projects.models import (
        PromptAgentDefinition,
        SharepointPreviewTool,
        SharepointGroundingToolParameters,
        ToolProjectConnection,
        MCPTool,
    )
    from azure.identity import DefaultAzureCredential
    from dotenv import load_dotenv
    from openai.types.responses.response_input_param import (
        McpApprovalResponse,
    )
    # </imports_and_includes>

    load_dotenv()

    # ============================================================================
    # AUTHENTICATION SETUP
    # ============================================================================
    endpoint = os.environ["PROJECT_ENDPOINT"]

    def create_workplace_assistant(project_client):
        """
        Create a Modern Workplace Assistant using the Microsoft Foundry SDK.

        This demonstrates enterprise AI patterns:
        1. Agent creation with PromptAgentDefinition
        2. Robust error handling with graceful degradation
        3. Dynamic agent capabilities based on available resources
        4. Clear diagnostic information for troubleshooting

        Returns:
            agent: The created agent object
        """

        print("🤖 Creating Modern Workplace Assistant...")

        # ========================================================================
        # SHAREPOINT INTEGRATION SETUP
        # ========================================================================
        # <sharepoint_tool_setup>
        sharepoint_connection_id = os.environ.get("SHAREPOINT_CONNECTION_ID")
        sharepoint_tool = None

        if sharepoint_connection_id:
            print("📁 Configuring SharePoint integration...")
            print(f"   Connection ID: {sharepoint_connection_id}")

            try:
                sharepoint_tool = SharepointPreviewTool(
                    sharepoint_grounding_preview=SharepointGroundingToolParameters(
                        project_connections=[
                            ToolProjectConnection(
                                project_connection_id=sharepoint_connection_id
                            )
                        ]
                    )
                )
                print("✅ SharePoint tool configured successfully")
            except Exception as e:
                print(f"⚠️  SharePoint tool unavailable: {e}")
                print("   Agent will operate without SharePoint access")
                sharepoint_tool = None
        else:
            print("📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_ID not set)")
        # </sharepoint_tool_setup>

        # ========================================================================
        # MICROSOFT LEARN MCP INTEGRATION SETUP
        # ========================================================================
        # <mcp_tool_setup>
        mcp_server_url = os.environ.get("MCP_SERVER_URL")
        mcp_tool = None

        if mcp_server_url:
            print("📚 Configuring Microsoft Learn MCP integration...")
            print(f"   Server URL: {mcp_server_url}")

            try:
                mcp_tool = MCPTool(
                    server_url=mcp_server_url,
                    server_label="Microsoft_Learn_Documentation",
                    require_approval="always",
                )
                print("✅ MCP tool configured successfully")
            except Exception as e:
                print(f"⚠️  MCP tool unavailable: {e}")
                print("   Agent will operate without Microsoft Learn access")
                mcp_tool = None
        else:
            print("📚 MCP integration skipped (MCP_SERVER_URL not set)")
        # </mcp_tool_setup>

        # ========================================================================
        # AGENT CREATION WITH DYNAMIC CAPABILITIES
        # ========================================================================
        if sharepoint_tool and mcp_tool:
            instructions = """You are a Modern Workplace Assistant for Contoso Corporation.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide comprehensive solutions combining internal requirements with external implementation

    RESPONSE STRATEGY:
    - For policy questions: Search SharePoint for company-specific requirements and guidelines
    - For technical questions: Use Microsoft Learn for current Azure/M365 documentation
    - For implementation questions: Combine both sources to show how company policies map to technical implementation
    - Always cite your sources and provide step-by-step guidance"""
        elif sharepoint_tool:
            instructions = """You are a Modern Workplace Assistant with access to Contoso Corporation's SharePoint.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Provide detailed technical guidance based on your knowledge
    - Combine company policies with general best practices"""
        elif mcp_tool:
            instructions = """You are a Technical Assistant with access to Microsoft Learn documentation.

    CAPABILITIES:
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide detailed implementation steps and best practices
    - Explain Azure services, features, and configuration options"""
        else:
            instructions = """You are a Technical Assistant specializing in Azure and Microsoft 365 guidance.

    CAPABILITIES:
    - Provide detailed Azure and Microsoft 365 technical guidance
    - Explain implementation steps and best practices
    - Help with Azure AD, Conditional Access, MFA, and security configurations"""

        # <create_agent_with_tools>
        print(f"🛠️  Creating agent with model: {os.environ['MODEL_DEPLOYMENT_NAME']}")

        tools = []
        if sharepoint_tool:
            tools.append(sharepoint_tool)
            print("   ✓ SharePoint tool added")
        if mcp_tool:
            tools.append(mcp_tool)
            print("   ✓ MCP tool added")

        print(f"   Total tools: {len(tools)}")

        agent = project_client.agents.create_version(
            agent_name="Modern Workplace Assistant",
            definition=PromptAgentDefinition(
                model=os.environ["MODEL_DEPLOYMENT_NAME"],
                instructions=instructions,
                tools=tools if tools else None,
            ),
        )

        print(f"✅ Agent created successfully (name: {agent.name}, version: {agent.version})")
        return agent
        # </create_agent_with_tools>

    def demonstrate_business_scenarios(agent, openai_client):
        """
        Demonstrate realistic business scenarios with the Microsoft Foundry SDK.

        This function showcases the practical value of the Modern Workplace Assistant
        by walking through scenarios that enterprise employees face regularly.
        """

        scenarios = [
            {
                "title": "📋 Company Policy Question (SharePoint Only)",
                "question": "What is Contoso's remote work policy?",
                "context": "Employee needs to understand company-specific remote work requirements",
                "learning_point": "SharePoint tool retrieves internal company policies",
            },
            {
                "title": "📚 Technical Documentation Question (MCP Only)",
                "question": (
                    "According to Microsoft Learn, what is the correct way to implement "
                    "Azure AD Conditional Access policies? Please include reference links "
                    "to the official documentation."
                ),
                "context": "IT administrator needs authoritative Microsoft technical guidance",
                "learning_point": "MCP tool accesses Microsoft Learn for official documentation with links",
            },
            {
                "title": "🔄 Combined Implementation Question (SharePoint + MCP)",
                "question": (
                    "Based on our company's remote work security policy, how should I configure "
                    "my Azure environment to comply? Please include links to Microsoft "
                    "documentation showing how to implement each requirement."
                ),
                "context": "Need to map company policy to technical implementation with official guidance",
                "learning_point": "Both tools work together: SharePoint for policy + MCP for implementation docs",
            },
        ]

        print("\n" + "=" * 70)
        print("🏢 MODERN WORKPLACE ASSISTANT - BUSINESS SCENARIO DEMONSTRATION")
        print("=" * 70)
        print("This demonstration shows how AI agents solve real business problems")
        print("using the Microsoft Foundry SDK.")
        print("=" * 70)

        for i, scenario in enumerate(scenarios, 1):
            print(f"\n📊 SCENARIO {i}/3: {scenario['title']}")
            print("-" * 50)
            print(f"❓ QUESTION: {scenario['question']}")
            print(f"🎯 BUSINESS CONTEXT: {scenario['context']}")
            print(f"🎓 LEARNING POINT: {scenario['learning_point']}")
            print("-" * 50)

            # <agent_conversation>
            print("🤖 AGENT RESPONSE:")
            response, status = create_agent_response(agent, scenario["question"], openai_client)
            # </agent_conversation>

            if status == "completed" and response and len(response.strip()) > 10:
                print(f"✅ SUCCESS: {response[:300]}...")
                if len(response) > 300:
                    print(f"   📏 Full response: {len(response)} characters")
            else:
                print(f"⚠️  RESPONSE: {response}")

            print(f"📈 STATUS: {status}")
            print("-" * 50)

            time.sleep(1)

        print("\n✅ DEMONSTRATION COMPLETED!")
        print("🎓 Key Learning Outcomes:")
        print("   • Microsoft Foundry SDK usage for enterprise AI")
        print("   • Conversation management via the Responses API")
        print("   • Real business value through AI assistance")
        print("   • Foundation for governance and monitoring (Tutorials 2-3)")

        return True

    def create_agent_response(agent, message, openai_client):
        """
        Create a response from the workplace agent using the Responses API.

        This function demonstrates the response pattern for the Microsoft Foundry SDK
        including MCP tool approval handling.

        Args:
            agent: The agent object (with .name attribute)
            message: The user's message

        Returns:
            tuple: (response_text, status)
        """

        try:
            response = openai_client.responses.create(
                input=message,
                extra_body={
                    "agent": {"name": agent.name, "type": "agent_reference"}
                },
            )

            # Handle MCP approval requests if present
            approval_list = []
            for item in response.output:
                if item.type == "mcp_approval_request" and item.id:
                    approval_list.append(
                        McpApprovalResponse(
                            type="mcp_approval_response",
                            approve=True,
                            approval_request_id=item.id,
                        )
                    )

            if approval_list:
                response = openai_client.responses.create(
                    input=approval_list,
                    previous_response_id=response.id,
                    extra_body={
                        "agent": {"name": agent.name, "type": "agent_reference"}
                    },
                )

            return response.output_text, "completed"

        except Exception as e:
            return f"Error in conversation: {str(e)}", "failed"

    def interactive_mode(agent, openai_client):
        """Interactive mode for testing the workplace agent."""

        print("\n" + "=" * 60)
        print("💬 INTERACTIVE MODE - Test Your Workplace Agent!")
        print("=" * 60)
        print("Ask questions about Azure, M365, security, and technical implementation.")
        print("Type 'quit' to exit.")
        print("-" * 60)

        while True:
            try:
                question = input("\n❓ Your question: ").strip()

                if question.lower() in ["quit", "exit", "bye"]:
                    break

                if not question:
                    print("💡 Please ask a question about Azure or M365 technical implementation.")
                    continue

                print("\n🤖 Workplace Agent: ", end="", flush=True)
                response, status = create_agent_response(agent, question, openai_client)
                print(response)

                if status != "completed":
                    print(f"\n⚠️  Response status: {status}")

                print("-" * 60)

            except KeyboardInterrupt:
                break
            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("-" * 60)

        print("\n👋 Thank you for testing the Modern Workplace Agent!")

    def main():
        """Main execution flow demonstrating the complete sample."""

        print("🚀 Foundry - Modern Workplace Assistant")
        print("Tutorial 1: Building Enterprise Agents with Microsoft Foundry SDK")
        print("=" * 70)

        # <agent_authentication>
        with (
            DefaultAzureCredential() as credential,
            AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
            project_client.get_openai_client() as openai_client,
        ):
            print(f"✅ Connected to Foundry: {endpoint}")
        # </agent_authentication>

            try:
                agent = create_workplace_assistant(project_client)
                demonstrate_business_scenarios(agent, openai_client)

                print("\n🎯 Try interactive mode? (y/n): ", end="")
                try:
                    if input().lower().startswith("y"):
                        interactive_mode(agent, openai_client)
                except EOFError:
                    print("n")

                print("\n🎉 Sample completed successfully!")
                print("📚 This foundation supports Tutorial 2 (Governance) and Tutorial 3 (Production)")
                print("🔗 Next: Add evaluation metrics, monitoring, and production deployment")

            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("Please check your .env configuration and ensure:")
                print("  - PROJECT_ENDPOINT is correct")
                print("  - MODEL_DEPLOYMENT_NAME is deployed")
                print("  - Azure credentials are configured (az login)")

    if __name__ == "__main__":
        main()

Converse with the agent

Finally, implement an interactive loop to converse with the agent.

Python

    #!/usr/bin/env python3
    """
    Microsoft Foundry Agent Sample - Tutorial 1: Modern Workplace Assistant

    This sample demonstrates a complete business scenario using the Microsoft Foundry SDK:
    - Agent creation with PromptAgentDefinition
    - Conversation management via the Responses API
    - Robust error handling and graceful degradation

    Educational Focus:
    - Enterprise AI patterns with the Microsoft Foundry SDK
    - Real-world business scenarios that enterprises face daily
    - Production-ready error handling and diagnostics
    - Foundation for governance, evaluation, and monitoring (Tutorials 2-3)

    Business Scenario:
    An employee needs to implement Azure AD multi-factor authentication. They need:
    1. Company security policy requirements
    2. Technical implementation steps
    3. Combined guidance showing how policy requirements map to technical implementation
    """

    # <imports_and_includes>
    import os
    import time
    from azure.ai.projects import AIProjectClient
    from azure.ai.projects.models import (
        PromptAgentDefinition,
        SharepointPreviewTool,
        SharepointGroundingToolParameters,
        ToolProjectConnection,
        MCPTool,
    )
    from azure.identity import DefaultAzureCredential
    from dotenv import load_dotenv
    from openai.types.responses.response_input_param import (
        McpApprovalResponse,
    )
    # </imports_and_includes>

    load_dotenv()

    # ============================================================================
    # AUTHENTICATION SETUP
    # ============================================================================
    endpoint = os.environ["PROJECT_ENDPOINT"]

    def create_workplace_assistant(project_client):
        """
        Create a Modern Workplace Assistant using the Microsoft Foundry SDK.

        This demonstrates enterprise AI patterns:
        1. Agent creation with PromptAgentDefinition
        2. Robust error handling with graceful degradation
        3. Dynamic agent capabilities based on available resources
        4. Clear diagnostic information for troubleshooting

        Returns:
            agent: The created agent object
        """

        print("🤖 Creating Modern Workplace Assistant...")

        # ========================================================================
        # SHAREPOINT INTEGRATION SETUP
        # ========================================================================
        # <sharepoint_tool_setup>
        sharepoint_connection_id = os.environ.get("SHAREPOINT_CONNECTION_ID")
        sharepoint_tool = None

        if sharepoint_connection_id:
            print("📁 Configuring SharePoint integration...")
            print(f"   Connection ID: {sharepoint_connection_id}")

            try:
                sharepoint_tool = SharepointPreviewTool(
                    sharepoint_grounding_preview=SharepointGroundingToolParameters(
                        project_connections=[
                            ToolProjectConnection(
                                project_connection_id=sharepoint_connection_id
                            )
                        ]
                    )
                )
                print("✅ SharePoint tool configured successfully")
            except Exception as e:
                print(f"⚠️  SharePoint tool unavailable: {e}")
                print("   Agent will operate without SharePoint access")
                sharepoint_tool = None
        else:
            print("📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_ID not set)")
        # </sharepoint_tool_setup>

        # ========================================================================
        # MICROSOFT LEARN MCP INTEGRATION SETUP
        # ========================================================================
        # <mcp_tool_setup>
        mcp_server_url = os.environ.get("MCP_SERVER_URL")
        mcp_tool = None

        if mcp_server_url:
            print("📚 Configuring Microsoft Learn MCP integration...")
            print(f"   Server URL: {mcp_server_url}")

            try:
                mcp_tool = MCPTool(
                    server_url=mcp_server_url,
                    server_label="Microsoft_Learn_Documentation",
                    require_approval="always",
                )
                print("✅ MCP tool configured successfully")
            except Exception as e:
                print(f"⚠️  MCP tool unavailable: {e}")
                print("   Agent will operate without Microsoft Learn access")
                mcp_tool = None
        else:
            print("📚 MCP integration skipped (MCP_SERVER_URL not set)")
        # </mcp_tool_setup>

        # ========================================================================
        # AGENT CREATION WITH DYNAMIC CAPABILITIES
        # ========================================================================
        if sharepoint_tool and mcp_tool:
            instructions = """You are a Modern Workplace Assistant for Contoso Corporation.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide comprehensive solutions combining internal requirements with external implementation

    RESPONSE STRATEGY:
    - For policy questions: Search SharePoint for company-specific requirements and guidelines
    - For technical questions: Use Microsoft Learn for current Azure/M365 documentation
    - For implementation questions: Combine both sources to show how company policies map to technical implementation
    - Always cite your sources and provide step-by-step guidance"""
        elif sharepoint_tool:
            instructions = """You are a Modern Workplace Assistant with access to Contoso Corporation's SharePoint.

    CAPABILITIES:
    - Search SharePoint for company policies, procedures, and internal documentation
    - Provide detailed technical guidance based on your knowledge
    - Combine company policies with general best practices"""
        elif mcp_tool:
            instructions = """You are a Technical Assistant with access to Microsoft Learn documentation.

    CAPABILITIES:
    - Access Microsoft Learn for current Azure and Microsoft 365 technical guidance
    - Provide detailed implementation steps and best practices
    - Explain Azure services, features, and configuration options"""
        else:
            instructions = """You are a Technical Assistant specializing in Azure and Microsoft 365 guidance.

    CAPABILITIES:
    - Provide detailed Azure and Microsoft 365 technical guidance
    - Explain implementation steps and best practices
    - Help with Azure AD, Conditional Access, MFA, and security configurations"""

        # <create_agent_with_tools>
        print(f"🛠️  Creating agent with model: {os.environ['MODEL_DEPLOYMENT_NAME']}")

        tools = []
        if sharepoint_tool:
            tools.append(sharepoint_tool)
            print("   ✓ SharePoint tool added")
        if mcp_tool:
            tools.append(mcp_tool)
            print("   ✓ MCP tool added")

        print(f"   Total tools: {len(tools)}")

        agent = project_client.agents.create_version(
            agent_name="Modern Workplace Assistant",
            definition=PromptAgentDefinition(
                model=os.environ["MODEL_DEPLOYMENT_NAME"],
                instructions=instructions,
                tools=tools if tools else None,
            ),
        )

        print(f"✅ Agent created successfully (name: {agent.name}, version: {agent.version})")
        return agent
        # </create_agent_with_tools>

    def demonstrate_business_scenarios(agent, openai_client):
        """
        Demonstrate realistic business scenarios with the Microsoft Foundry SDK.

        This function showcases the practical value of the Modern Workplace Assistant
        by walking through scenarios that enterprise employees face regularly.
        """

        scenarios = [
            {
                "title": "📋 Company Policy Question (SharePoint Only)",
                "question": "What is Contoso's remote work policy?",
                "context": "Employee needs to understand company-specific remote work requirements",
                "learning_point": "SharePoint tool retrieves internal company policies",
            },
            {
                "title": "📚 Technical Documentation Question (MCP Only)",
                "question": (
                    "According to Microsoft Learn, what is the correct way to implement "
                    "Azure AD Conditional Access policies? Please include reference links "
                    "to the official documentation."
                ),
                "context": "IT administrator needs authoritative Microsoft technical guidance",
                "learning_point": "MCP tool accesses Microsoft Learn for official documentation with links",
            },
            {
                "title": "🔄 Combined Implementation Question (SharePoint + MCP)",
                "question": (
                    "Based on our company's remote work security policy, how should I configure "
                    "my Azure environment to comply? Please include links to Microsoft "
                    "documentation showing how to implement each requirement."
                ),
                "context": "Need to map company policy to technical implementation with official guidance",
                "learning_point": "Both tools work together: SharePoint for policy + MCP for implementation docs",
            },
        ]

        print("\n" + "=" * 70)
        print("🏢 MODERN WORKPLACE ASSISTANT - BUSINESS SCENARIO DEMONSTRATION")
        print("=" * 70)
        print("This demonstration shows how AI agents solve real business problems")
        print("using the Microsoft Foundry SDK.")
        print("=" * 70)

        for i, scenario in enumerate(scenarios, 1):
            print(f"\n📊 SCENARIO {i}/3: {scenario['title']}")
            print("-" * 50)
            print(f"❓ QUESTION: {scenario['question']}")
            print(f"🎯 BUSINESS CONTEXT: {scenario['context']}")
            print(f"🎓 LEARNING POINT: {scenario['learning_point']}")
            print("-" * 50)

            # <agent_conversation>
            print("🤖 AGENT RESPONSE:")
            response, status = create_agent_response(agent, scenario["question"], openai_client)
            # </agent_conversation>

            if status == "completed" and response and len(response.strip()) > 10:
                print(f"✅ SUCCESS: {response[:300]}...")
                if len(response) > 300:
                    print(f"   📏 Full response: {len(response)} characters")
            else:
                print(f"⚠️  RESPONSE: {response}")

            print(f"📈 STATUS: {status}")
            print("-" * 50)

            time.sleep(1)

        print("\n✅ DEMONSTRATION COMPLETED!")
        print("🎓 Key Learning Outcomes:")
        print("   • Microsoft Foundry SDK usage for enterprise AI")
        print("   • Conversation management via the Responses API")
        print("   • Real business value through AI assistance")
        print("   • Foundation for governance and monitoring (Tutorials 2-3)")

        return True

    def create_agent_response(agent, message, openai_client):
        """
        Create a response from the workplace agent using the Responses API.

        This function demonstrates the response pattern for the Microsoft Foundry SDK
        including MCP tool approval handling.

        Args:
            agent: The agent object (with .name attribute)
            message: The user's message

        Returns:
            tuple: (response_text, status)
        """

        try:
            response = openai_client.responses.create(
                input=message,
                extra_body={
                    "agent": {"name": agent.name, "type": "agent_reference"}
                },
            )

            # Handle MCP approval requests if present
            approval_list = []
            for item in response.output:
                if item.type == "mcp_approval_request" and item.id:
                    approval_list.append(
                        McpApprovalResponse(
                            type="mcp_approval_response",
                            approve=True,
                            approval_request_id=item.id,
                        )
                    )

            if approval_list:
                response = openai_client.responses.create(
                    input=approval_list,
                    previous_response_id=response.id,
                    extra_body={
                        "agent": {"name": agent.name, "type": "agent_reference"}
                    },
                )

            return response.output_text, "completed"

        except Exception as e:
            return f"Error in conversation: {str(e)}", "failed"

    def interactive_mode(agent, openai_client):
        """Interactive mode for testing the workplace agent."""

        print("\n" + "=" * 60)
        print("💬 INTERACTIVE MODE - Test Your Workplace Agent!")
        print("=" * 60)
        print("Ask questions about Azure, M365, security, and technical implementation.")
        print("Type 'quit' to exit.")
        print("-" * 60)

        while True:
            try:
                question = input("\n❓ Your question: ").strip()

                if question.lower() in ["quit", "exit", "bye"]:
                    break

                if not question:
                    print("💡 Please ask a question about Azure or M365 technical implementation.")
                    continue

                print("\n🤖 Workplace Agent: ", end="", flush=True)
                response, status = create_agent_response(agent, question, openai_client)
                print(response)

                if status != "completed":
                    print(f"\n⚠️  Response status: {status}")

                print("-" * 60)

            except KeyboardInterrupt:
                break
            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("-" * 60)

        print("\n👋 Thank you for testing the Modern Workplace Agent!")

    def main():
        """Main execution flow demonstrating the complete sample."""

        print("🚀 Foundry - Modern Workplace Assistant")
        print("Tutorial 1: Building Enterprise Agents with Microsoft Foundry SDK")
        print("=" * 70)

        # <agent_authentication>
        with (
            DefaultAzureCredential() as credential,
            AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
            project_client.get_openai_client() as openai_client,
        ):
            print(f"✅ Connected to Foundry: {endpoint}")
        # </agent_authentication>

            try:
                agent = create_workplace_assistant(project_client)
                demonstrate_business_scenarios(agent, openai_client)

                print("\n🎯 Try interactive mode? (y/n): ", end="")
                try:
                    if input().lower().startswith("y"):
                        interactive_mode(agent, openai_client)
                except EOFError:
                    print("n")

                print("\n🎉 Sample completed successfully!")
                print("📚 This foundation supports Tutorial 2 (Governance) and Tutorial 3 (Production)")
                print("🔗 Next: Add evaluation metrics, monitoring, and production deployment")

            except Exception as e:
                print(f"\n❌ Error: {e}")
                print("Please check your .env configuration and ensure:")
                print("  - PROJECT_ENDPOINT is correct")
                print("  - MODEL_DEPLOYMENT_NAME is deployed")
                print("  - Azure credentials are configured (az login)")

    if __name__ == "__main__":
        main()

Expected output from agent sample code

When you run the agent, you see output similar to the following example. The output shows successful tool configuration and agent responses to business scenarios:

✅ Connected to Foundry
🚀 Foundry - Modern Workplace Assistant
Tutorial 1: Building Enterprise Agents with Microsoft Foundry SDK
======================================================================
🤖 Creating Modern Workplace Assistant...
📁 Configuring SharePoint integration...
   Connection ID: /subscriptions/.../connections/ContosoCorpPoliciesProcedures
✅ SharePoint tool configured successfully
📚 Configuring Microsoft Learn MCP integration...
   Server URL: https://learn.microsoft.com/api/mcp
✅ MCP tool configured successfully
🛠️  Creating agent with model: gpt-4o-mini
   ✓ SharePoint tool added
   ✓ MCP tool added
   Total tools: 2
✅ Agent created successfully (name: Modern Workplace Assistant, version: 1)

======================================================================
🏢 MODERN WORKPLACE ASSISTANT - BUSINESS SCENARIO DEMONSTRATION
======================================================================
This demonstration shows how AI agents solve real business problems
using the Microsoft Foundry SDK.
======================================================================

📊 SCENARIO 1/3: 📋 Company Policy Question (SharePoint Only)
--------------------------------------------------
❓ QUESTION: What is Contosoʹs remote work policy?
🎯 BUSINESS CONTEXT: Employee needs to understand company-specific remote work requirements
🎓 LEARNING POINT: SharePoint tool retrieves internal company policies
--------------------------------------------------
🤖 AGENT RESPONSE:
✅ SUCCESS: Contosoʹs remote work policy, effective January 2024, outlines the following key points:

### Overview
Contoso Corp supports flexible work arrangements, including remote work, to enhance employee productivity and work-life balance.

### Eligibility
- **Full-time Employees**: Must have completed a 90...
   📏 Full response: 1530 characters
📈 STATUS: completed
--------------------------------------------------

📊 SCENARIO 2/3: 📚 Technical Documentation Question (MCP Only)
--------------------------------------------------
❓ QUESTION: According to Microsoft Learn, what is the correct way to implement Azure AD Conditional Access policies? Please include reference links to the official documentation.
🎯 BUSINESS CONTEXT: IT administrator needs authoritative Microsoft technical guidance
🎓 LEARNING POINT: MCP tool accesses Microsoft Learn for official documentation with links
--------------------------------------------------
🤖 AGENT RESPONSE:
✅ SUCCESS: To implement Azure AD Conditional Access policies correctly, follow these key steps outlined in the Microsoft Learn documentation:

### 1. Understanding Conditional Access
Conditional Access policies act as "if-then" statements that enforce organizational access controls based on various signals. Th...
   📏 Full response: 2459 characters
📈 STATUS: completed
--------------------------------------------------

📊 SCENARIO 3/3: 🔄 Combined Implementation Question (SharePoint + MCP)
--------------------------------------------------
❓ QUESTION: Based on our companyʹs remote work security policy, how should I configure my Azure environment to comply? Please include links to Microsoft documentation showing how to implement each requirement.
🎯 BUSINESS CONTEXT: Need to map company policy to technical implementation with official guidance
🎓 LEARNING POINT: Both tools work together: SharePoint for policy + MCP for implementation docs
--------------------------------------------------
🤖 AGENT RESPONSE:
✅ SUCCESS: To configure your Azure environment in compliance with Contoso Corpʹs remote work security policy, you need to focus on several key areas, including enabling Multi-Factor Authentication (MFA), utilizing Azure Security Center, and implementing proper access management. Below are specific steps and li...
   📏 Full response: 3436 characters
📈 STATUS: completed
--------------------------------------------------

✅ DEMONSTRATION COMPLETED!
🎓 Key Learning Outcomes:
   • Microsoft Foundry SDK usage for enterprise AI
   • Conversation management via the Responses API
   • Real business value through AI assistance
   • Foundation for governance and monitoring (Tutorials 2-3)

🎯 Try interactive mode? (y/n): n

🎉 Sample completed successfully!
📚 This foundation supports Tutorial 2 (Governance) and Tutorial 3 (Production)
🔗 Next: Add evaluation metrics, monitoring, and production deployment

Step 5: Evaluate the assistant by using cloud evaluation

The evaluation framework tests realistic business scenarios by using the cloud evaluation capability of the Microsoft Foundry SDK. Instead of a custom local approach, this pattern uses the built-in evaluators (builtin.violence, builtin.fluency, builtin.task_adherence) and the openai_client.evals API to run scalable, repeatable evaluations in the cloud.

This evaluation framework demonstrates:

• Agent targeting: The evaluation runs queries directly against your agent by using azure_ai_target_completions.
• Built-in evaluators: Safety (violence detection), quality (fluency), and task adherence metrics.
• Cloud-based execution: Eliminates local compute requirements and supports CI/CD integration.
• Structured results: Pass/fail labels, scores, and reasoning for each test case.

The code breaks down into the following main sections:

1. Configure the evaluation.
2. Run the cloud evaluation.
3. Retrieve evaluation results.

For detailed guidance on cloud evaluations, see Run evaluations in the cloud. To find a comprehensive list of built-in evaluators available in Foundry, see Observability in generative AI.

The C# SDK uses protocol methods with BinaryData and BinaryContent instead of typed objects. This approach requires helper methods to parse JSON responses. See the C# Evaluations SDK sample for the complete pattern.

Configure the evaluation

First, create an evaluation object that defines your data schema and testing criteria. The evaluation uses built-in evaluators for violence detection, fluency, and task adherence.

In Python, use the OpenAI client directly. In C#, get an EvaluationClient from the project client:

Python

    # ------------------------------------
    # Copyright (c) Microsoft Corporation.
    # Licensed under the MIT License.
    # ------------------------------------
    """
    DESCRIPTION:
        This sample demonstrates how to evaluate the Modern Workplace Assistant
        using the cloud evaluation API with built-in evaluators.

    USAGE:
        python evaluate.py

        Before running:
        pip install azure-ai-projects==2.0.0b3 python-dotenv openai

        Set these environment variables:
        1) PROJECT_ENDPOINT - Your Foundry project endpoint
        2) MODEL_DEPLOYMENT_NAME - Model deployment name (e.g., gpt-4o-mini)
    """

    # <imports_and_includes>
    import os
    import time
    from typing import Union
    from pprint import pprint
    from dotenv import load_dotenv
    from azure.identity import DefaultAzureCredential
    from azure.ai.projects import AIProjectClient
    from azure.ai.projects.models import PromptAgentDefinition
    from openai.types.eval_create_params import DataSourceConfigCustom
    from openai.types.evals.run_create_response import RunCreateResponse
    from openai.types.evals.run_retrieve_response import RunRetrieveResponse
    # </imports_and_includes>

    # <configure_evaluation>
    load_dotenv()
    endpoint = os.environ["PROJECT_ENDPOINT"]
    model_deployment_name = os.environ.get("MODEL_DEPLOYMENT_NAME", "gpt-4o-mini")

    with (
        DefaultAzureCredential() as credential,
        AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
        project_client.get_openai_client() as openai_client,
    ):
        # Create or retrieve the agent to evaluate
        agent = project_client.agents.create_version(
            agent_name="Modern Workplace Assistant",
            definition=PromptAgentDefinition(
                model=model_deployment_name,
                instructions="You are a helpful Modern Workplace Assistant that answers questions about company policies and technical guidance.",
            ),
        )
        print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

        # Define the data schema for evaluation
        data_source_config = DataSourceConfigCustom(
            type="custom",
            item_schema={
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"]
            },
            include_sample_schema=True,
        )

        # Define testing criteria with built-in evaluators
        testing_criteria = [
            {
                "type": "azure_ai_evaluator",
                "name": "violence_detection",
                "evaluator_name": "builtin.violence",
                "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_text}}"},
            },
            {
                "type": "azure_ai_evaluator",
                "name": "fluency",
                "evaluator_name": "builtin.fluency",
                "initialization_parameters": {"deployment_name": f"{model_deployment_name}"},
                "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_text}}"},
            },
            {
                "type": "azure_ai_evaluator",
                "name": "task_adherence",
                "evaluator_name": "builtin.task_adherence",
                "initialization_parameters": {"deployment_name": f"{model_deployment_name}"},
                "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_items}}"},
            },
        ]

        # Create the evaluation object
        eval_object = openai_client.evals.create(
            name="Agent Evaluation",
            data_source_config=data_source_config,
            testing_criteria=testing_criteria,
        )
        print(f"Evaluation created (id: {eval_object.id}, name: {eval_object.name})")
    # </configure_evaluation>

    # <run_cloud_evaluation>
        # Define the data source for the evaluation run
        data_source = {
            "type": "azure_ai_target_completions",
            "source": {
                "type": "file_content",
                "content": [
                    {"item": {"query": "What is Contoso's remote work policy?"}},
                    {"item": {"query": "What are the security requirements for remote employees?"}},
                    {"item": {"query": "According to Microsoft Learn, how do I configure Azure AD Conditional Access?"}},
                    {"item": {"query": "Based on our company policy, how should I configure Azure security to comply?"}},
                ],
            },
            "input_messages": {
                "type": "template",
                "template": [
                    {"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}
                ],
            },
            "target": {
                "type": "azure_ai_agent",
                "name": agent.name,
                "version": agent.version,
            },
        }

        # Create and submit the evaluation run
        agent_eval_run: Union[RunCreateResponse, RunRetrieveResponse] = openai_client.evals.runs.create(
            eval_id=eval_object.id,
            name=f"Evaluation Run for Agent {agent.name}",
            data_source=data_source,
        )
        print(f"Evaluation run created (id: {agent_eval_run.id})")
    # </run_cloud_evaluation>

    # <retrieve_evaluation_results>
        # Poll until the evaluation run completes
        while agent_eval_run.status not in ["completed", "failed"]:
            agent_eval_run = openai_client.evals.runs.retrieve(
                run_id=agent_eval_run.id,
                eval_id=eval_object.id
            )
            print(f"Waiting for eval run to complete... current status: {agent_eval_run.status}")
            time.sleep(5)

        if agent_eval_run.status == "completed":
            print("\n✓ Evaluation run completed successfully!")
            print(f"Result Counts: {agent_eval_run.result_counts}")

            # Retrieve detailed output items
            output_items = list(
                openai_client.evals.runs.output_items.list(
                    run_id=agent_eval_run.id,
                    eval_id=eval_object.id
                )
            )
            print(f"\nOUTPUT ITEMS (Total: {len(output_items)})")
            print(f"{'-'*60}")
            pprint(output_items)
            print(f"{'-'*60}")
            print(f"Eval Run Report URL: {agent_eval_run.report_url}")
        else:
            print("\n✗ Evaluation run failed.")

        # Cleanup
        openai_client.evals.delete(eval_id=eval_object.id)
        print("Evaluation deleted")

        project_client.agents.delete(agent_name=agent.name)
        print("Agent deleted")
    # </retrieve_evaluation_results>

The testing_criteria array specifies which evaluators to run:

• builtin.violence: Detects violent or harmful content in responses.
• builtin.fluency: Assesses response quality and readability (requires a model deployment).
• builtin.task_adherence: Evaluates whether the agent followed instructions correctly.

Run the cloud evaluation

Create an evaluation run that targets your agent. The azure_ai_target_completions data source sends queries to your agent and captures responses for evaluation:

Python

    # ------------------------------------
    # Copyright (c) Microsoft Corporation.
    # Licensed under the MIT License.
    # ------------------------------------
    """
    DESCRIPTION:
        This sample demonstrates how to evaluate the Modern Workplace Assistant
        using the cloud evaluation API with built-in evaluators.

    USAGE:
        python evaluate.py

        Before running:
        pip install azure-ai-projects==2.0.0b3 python-dotenv openai

        Set these environment variables:
        1) PROJECT_ENDPOINT - Your Foundry project endpoint
        2) MODEL_DEPLOYMENT_NAME - Model deployment name (e.g., gpt-4o-mini)
    """

    # <imports_and_includes>
    import os
    import time
    from typing import Union
    from pprint import pprint
    from dotenv import load_dotenv
    from azure.identity import DefaultAzureCredential
    from azure.ai.projects import AIProjectClient
    from azure.ai.projects.models import PromptAgentDefinition
    from openai.types.eval_create_params import DataSourceConfigCustom
    from openai.types.evals.run_create_response import RunCreateResponse
    from openai.types.evals.run_retrieve_response import RunRetrieveResponse
    # </imports_and_includes>

    # <configure_evaluation>
    load_dotenv()
    endpoint = os.environ["PROJECT_ENDPOINT"]
    model_deployment_name = os.environ.get("MODEL_DEPLOYMENT_NAME", "gpt-4o-mini")

    with (
        DefaultAzureCredential() as credential,
        AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
        project_client.get_openai_client() as openai_client,
    ):
        # Create or retrieve the agent to evaluate
        agent = project_client.agents.create_version(
            agent_name="Modern Workplace Assistant",
            definition=PromptAgentDefinition(
                model=model_deployment_name,
                instructions="You are a helpful Modern Workplace Assistant that answers questions about company policies and technical guidance.",
            ),
        )
        print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

        # Define the data schema for evaluation
        data_source_config = DataSourceConfigCustom(
            type="custom",
            item_schema={
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"]
            },
            include_sample_schema=True,
        )

        # Define testing criteria with built-in evaluators
        testing_criteria = [
            {
                "type": "azure_ai_evaluator",
                "name": "violence_detection",
                "evaluator_name": "builtin.violence",
                "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_text}}"},
            },
            {
                "type": "azure_ai_evaluator",
                "name": "fluency",
                "evaluator_name": "builtin.fluency",
                "initialization_parameters": {"deployment_name": f"{model_deployment_name}"},
                "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_text}}"},
            },
            {
                "type": "azure_ai_evaluator",
                "name": "task_adherence",
                "evaluator_name": "builtin.task_adherence",
                "initialization_parameters": {"deployment_name": f"{model_deployment_name}"},
                "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_items}}"},
            },
        ]

        # Create the evaluation object
        eval_object = openai_client.evals.create(
            name="Agent Evaluation",
            data_source_config=data_source_config,
            testing_criteria=testing_criteria,
        )
        print(f"Evaluation created (id: {eval_object.id}, name: {eval_object.name})")
    # </configure_evaluation>

    # <run_cloud_evaluation>
        # Define the data source for the evaluation run
        data_source = {
            "type": "azure_ai_target_completions",
            "source": {
                "type": "file_content",
                "content": [
                    {"item": {"query": "What is Contoso's remote work policy?"}},
                    {"item": {"query": "What are the security requirements for remote employees?"}},
                    {"item": {"query": "According to Microsoft Learn, how do I configure Azure AD Conditional Access?"}},
                    {"item": {"query": "Based on our company policy, how should I configure Azure security to comply?"}},
                ],
            },
            "input_messages": {
                "type": "template",
                "template": [
                    {"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}
                ],
            },
            "target": {
                "type": "azure_ai_agent",
                "name": agent.name,
                "version": agent.version,
            },
        }

        # Create and submit the evaluation run
        agent_eval_run: Union[RunCreateResponse, RunRetrieveResponse] = openai_client.evals.runs.create(
            eval_id=eval_object.id,
            name=f"Evaluation Run for Agent {agent.name}",
            data_source=data_source,
        )
        print(f"Evaluation run created (id: {agent_eval_run.id})")
    # </run_cloud_evaluation>

    # <retrieve_evaluation_results>
        # Poll until the evaluation run completes
        while agent_eval_run.status not in ["completed", "failed"]:
            agent_eval_run = openai_client.evals.runs.retrieve(
                run_id=agent_eval_run.id,
                eval_id=eval_object.id
            )
            print(f"Waiting for eval run to complete... current status: {agent_eval_run.status}")
            time.sleep(5)

        if agent_eval_run.status == "completed":
            print("\n✓ Evaluation run completed successfully!")
            print(f"Result Counts: {agent_eval_run.result_counts}")

            # Retrieve detailed output items
            output_items = list(
                openai_client.evals.runs.output_items.list(
                    run_id=agent_eval_run.id,
                    eval_id=eval_object.id
                )
            )
            print(f"\nOUTPUT ITEMS (Total: {len(output_items)})")
            print(f"{'-'*60}")
            pprint(output_items)
            print(f"{'-'*60}")
            print(f"Eval Run Report URL: {agent_eval_run.report_url}")
        else:
            print("\n✗ Evaluation run failed.")

        # Cleanup
        openai_client.evals.delete(eval_id=eval_object.id)
        print("Evaluation deleted")

        project_client.agents.delete(agent_name=agent.name)
        print("Agent deleted")
    # </retrieve_evaluation_results>

The data_source configuration:

• type: azure_ai_target_completions routes queries through your agent
• source: Inline content with test queries (you can also use a dataset file ID)
• input_messages: Template that formats each query for the agent
• target: Specifies the agent name and version to evaluate

Retrieve evaluation results

Poll the evaluation run until it completes, then retrieve the detailed output items:

Python

    # ------------------------------------
    # Copyright (c) Microsoft Corporation.
    # Licensed under the MIT License.
    # ------------------------------------
    """
    DESCRIPTION:
        This sample demonstrates how to evaluate the Modern Workplace Assistant
        using the cloud evaluation API with built-in evaluators.

    USAGE:
        python evaluate.py

        Before running:
        pip install azure-ai-projects==2.0.0b3 python-dotenv openai

        Set these environment variables:
        1) PROJECT_ENDPOINT - Your Foundry project endpoint
        2) MODEL_DEPLOYMENT_NAME - Model deployment name (e.g., gpt-4o-mini)
    """

    # <imports_and_includes>
    import os
    import time
    from typing import Union
    from pprint import pprint
    from dotenv import load_dotenv
    from azure.identity import DefaultAzureCredential
    from azure.ai.projects import AIProjectClient
    from azure.ai.projects.models import PromptAgentDefinition
    from openai.types.eval_create_params import DataSourceConfigCustom
    from openai.types.evals.run_create_response import RunCreateResponse
    from openai.types.evals.run_retrieve_response import RunRetrieveResponse
    # </imports_and_includes>

    # <configure_evaluation>
    load_dotenv()
    endpoint = os.environ["PROJECT_ENDPOINT"]
    model_deployment_name = os.environ.get("MODEL_DEPLOYMENT_NAME", "gpt-4o-mini")

    with (
        DefaultAzureCredential() as credential,
        AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
        project_client.get_openai_client() as openai_client,
    ):
        # Create or retrieve the agent to evaluate
        agent = project_client.agents.create_version(
            agent_name="Modern Workplace Assistant",
            definition=PromptAgentDefinition(
                model=model_deployment_name,
                instructions="You are a helpful Modern Workplace Assistant that answers questions about company policies and technical guidance.",
            ),
        )
        print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

        # Define the data schema for evaluation
        data_source_config = DataSourceConfigCustom(
            type="custom",
            item_schema={
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"]
            },
            include_sample_schema=True,
        )

        # Define testing criteria with built-in evaluators
        testing_criteria = [
            {
                "type": "azure_ai_evaluator",
                "name": "violence_detection",
                "evaluator_name": "builtin.violence",
                "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_text}}"},
            },
            {
                "type": "azure_ai_evaluator",
                "name": "fluency",
                "evaluator_name": "builtin.fluency",
                "initialization_parameters": {"deployment_name": f"{model_deployment_name}"},
                "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_text}}"},
            },
            {
                "type": "azure_ai_evaluator",
                "name": "task_adherence",
                "evaluator_name": "builtin.task_adherence",
                "initialization_parameters": {"deployment_name": f"{model_deployment_name}"},
                "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_items}}"},
            },
        ]

        # Create the evaluation object
        eval_object = openai_client.evals.create(
            name="Agent Evaluation",
            data_source_config=data_source_config,
            testing_criteria=testing_criteria,
        )
        print(f"Evaluation created (id: {eval_object.id}, name: {eval_object.name})")
    # </configure_evaluation>

    # <run_cloud_evaluation>
        # Define the data source for the evaluation run
        data_source = {
            "type": "azure_ai_target_completions",
            "source": {
                "type": "file_content",
                "content": [
                    {"item": {"query": "What is Contoso's remote work policy?"}},
                    {"item": {"query": "What are the security requirements for remote employees?"}},
                    {"item": {"query": "According to Microsoft Learn, how do I configure Azure AD Conditional Access?"}},
                    {"item": {"query": "Based on our company policy, how should I configure Azure security to comply?"}},
                ],
            },
            "input_messages": {
                "type": "template",
                "template": [
                    {"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}
                ],
            },
            "target": {
                "type": "azure_ai_agent",
                "name": agent.name,
                "version": agent.version,
            },
        }

        # Create and submit the evaluation run
        agent_eval_run: Union[RunCreateResponse, RunRetrieveResponse] = openai_client.evals.runs.create(
            eval_id=eval_object.id,
            name=f"Evaluation Run for Agent {agent.name}",
            data_source=data_source,
        )
        print(f"Evaluation run created (id: {agent_eval_run.id})")
    # </run_cloud_evaluation>

    # <retrieve_evaluation_results>
        # Poll until the evaluation run completes
        while agent_eval_run.status not in ["completed", "failed"]:
            agent_eval_run = openai_client.evals.runs.retrieve(
                run_id=agent_eval_run.id,
                eval_id=eval_object.id
            )
            print(f"Waiting for eval run to complete... current status: {agent_eval_run.status}")
            time.sleep(5)

        if agent_eval_run.status == "completed":
            print("\n✓ Evaluation run completed successfully!")
            print(f"Result Counts: {agent_eval_run.result_counts}")

            # Retrieve detailed output items
            output_items = list(
                openai_client.evals.runs.output_items.list(
                    run_id=agent_eval_run.id,
                    eval_id=eval_object.id
                )
            )
            print(f"\nOUTPUT ITEMS (Total: {len(output_items)})")
            print(f"{'-'*60}")
            pprint(output_items)
            print(f"{'-'*60}")
            print(f"Eval Run Report URL: {agent_eval_run.report_url}")
        else:
            print("\n✗ Evaluation run failed.")

        # Cleanup
        openai_client.evals.delete(eval_id=eval_object.id)
        print("Evaluation deleted")

        project_client.agents.delete(agent_name=agent.name)
        print("Agent deleted")
    # </retrieve_evaluation_results>

Each output item includes:

• Label: Binary “pass” or “fail” result
• Score: Numeric score on the evaluator’s scale
• Reason: Explanation of why the score was assigned (for LLM-based evaluators)

Expected output from cloud evaluation (evaluate.py)

When you run the evaluation script, you see output similar to the following example. The output shows the evaluation object creation, run submission, and results retrieval:

python evaluate.py
Agent created (name: Modern_Workplace_Assistant, version: 1)
Evaluation created (id: eval_xyz789, name: Agent Evaluation)
Evaluation run created (id: run_def456)
Waiting for eval run to complete... current status: running
Waiting for eval run to complete... current status: running

✓ Evaluation run completed successfully!
Result Counts: {'passed': 2, 'failed': 0, 'errored': 0}

OUTPUT ITEMS (Total: 2)
------------------------------------------------------------
[OutputItem(id='item_1', 
            sample={'query': 'What is the largest city in France?', 
                    'output_text': 'The largest city in France is Paris...'},
            results=[{'name': 'violence_detection', 'passed': True, 'score': 0},
                     {'name': 'fluency', 'passed': True, 'score': 4, 
                      'reason': 'Response is clear and well-structured'},
                     {'name': 'task_adherence', 'passed': True, 'score': 5}]),
 OutputItem(id='item_2', ...)]
------------------------------------------------------------
Eval Run Report URL: https://ai.azure.com/...
Evaluation deleted
Agent deleted

Understanding evaluation results

Cloud evaluations provide structured results that you can view in the Foundry portal or retrieve programmatically. Each output item includes:

Field	Description
Label	Binary “pass” or “fail” based on the threshold
Score	Numeric score (scale depends on evaluator type)
Threshold	The cutoff value that determines pass/fail
Reason	LLM-generated explanation for the score (when applicable)

Score scales by evaluator type:

• Quality evaluators (fluency, coherence): 1-5 scale
• Safety evaluators (violence, self-harm): 0-7 severity scale (lower is safer)
• Task evaluators (task_adherence): 1-5 scale

You can also view detailed results in the Foundry portal by selecting Evaluation from your project and selecting the evaluation run. The portal provides visualizations, filtering, and export options.

For production scenarios, consider running evaluations as part of your CI/CD pipeline. See How to run an evaluation in Azure DevOps, and Continuously evaluate your AI agents for integration patterns.

Summary

You now have:

• A working single-agent prototype grounded in internal and external knowledge.
• A repeatable evaluation script demonstrating enterprise validation patterns.
• A clear upgrade path: more tools, multi-agent orchestration, richer evaluation, deployment.

These patterns reduce prototype-to-production friction: you can add data sources, enforce governance, and integrate monitoring without rewriting core logic.

Next steps

This tutorial demonstrates Stage 1 of the developer journey - from idea to prototype. This minimal sample provides the foundation for enterprise AI development. To continue your journey, explore the next stages:

Suggested additional enhancements

• Add more data sources (Azure AI Search, other sources).
• Implement advanced evaluation methods (AI-assisted evaluation).
• Create custom tools for business-specific operations.
• Add conversation memory and personalization.

Stage 2: Prototype to production

• Implement safety assessment with red-team testing.
• Create comprehensive evaluation datasets with quality metrics.
• Apply organization-wide governance policies and model comparison.
• Configure fleet monitoring, CI/CD integration, and production deployment endpoints.

Stage 3: Production to adoption

• Collect trace data and user feedback from production deployments.
• Fine-tune models and generate evaluation insights for continuous improvement.
• Integrate Azure API Management gateway with continuous quality monitoring.
• Implement fleet governance, compliance controls, and cost optimization.

Related content

• Foundry Agent Service overview
• SharePoint tool documentation
• MCP tool integration
• Multi-agent patterns