[Hosted Agents] Container readiness probe fails - documentation doesn't specify health endpoint

[Arturo-Quiroga-MSFT]

Description

When deploying a hosted agent following the official documentation, the deployment fails with ContainerProbesFailed error. The documentation doesn't clearly specify which health endpoint Azure Container Apps probes for readiness checks.

Environment

• Region: North Central US
• SDK: azure-ai-projects==2.0.0b3
• Hosting Adapter: azure-ai-agentserver-agentframework==1.0.0b9
• Agent Framework: agent-framework==1.0.0b260107

Steps to Reproduce

1. Create a hosted agent following the documentation at https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents
2. Use the sample Dockerfile pattern from the docs
3. Deploy using client.agents.create_version() and az cognitiveservices agent start
4. Deployment stays in "Starting" status indefinitely

Error

Portal shows only one line in deployment logs:

[ContainerProbesFailed] User Error Occurred - Container readiness probes failed.

Root Cause Found

The Dockerfile in documentation examples uses:

HEALTHCHECK CMD curl -f http://localhost:8088/ || exit 1

But the hosting adapter exposes /readiness endpoint, not /. Azure Container Apps probes /readiness.

Suggested Fix

1. Update documentation to clarify that the hosting adapter provides /readiness and /health endpoints
2. Update sample Dockerfiles to use:

HEALTHCHECK CMD curl -f http://localhost:8088/readiness || exit 1

3. Document the expected health endpoints in the "Package code and test locally" section

Additional Issue: Container Log API Not Working

The documented REST API for viewing container logs returns UnsupportedAction:

Documented endpoint:

GET /agents/v2.0/.../containers/default:logstream?kind=console&tail=50

Response:

{"error":{"code":"UnsupportedAction","message":"The requested action 'agents/.../containers/default:logstream' is not supported"}}

This makes troubleshooting deployment failures very difficult as the only diagnostic information is the single-line error in the portal.

Related Documentation

• https://learn.microsoft.com/en-us/azure/ai-foundry/agents/concepts/hosted-agents
• https://github.com/azure-ai-foundry/foundry-samples/tree/main/samples/python/hosted-agents