How to Fix Azure Health Bot: Setup, Config & Billing Errors

If you're still on the Legacy Standard S1 tier, you're running on deprecated infrastructure. No new S1 instances can be created as of November 2025, and while existing S1 agents continue to function, you cannot access any Generative AI capabilities, including customer source grounding, credible source responses backed by medical databases, or interactive triage sessions. Those capabilities only exist in C1.

To change your tier, open the Azure portal and go to your healthcare agent service resource. In the left menu, select Settings, then click Pricing tier. You'll see options for Free (F0) and Agent Tier C1. Select C1 (PAYGO) and click Apply.

Here's what actually changes when you make this move: the fixed $500/month fee goes away. Under C1, you pay $0.01 per Action, and Actions are consumed differently depending on what feature handles the response. A standard rule-based answer uses 1 Action. A response grounded in your own uploaded documents or websites uses 2 Actions. A response that draws from the built-in medical intelligence and healthcare databases costs 5 Actions. A full triage session, the interactive clinical question-and-answer flow, costs 18 Actions per session.

Before you flip the switch on a production agent, model your expected Action consumption. If your bot handles 10,000 standard messages per month, that's $100. If 500 of those escalate to triage sessions, add another $90. Most teams find C1 significantly cheaper than S1 once they run the math, but you need to actually run the math for your usage pattern. After upgrading, check Cost Management + Billing within 48 hours to confirm the new meter is active.

Healthcare agent service uses Azure Active Directory app registrations for identity. When authentication breaks, your agent goes silent, no error to the end user, just no response. The most common cause is an expired client secret on the app registration tied to your agent.

Open the Azure portal and navigate to Azure Active Directory > App registrations. Find the registration associated with your healthcare agent service instance (it typically has the same display name you gave the agent during setup). Click Certificates & secrets. If any client secrets show an expiration date in the past, that's your problem.

Create a new secret by clicking New client secret, set the expiration period (12 or 24 months is typical for production), copy the value immediately, it's only shown once, and then update the corresponding secret in your agent's configuration. In the healthcare agent service portal, go to Settings > Bot Management Settings and paste the new secret into the correct field.

# Check your app registration's expiration via Azure CLI
az ad app credential list --id <your-app-id> --query "[].{EndDate:endDateTime, KeyId:keyId}"

For multi-tenant deployments, also verify that the app registration's Supported account types is set correctly. Single-tenant agents registered as multi-tenant (or vice versa) will produce authentication errors that look identical to expired credential errors in the portal logs, which wastes a lot of time. Set it to match your actual deployment topology. After updating credentials, re-publish your agent and test in the emulator before pushing to production channels.

Customer extensions, those integrations where your agent calls out to an external OpenAPI service, a conversational service, or another backend, consume 2 Actions each and are one of the most powerful features in the platform. They're also one of the most common points of failure, and when they break, they tend to break silently from the patient's perspective.

Start your diagnosis in the healthcare agent service portal under Integration > Extensions. Each extension has a connection status indicator. A yellow or red status here means the agent can't reach your endpoint. Click the extension name and use the Test Connection button to see the actual HTTP response.

The most common causes of extension failures, in order: TLS certificate mismatch on your backend endpoint (the healthcare agent service requires valid, publicly trusted certificates, self-signed certs will be rejected), network security group rules on Azure-hosted backends blocking the agent service's outbound IP ranges, and schema mismatches between your OpenAPI spec and your actual API response shape.

# Test your extension endpoint directly to rule out cert issues
curl -v --tlsv1.2 https://your-extension-endpoint.com/api/health

For OpenAPI spec issues specifically, validate your spec at the extension configuration screen, the portal has a built-in validator. Pay close attention to required vs. optional fields; if your live API returns a field as nullable but your spec marks it required, the agent runtime will throw a schema validation error and fall back to a generic response. That's frustrating to debug because the scenario appears to execute correctly in the designer preview but fails in live traffic.

Once you've identified and fixed the root cause, re-import your OpenAPI spec, re-validate the extension, then re-publish the agent. Always confirm the extension shows a green connection status before pushing to end users.

Triage sessions are the most sophisticated feature in the healthcare agent service, they guide a patient through a dynamic clinical question-and-answer flow based on their reported symptoms and recommend appropriate next steps. At 18 Actions per session, they're also the most expensive interaction type, so when they break, it stings both ways.

The most common triage session problem is a session that starts but cuts off mid-flow, returning a generic message like "I'm sorry, I couldn't complete your request." This almost always traces back to one of three things: a missing or misconfigured medical protocol, a localization setting mismatch, or an Actions quota exhaustion mid-session on the Free F0 tier.

For the Free tier specifically: F0 has strict monthly usage caps. If your organization is using F0 for anything beyond genuine evaluation and development, you will hit those caps and triage sessions will terminate unexpectedly. The fix is to upgrade to C1, the Free tier is explicitly recommended only for experimentation, not production patient interactions.

For medical protocol issues, go to Medical Protocols in the healthcare agent service portal and verify that the protocols your triage scenario references are enabled and up to date. Microsoft periodically updates the built-in clinical content; if a protocol was auto-updated and you have hardcoded references to a specific version in your scenario logic, the mismatch will cause silent failures.

// In your scenario's "On Error" handler, log the full error object:
// This surfaces the actual failure reason in your conversation logs
conversation.memory["debug_error"] = scenario.error.message;

Add an explicit error handler to every triage scenario. Without one, you're flying blind when failures occur in production. Route error states to a handoff flow that connects the patient to a human agent, and log the error context to your conversation memory for post-session analysis.

Credible source responses are what make the healthcare agent service genuinely useful for patient education, they ground answers in built-in medical databases, clinical guidelines, and trusted third-party health intelligence sources. Each response costs 5 Actions, which reflects the real-time retrieval and synthesis happening behind the scenes. When this feature breaks, patients get either no response or a generic fallback that doesn't actually answer their medical question.

First, confirm you're on the C1 tier. Credible source is not available on F0 or S1, full stop. If you're on C1 and credible source responses are still failing, the next thing to check is your agent's language and region configuration. The built-in healthcare intelligence is not uniformly available across all locales. Some clinical databases are English-only or limited to specific regional markets. Go to Settings > Language and Regional Settings and confirm your configured locale has full credible source support.

If locale isn't the issue, check whether your scenario is correctly configured to invoke credible source. In the scenario designer, the response node needs to have Response type: Credible Source selected, not "Classic" and not "Customer Source." These are distinct response types that bill differently and draw from different knowledge bases. A scenario accidentally set to Classic will give a rule-based response even if you have credible source enabled at the resource level.

// Verify response type in scenario JSON export
// Look for the "responseType" field in each dialog node:
{
  "type": "prompt",
  "responseType": "credibleSource",  // Must be this, not "classic"
  "text": "What is your question?"
}

Finally, check your compliance configuration. Healthcare agent service operates under a strict compliance framework, it holds certifications including GDPR, HIPAA-adjacent standards through ISO 27018, SOC 2 Type 2, and many others. Some credible source content has jurisdictional restrictions baked in. If your tenant is configured for a region where certain clinical guidance cannot be surfaced due to regulatory requirements, the response will silently fall back rather than surface restricted content. Contact Microsoft Support if you believe you're hitting a regional content restriction.