mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Eduard van Valkenburg
cc0cfaaac8
* Python: fix OpenAI Azure routing and provider samples Prefer OpenAI when OPENAI_API_KEY is present unless Azure is explicitly requested. Clarify constructor docs, keep deprecated Azure wrappers compatible with stricter settings validation, and refresh the provider samples and tests to use the current client patterns. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix bandit * Python: align OpenAI embedding Azure routing Extend the shared OpenAI-vs-Azure routing and credential behavior to the embedding client, add Azure embedding regression coverage, and refresh the embedding samples to use the generic client path. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: fix embedding client pyright check Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: thin OpenAI embedding wrapper Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: document embedding overload routing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: fix callable OpenAI key routing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: fix Azure credential routing tests Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: address OpenAI review feedback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: narrow Azure routing markers Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: refine OpenAI model fallback order Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: narrow Azure deployment docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: remove embedding routing wording Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: run embedding Azure integration tests Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * changed variable name * Python: expand OpenAI package README Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * clarified readme * Python: fix Azure OpenAI integration setup Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: correct Azure integration env mapping Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * updated code to fix int tests * test updates * test fix * fix test setup * updates to tests and setup * remove openai assistants int tests * improvements in int tests * fix env var * fix env vars * fix azure responses test * trigger actions --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
107 lines
3.5 KiB
Markdown
107 lines
3.5 KiB
Markdown
# agent-framework-openai
|
|
|
|
OpenAI integration for Microsoft Agent Framework.
|
|
|
|
This package provides:
|
|
|
|
- `OpenAIChatClient` for the OpenAI Responses API
|
|
- `OpenAIChatCompletionClient` for the Chat Completions API
|
|
- `OpenAIEmbeddingClient` for embeddings
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install agent-framework-openai --pre
|
|
```
|
|
|
|
## Which chat client should I use?
|
|
|
|
Use `OpenAIChatClient` for new work unless you specifically need the Chat Completions API.
|
|
|
|
- `OpenAIChatClient` uses the Responses API and is the preferred general-purpose chat client.
|
|
- `OpenAIChatCompletionClient` uses the Chat Completions API and is mainly for compatibility with
|
|
existing Chat Completions-based integrations.
|
|
|
|
The deprecated `OpenAIResponsesClient` alias points to `OpenAIChatClient`.
|
|
|
|
## Environment variables
|
|
|
|
### OpenAI
|
|
|
|
These variables are used when the client is configured for OpenAI:
|
|
|
|
| Variable | Purpose |
|
|
| --- | --- |
|
|
| `OPENAI_API_KEY` | OpenAI API key |
|
|
| `OPENAI_ORG_ID` | OpenAI organization ID |
|
|
| `OPENAI_BASE_URL` | Custom OpenAI-compatible base URL |
|
|
| `OPENAI_MODEL` | Generic fallback model |
|
|
| `OPENAI_RESPONSES_MODEL` | Preferred model for `OpenAIChatClient` |
|
|
| `OPENAI_CHAT_MODEL` | Preferred model for `OpenAIChatCompletionClient` |
|
|
| `OPENAI_EMBEDDING_MODEL` | Preferred model for `OpenAIEmbeddingClient` |
|
|
|
|
Model lookup order:
|
|
|
|
- `OpenAIChatClient`: `OPENAI_RESPONSES_MODEL` -> `OPENAI_MODEL`
|
|
- `OpenAIChatCompletionClient`: `OPENAI_CHAT_MODEL` -> `OPENAI_MODEL`
|
|
- `OpenAIEmbeddingClient`: `OPENAI_EMBEDDING_MODEL` -> `OPENAI_MODEL`
|
|
|
|
### Azure OpenAI
|
|
|
|
These variables are used when the client is configured for Azure OpenAI:
|
|
|
|
| Variable | Purpose |
|
|
| --- | --- |
|
|
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI resource endpoint |
|
|
| `AZURE_OPENAI_BASE_URL` | Full Azure OpenAI base URL (`.../openai/v1`) |
|
|
| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key |
|
|
| `AZURE_OPENAI_API_VERSION` | Azure OpenAI API version |
|
|
| `AZURE_OPENAI_DEPLOYMENT_NAME` | Generic fallback deployment |
|
|
| `AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME` | Preferred deployment for `OpenAIChatClient` |
|
|
| `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME` | Preferred deployment for `OpenAIChatCompletionClient` |
|
|
| `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME` | Preferred deployment for `OpenAIEmbeddingClient` |
|
|
|
|
Deployment lookup order:
|
|
|
|
- `OpenAIChatClient`: `AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME` -> `AZURE_OPENAI_DEPLOYMENT_NAME`
|
|
- `OpenAIChatCompletionClient`: `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME` -> `AZURE_OPENAI_DEPLOYMENT_NAME`
|
|
- `OpenAIEmbeddingClient`: `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME` -> `AZURE_OPENAI_DEPLOYMENT_NAME`
|
|
|
|
When both OpenAI and Azure environment variables are present, the generic clients prefer OpenAI
|
|
when `OPENAI_API_KEY` is configured. To use Azure explicitly, pass `azure_endpoint` or
|
|
`credential`.
|
|
|
|
## OpenAI example
|
|
|
|
```python
|
|
from agent_framework.openai import OpenAIChatClient
|
|
|
|
client = OpenAIChatClient(model="gpt-4.1")
|
|
```
|
|
|
|
## Azure OpenAI example
|
|
|
|
```python
|
|
from azure.identity.aio import AzureCliCredential
|
|
|
|
from agent_framework.openai import OpenAIChatClient
|
|
|
|
client = OpenAIChatClient(
|
|
model="my-responses-deployment",
|
|
azure_endpoint="https://my-resource.openai.azure.com",
|
|
credential=AzureCliCredential(),
|
|
)
|
|
```
|
|
|
|
## ChatClient vs ChatCompletionClient
|
|
|
|
Use `OpenAIChatClient` when you want the Responses API as your default chat surface.
|
|
|
|
Use `OpenAIChatCompletionClient` when you specifically need the Chat Completions API:
|
|
|
|
```python
|
|
from agent_framework.openai import OpenAIChatCompletionClient
|
|
|
|
client = OpenAIChatCompletionClient(model="gpt-4o-mini")
|
|
```
|