> ## 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.

# Run a hosted agent locally with the Azure Developer CLI

> Start and test a Microsoft Foundry hosted agent on your local machine with azd before you deploy it to Foundry.

Use `azd ai agent run` to start your Microsoft Foundry hosted agent on your local machine and `azd ai agent invoke --local` to test it without deploying to Azure. You also learn how to set ports, choose an agent in a multi-agent project, override startup commands, and pass local runtime secrets.

## 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.
* Required language runtimes for your agent, such as Python 3.10+, .NET 8+, or Node.js.

## Start the agent

* Start the agent from your project directory:

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

  This command auto-detects the project type (Python, .NET, Node.js), installs dependencies, and starts the agent server on `localhost:8088`. The startup command is read from the `startupCommand` property in `azure.yaml`.

<Tip>
  `azd ai agent run` automatically injects environment variables from your default [azd environment](/agents/azure-yaml-reference), the one you set with `azd env select` or created during `azd ai agent init`. This means variables like `FOUNDRY_PROJECT_ENDPOINT`, `AZURE_SUBSCRIPTION_ID`, and any values you've set with `azd env set` are available to your agent without manual configuration.

  See [Configure environment variables for a hosted agent](/agents/configure-hosted-agent-env-variables) for the full list.
</Tip>

## Start on a custom port

* Pass `--port` when the default port is unavailable:

  ```bash theme={null}
  azd ai agent run --port 9090
  ```

## Start a specific agent

* If your project defines multiple agents, specify which one to run:

  ```bash theme={null}
  azd ai agent run my-agent
  ```

## Override the startup command

* Pass `--start-command` to override the command in `azure.yaml`:

  ```bash theme={null}
  azd ai agent run --start-command "python app.py"
  ```

  This overrides the `startupCommand` defined in your `azure.yaml` service configuration. The `startupCommand` is the default command used both for local development (`azd ai agent run`) and for container startup when deployed. See [azure.yaml service configuration](/agents/azure-yaml-reference) for details.

## Pass environment variables and secrets

A local run reads the `env` map declared in the `azure.ai.agent` service in `azure.yaml` and resolves any `${VAR}` placeholders from the active `azd` environment. To provide a value, such as an API key, set it as an `azd` environment variable and reference it in `azure.yaml`.

1. Set the value in the active `azd` environment:

   ```bash theme={null}
   azd env set OPENAI_KEY <value>
   ```

   `azd` stores environment values in `.azure/<env>/.env`. The `.azure` directory is gitignored by default, so these values stay out of source control.

2. Reference the variable in the `azure.ai.agent` service in `azure.yaml` so the local run injects it:

   ```yaml theme={null}
   services:
     my-agent:
       host: azure.ai.agent
       env:
         OPENAI_KEY: ${OPENAI_KEY}
   ```

For secrets that shouldn't live in a local `.env` file at all, store them in a Foundry project connection and reference them with a `${{connections.<name>.credentials.<field>}}` placeholder in the `env` map. The platform resolves the placeholder at runtime. For more information, see [Configure environment variables for a hosted agent](/agents/configure-hosted-agent-env-variables).

## Test with invoke

* Open a separate terminal and send a message to your running agent:

  ```bash theme={null}
  azd ai agent invoke --local "Hello, what can you do?"
  ```

  The `--local` flag routes the request to `localhost:8088` instead of the deployed endpoint.

### Test protocols with invoke

The protocol your agent uses is defined in the `protocols` field of the `azure.ai.agent` service in `azure.yaml`. If your agent implements the `responses` protocol, `invoke` sends a standard Responses API request. If your agent uses the `invocations` protocol, the payload is whatever your agent code expects. Use `--input-file` (`-f`) to send a custom JSON body:

```bash theme={null}
azd ai agent invoke --local -f request.json
```

For `invocations` agents, refer to the sample's README or inspect the handler or entry point to understand the expected payload structure.

If your agent implements multiple protocols, `invoke` uses the `responses` protocol by default. Pass `-p` (`--protocol`) with `responses` or `invocations` to select one explicitly:

```bash theme={null}
azd ai agent invoke --local --protocol invocations -f request.json
```

## Test with curl

* Test directly with `curl`:

  ```bash theme={null}
  curl -X POST http://localhost:8088/responses \
    -H "Content-Type: application/json" \
    -d '{"input": "Hello, what can you do?"}'
  ```

## Troubleshoot local development

| Issue                           | Solution                                          |
| ------------------------------- | ------------------------------------------------- |
| `AuthenticationError`           | Run `azd auth login` to refresh credentials.      |
| `ResourceNotFound`              | Verify endpoint URLs match Foundry portal values. |
| `DeploymentNotFound`            | Check the deployment name in your `azure.yaml`.   |
| Connection refused on port 8088 | Ensure no other process is using the port.        |
| Dependencies fail to install    | Ensure Python 3.10+ or .NET 8+ is installed.      |

## Related content

* [Invoke a hosted agent with the Azure Developer CLI](/agents/invoke-hosted-agent) for invoke options, sessions, and file input.
* [Inspect a local agent with the Agent Inspector](/agents/agent-inspector) for a browser-based local test UI.
* [Configure environment variables for a hosted agent](/agents/configure-hosted-agent-env-variables) for local and deployed configuration.