docs: improve Azure OpenAI integration documentation #8499

vbs-0 · 2025-05-14T03:25:33Z

Description

This PR improves the Azure OpenAI integration documentation to address issue #8412. The documentation was unclear about environment variables and authentication methods, especially for Azure AD token authentication in headless mode.

Changes Made

Added clear separation between API Key and Azure AD Token authentication methods
Documented all relevant environment variables with examples
Added detailed examples for both authentication methods
Improved UI configuration instructions
Added a troubleshooting section
Fixed formatting and organization

Changelog Message

Added comprehensive documentation for Azure OpenAI integration, including both API key and AD token authentication methods, with clear examples and troubleshooting guide.

Type of Change

Testing Done

Verified all environment variables mentioned are correct
Confirmed documentation aligns with LiteLLM implementation
Checked formatting in both light and dark modes
Validated all links work correctly

Related Issues

Fixes #8412 (#8412)

Additional Notes

The documentation now includes both authentication methods with clear examples, which should help users avoid confusion about which environment variables to use.

…y vbs_0)

- Add clear instructions for both API key and AD token authentication - Clarify required environment variables - Add troubleshooting section - Fix formatting and organization - Addresses issue OpenHands#8412

mamoodi · 2025-05-14T14:47:48Z

docs/modules/usage/llms/azure-llms.md


-When running OpenHands, you'll need to set the following environment variable using `-e` in the
-[docker run command](../installation#running-openhands):
+OpenHands supports two authentication methods for Azure OpenAI:


Suggested change

OpenHands supports two authentication methods for Azure OpenAI:

OpenHands supports the following authentication methods for Azure OpenAI:

mamoodi · 2025-05-14T14:48:00Z

docs/modules/usage/llms/azure-llms.md

-[docker run command](../installation#running-openhands):
+OpenHands supports two authentication methods for Azure OpenAI:

+### 1. API Key Authentication


Suggested change

### 1. API Key Authentication

### API Key Authentication

mamoodi · 2025-05-14T14:48:09Z

docs/modules/usage/llms/azure-llms.md

 ```

-Example:
+### 2. Azure AD Token Authentication


Suggested change

### 2. Azure AD Token Authentication

### Azure AD Token Authentication

mamoodi · 2025-05-14T14:48:52Z

docs/modules/usage/llms/azure-llms.md

-   - `Custom Model` to azure/&lt;deployment-name&gt;
-   - `Base URL` to your Azure API Base URL (e.g. `https://example-endpoint.openai.azure.com`)
-   - `API Key` to your Azure API key
+   - `LLM Provider` to `Azure`


Suggested change

- `LLM Provider` to `Azure`

mamoodi · 2025-05-14T14:50:57Z

docs/modules/usage/llms/azure-llms.md

+```bash
+# Required
+LLM_API_VERSION="<api-version>"              # e.g. "2024-02-15-preview"
+LLM_BASE_URL="<azure-endpoint>"              # e.g. "https://your-resource.openai.azure.com/"


If using the UI, you don't need to set:
LLM_BASE_URL
LLM_API_KEY
LLM_MODEL

because what you set in the settings in the UI will overwrite these.

why does the UI force a choice when these variables are set?

That's a good question. Been like that since I remember and there's a big github issue on that.

Ah I see enyst already linked it below.

mamoodi · 2025-05-14T14:52:22Z

docs/modules/usage/llms/azure-llms.md

+    -e LLM_BASE_URL="https://your-resource.openai.azure.com/" \
+    -e LLM_API_KEY="your-api-key" \
+    -e LLM_MODEL="azure/your-deployment-name" \
+    docker.all-hands.dev/all-hands-ai/openhands:latest


Same comment as above. LLM_BASE_URL, LLM_API_KEY, LLM_MODEL should not be needed.

Just replace docker.all-hands.dev/all-hands-ai/openhands:latest with ... to note that the rest of the docker command is the same as the original docker command to run OpenHands.

what should happen instead is the UI should not force you to re-enter the config if these are set

another bug?

Yes, that is this bug:

[Bug]: Configuration behavior is unpredictable #3220

What happened here was that the UI was reading them only from local storage, not backend, a long time ago, and then we refactored that to read and write on the web server, but it still doesn't do it from the application configuration.

I think it might be better to document running with UI without these vars (that are overridden by the UI), and only document these vars when running CLI or headless, which read them and follow them.

mamoodi · 2025-05-14T14:52:49Z

docs/modules/usage/llms/azure-llms.md

+LLM_API_VERSION="<api-version>"              # e.g. "2024-02-15-preview"
+LLM_BASE_URL="<azure-endpoint>"              # e.g. "https://your-resource.openai.azure.com/"
+AZURE_AD_TOKEN="<your-ad-token>"            # Your Azure AD access token
+LLM_MODEL="azure/<deployment-name>"          # e.g. "azure/gpt-4" where gpt-4 is your deployment name


Same as above. LLM_BASE_URL and LLM_MODEL are not needed since they will be set in the UI

mamoodi · 2025-05-14T14:52:57Z

docs/modules/usage/llms/azure-llms.md

+    -e LLM_BASE_URL="https://your-resource.openai.azure.com/" \
+    -e AZURE_AD_TOKEN="your-ad-token" \
+    -e LLM_MODEL="azure/your-deployment-name" \
+    docker.all-hands.dev/all-hands-ai/openhands:latest


Same comments as the above command

mamoodi · 2025-05-14T14:53:13Z

docs/modules/usage/llms/azure-llms.md

-   - `Base URL` to your Azure API Base URL (e.g. `https://example-endpoint.openai.azure.com`)
-   - `API Key` to your Azure API key
+   - `LLM Provider` to `Azure`
+   - `Advanced` options:


Suggested change

- `Advanced` options:

pcuci

not clear how to disable the UI modal when the LLM_* variables are set

would that be another variable somewhere to force env var pickup?

pcuci · 2025-05-16T19:21:10Z

docs/modules/usage/llms/azure-llms.md

+```bash
+# Required
+LLM_API_VERSION="<api-version>"              # e.g. "2024-02-15-preview"
+LLM_BASE_URL="<azure-endpoint>"              # e.g. "https://your-resource.openai.azure.com/"


why does the UI force a choice when these variables are set?

pcuci · 2025-05-16T19:22:56Z

docs/modules/usage/llms/azure-llms.md

+    -e LLM_BASE_URL="https://your-resource.openai.azure.com/" \
+    -e LLM_API_KEY="your-api-key" \
+    -e LLM_MODEL="azure/your-deployment-name" \
+    docker.all-hands.dev/all-hands-ai/openhands:latest


what should happen instead is the UI should not force you to re-enter the config if these are set

another bug?

github-actions · 2025-06-16T02:12:41Z

This PR is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.

enyst · 2025-06-16T15:17:51Z

docs/modules/usage/llms/azure-llms.md

+# Required
+LLM_API_VERSION="<api-version>"              # e.g. "2024-02-15-preview"
+LLM_BASE_URL="<azure-endpoint>"              # e.g. "https://your-resource.openai.azure.com/"
+AZURE_AD_TOKEN="<your-ad-token>"            # Your Azure AD access token


Documentation for the AD token use is welcome! I have some doubt here though, does this really work like this? I thought this token is refreshed periodically, in which case maybe it works when the user starts, but then it stops working.

I think litellm has AD token support. I’m just not sure that it works for us this way. Please feel free to correct me if wrong.

mamoodi · 2025-07-18T14:48:16Z

Hi there. This PR has been open for a while without addressing any of the comments. I'm going to close it. But feel free to let me know if I'm mistaken! And feel free to open a new PR once ready! Thank you.

vbs-0 added 4 commits May 13, 2025 08:47

fix: improve WebSocket reconnection logic for terminal reliability (b…

84f42ec

…y vbs_0)

Merge branch 'All-Hands-AI:main' into main

d2cdea2

Update ws-client-provider.tsx

e8d2b76

docs: improve Azure OpenAI integration documentation

0636b7b

- Add clear instructions for both API key and AD token authentication - Clarify required environment variables - Add troubleshooting section - Fix formatting and organization - Addresses issue OpenHands#8412

vbs-0 requested a review from mamoodi as a code owner May 14, 2025 03:25

mamoodi reviewed May 14, 2025

View reviewed changes

pcuci reviewed May 16, 2025

View reviewed changes

github-actions bot added the Stale Inactive for 40 days label Jun 16, 2025

enyst reviewed Jun 16, 2025

View reviewed changes

github-actions bot removed the Stale Inactive for 40 days label Jun 17, 2025

mamoodi closed this Jul 18, 2025

	OpenHands supports two authentication methods for Azure OpenAI:
	OpenHands supports the following authentication methods for Azure OpenAI:

	### 2. Azure AD Token Authentication
	### Azure AD Token Authentication

docs: improve Azure OpenAI integration documentation #8499

docs: improve Azure OpenAI integration documentation #8499

Uh oh!

Conversation

vbs-0 commented May 14, 2025

Description

Changes Made

Changelog Message

Type of Change

Testing Done

Related Issues

Additional Notes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pcuci left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jun 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mamoodi commented Jul 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants