> ## Documentation Index
> Fetch the complete documentation index at: https://hobbyist-e43fa225.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnose a project with agent doctor

> Run azd ai agent doctor to check Microsoft Foundry hosted agent project health before eval, optimize, deploy, or troubleshooting.

<Info>
  Items marked (preview) in this article are currently in public 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](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).
</Info>

`azd ai agent doctor` runs a sequence of local and remote checks against your current Microsoft Foundry azd project and reports the results. Use it to recover after losing terminal context, hitting a confusing error, or picking a project back up after a break.

## Prerequisites

* An initialized hosted agent project. To create one, see [Initialize an agent project](/agents/init-agent-project).
* The azd Foundry extensions installed. For installation steps, see [Install the azd Foundry extensions](/developer-tools-and-integrations/install-cli-foundry-extensions).
* An authenticated Azure Developer CLI session. Run `azd auth login` if needed.
* For remote checks, an azd environment that resolves to a Foundry project endpoint. For context resolution, see [Understand azd project context](/developer-tools-and-integrations/cli-project-context).

## Choose when to run doctor

Run `doctor` when:

* You came back to a project after a few days and forgot where you left off.
* A command failed with a confusing error and you want a structured view of what is set up versus missing.
* You want to confirm that azd, your Foundry project endpoint, your role assignments, and your deployed agent are all in a healthy state before kicking off a long-running operation such as eval, optimize, or deploy.

`doctor` doesn't change any state. It only reads.

## Review checked areas

Each invocation runs a set of checks, including but not limited to:

* **Local**: azd version; `azure.yaml` is present and parseable; `azure.yaml` declares an `azure.ai.agent` service; `.env` for the active azd env has the expected keys; container build prerequisites are present for container deploy; entry point and runtime are valid for code deploy.
* **Remote**: the Foundry project endpoint resolves and is reachable; required role assignments exist on the project; the deployed agent, if any, exists and can be invoked; the model deployment referenced by `azure.yaml` exists.

Each check reports `pass`, `fail`, or `skip`. When every executed check passes, the report also suggests the next command to run, such as `azd ai agent eval generate`.

## Interpret exit codes

| Exit code | Meaning                                                             |
| --------- | ------------------------------------------------------------------- |
| `0`       | At least one check passed and no checks failed.                     |
| `1`       | At least one check failed.                                          |
| `2`       | All checks were skipped, for example when preconditions aren't met. |

These exit codes are stable enough to use in CI. A `doctor` step before `azd up` can fail fast if the runner is missing role assignments or environment variables.

## Choose useful flags

| Flag           | Description                                                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `--local-only` | Skip remote, network-dependent checks. Use when offline, behind a proxy, or for a fast local triage.                          |
| `--unredacted` | Show raw principal IDs, scope ARNs, and UPNs in the report. By default, sensitive identifiers are redacted in console output. |

## Run doctor

1. Run the full diagnostic, local plus remote:

   ```bash theme={null}
   azd ai agent doctor
   ```

2. Run a fast triage while offline by skipping remote checks:

   ```bash theme={null}
   azd ai agent doctor --local-only
   ```

3. Show raw identifiers in the report when sharing with support:

   ```bash theme={null}
   azd ai agent doctor --unredacted
   ```

## Fix failures

Use this common loop when something is wrong:

1. Run `azd ai agent doctor` and read the failed checks.
2. Fix the first failed check, such as adding a missing role assignment, setting a missing environment variable, or rerunning `azd auth login`.
3. Rerun `azd ai agent doctor` until everything passes.
4. Follow the "next step" suggestion at the bottom of the report.

## Related content

* [Debug a hosted agent](/agents/debug-hosted-agent) for broader troubleshooting tactics.
* [Run a hosted agent locally with the Azure Developer CLI](/agents/run-hosted-agent-locally) to validate local startup.
* [Understand azd project context](/developer-tools-and-integrations/cli-project-context) for endpoint resolution used by remote checks.