Contoso Refund Agent — Foundry Hosted Agent

A hosted agent for Azure AI Foundry that handles refund policy lookups and order data queries. Uses the Responses protocol with Foundry Toolbox MCP for tool access.

Architecture

┌──────────────────────────────────────────────────────┐
│  Foundry Agent Service (Hosted Agent)                │
│                                                      │
│  ┌────────────┐    ┌─────────────────────────────┐   │
│  │  Responses │───▶│  Agentic Loop (GPT-4.1)     │   │
│  │  Protocol  │    │  + Toolbox MCP calls         │   │
│  │  :8088     │    └─────────────────────────────┘   │
│  └────────────┘              │                       │
│                              ▼                       │
│                    ┌─────────────────────┐           │
│                    │  Foundry Toolbox    │           │
│                    │  ┌───────────────┐  │           │
│                    │  │ Foundry IQ    │  │           │
│                    │  │ (policies)    │  │           │
│                    │  ├───────────────┤  │           │
│                    │  │ Fabric IQ     │  │           │
│                    │  │ (order data)  │  │           │
│                    │  ├───────────────┤  │           │
│                    │  │ Work IQ       │  │           │
│                    │  │ (email/comms) │  │           │
│                    │  └───────────────┘  │           │
│                    └─────────────────────┘           │
└──────────────────────────────────────────────────────┘

Blueprint (agent.yaml)

Every hosted agent comes with a blueprint that defines:

• Protocol: responses (OpenAI-compatible /responses endpoint)
• Resources: CPU/memory allocation for the sandbox
• Environment variables: Configuration injected at deploy time
• Toolbox: MCP-connected tools (Foundry IQ, Fabric IQ, Work IQ)

Prerequisites

• Azure AI Foundry project with a model deployment (e.g., gpt-4.1)
• Foundry Toolbox configured with your IQ connections
• Azure Container Registry (for deployment)

Local Development

# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # macOS/Linux

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your Foundry project endpoint and toolbox name

# Run locally
python main.py

# Test (in another terminal)
curl -sS -X POST http://localhost:8088/responses \
    -H "Content-Type: application/json" \
    -d '{"input": "Check refund eligibility for order #8822", "stream": false}'

Deploy to Foundry

# Build container (must be linux/amd64)
docker build --platform linux/amd64 -t contoso-refund-agent .

# Tag and push to ACR
docker tag contoso-refund-agent <your-acr>.azurecr.io/contoso-refund-agent:latest
docker push <your-acr>.azurecr.io/contoso-refund-agent:latest

# Deploy using azd or the Foundry SDK

Environment Variables

Variable	Description	Auto-injected
FOUNDRY_PROJECT_ENDPOINT	Foundry project endpoint	✅
AZURE_AI_MODEL_DEPLOYMENT_NAME	Model deployment name	❌
TOOLBOX_NAME	Toolbox resource name	❌
APPLICATIONINSIGHTS_CONNECTION_STRING	App Insights connection	✅