New lab - add AI Foundry Hosted Agents lab with custom frameworks

[georgeollis]

PR: AI Foundry Hosted Agents with Custom Frameworks

Purpose

• Adds a new lab (ai-foundry-hosted-agents-custom-framework) that extends the existing Hosted Agents scenario with framework-specific agent implementations.
• Demonstrates how to build, containerise, and deploy AI Foundry Hosted Agents using Strands Agents and Pydantic AI as custom runtimes, while keeping a common deployment pattern via Microsoft Foundry and Azure API Management.
• Includes Bicep infrastructure for Azure API Management, Microsoft Foundry (two AI Services resources), Azure Container Registry, and Application Insights, along with end-to-end setup notebooks and Dockerfiles for each framework.

Does this introduce a breaking change?

[ ] Yes
[x] No

Pull Request Type

What kind of change does this Pull Request introduce?

[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Documentation content changes
[ ] Other... Please describe:

How to Test

• Get the code

git clone [repo-address]
cd [repo-name]
git checkout [branch-name]

• Test the code

1. Open labs/ai-foundry-hosted-agents-custom-framework/ai-foundry-hosted-agents-custom-framework.ipynb
   and run all cells to deploy core infrastructure (APIM, Foundry, ACR, App Insights).

2. For the Strands framework:
   - Open src/responses/agents/frameworks/01_hosted_agent_strands_setup.ipynb
   - Run all cells in order:
       a. Build and push the Docker image from strands/ to ACR.
       b. Create a Foundry Hosted Agent version referencing the image.
       c. Test a direct Foundry Responses API call (expects a valid JSON response).
       d. Test the same call routed through APIM (expects the same valid response).

3. For the Pydantic AI framework:
   - Open src/responses/agents/frameworks/02_hosted_agent_pydantic_setup.ipynb
   - Repeat steps a–d above using the pydantic/ directory and agent.

4. Run clean-up-resources.ipynb to delete all provisioned Azure resources.

What to Check

Verify that the following are valid:

• Bicep deployment completes without errors and all resources (APIM, two Foundry AI Services, ACR, App Insights, Log Analytics) are created in the target resource group.
• RBAC role assignments are created correctly: ACR Reader/AcrPull for the Foundry hosted-agent resource; ACR Writer/Catalog Lister for the deploying user; Foundry User for all configured object IDs.
• Both Docker images (Strands and Pydantic AI) build and push to ACR successfully.
• Hosted Agent versions are registered in Foundry and reach a running state.
• Direct Foundry Responses API call returns a well-formed response for both frameworks.
• APIM-proxied call returns the same response, confirming managed identity token injection and header enforcement (Foundry-Features: HostedAgents=V1Preview) are working.
• Multi-turn conversation (via conversation_id / previous_response_id) works correctly for the Strands implementation.
• Streaming responses (TextResponse delta SSE events) are emitted correctly for the Strands agent.
• Clean-up notebook removes all provisioned resources without errors.

Other Information

• The lab targets the Foundry Hosted Agents Responses protocol v1.0.0 (azure-ai-agentserver).
• The APIM policy (hosted-agent-policy.xml) proxies Foundry Hosted Agent Responses and injects a managed identity bearer token; client authentication uses an APIM subscription key.
• Agent images are based on python:3.12-slim.
• Required environment variables for each agent runtime are documented in src/responses/agents/frameworks/strands/example.env and src/responses/agents/frameworks/pydantic/example.env.