diff --git a/README.md b/README.md index e5819bb0..81770d2c 100644 --- a/README.md +++ b/README.md @@ -29,21 +29,17 @@ azurefunctions-agents-runtime ## Model Provider Configuration -The runtime uses Microsoft Agent Framework, which supports OpenAI, Azure OpenAI, and Microsoft Foundry as inference back-ends. Auto-detection picks the first provider whose env vars are set, in this order: +The runtime uses Microsoft Agent Framework, which supports Microsoft Foundry, Azure OpenAI, and OpenAI as inference back-ends. The public preview quickstart and samples use **Microsoft Foundry** as the primary path, pinned with `MAF_PROVIDER=foundry`. -1. `AZURE_OPENAI_ENDPOINT` → Azure OpenAI -2. `FOUNDRY_PROJECT_ENDPOINT` → Microsoft Foundry -3. `OPENAI_API_KEY` → OpenAI +| Provider | `MAF_PROVIDER` | Required env vars | Notes | +| --- | --- | --- | --- | +| Microsoft Foundry | `foundry` | `FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL` | Recommended quickstart/sample path. Uses `DefaultAzureCredential`; run `az login` locally and set `AZURE_CLIENT_ID` in multi-identity Function Apps. | +| Azure OpenAI | `azure_openai` | `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT`, optional `AZURE_OPENAI_API_VERSION` | Alternative Azure-hosted provider. `AZURE_OPENAI_DEPLOYMENT` takes precedence over `MAF_MODEL`. If `AZURE_OPENAI_API_KEY` is omitted the SDK uses `DefaultAzureCredential` (AAD). | +| OpenAI | `openai` | `OPENAI_API_KEY`, optional `MAF_MODEL` (default `gpt-4o-mini`) | Alternative non-Azure provider. `MAF_MODEL` applies directly for OpenAI. | -You can pin the provider explicitly with `MAF_PROVIDER=openai|azure_openai|foundry`. +If `MAF_PROVIDER` is unset, auto-detection picks the first provider whose env vars are set, in this order: `AZURE_OPENAI_ENDPOINT` → `FOUNDRY_PROJECT_ENDPOINT` → `OPENAI_API_KEY`. Set `MAF_PROVIDER` to make the provider choice intentional. -| Provider | Required env vars | Notes | -| ----------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| OpenAI | `OPENAI_API_KEY`, optional `MAF_MODEL` (default `gpt-4o-mini`) | `MAF_MODEL` applies directly for OpenAI. | -| Azure OpenAI | `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT`, optional `AZURE_OPENAI_API_VERSION` | `AZURE_OPENAI_DEPLOYMENT` takes precedence over `MAF_MODEL`. If `AZURE_OPENAI_API_KEY` is omitted the SDK uses `DefaultAzureCredential` (AAD); set `AZURE_CLIENT_ID` in multi-identity Function Apps. | -| Microsoft Foundry | `FOUNDRY_PROJECT_ENDPOINT`, optional `FOUNDRY_MODEL` | `FOUNDRY_MODEL` takes precedence over `MAF_MODEL`. Uses `DefaultAzureCredential`; set `AZURE_CLIENT_ID` in multi-identity Function Apps. | - -Model resolution precedence is: explicit requested model > provider-specific env (`AZURE_OPENAI_DEPLOYMENT` for Azure OpenAI, `FOUNDRY_MODEL` for Foundry) > `MAF_MODEL` > provider default. +Model resolution precedence is: explicit requested model > provider-specific env (`FOUNDRY_MODEL` for Foundry, `AZURE_OPENAI_DEPLOYMENT` for Azure OpenAI) > `MAF_MODEL` > provider default. ## Quick Start @@ -72,7 +68,15 @@ app = create_function_app() > The app root is auto-detected from `AzureWebJobsScriptRoot` (set by `func start` and the Azure Functions host). You can override it with `create_function_app(app_root=Path(__file__).parent)` or the `AZURE_FUNCTIONS_AGENTS_APP_ROOT` env var. -### 3. Create `host.json` +### 3. Create `agents.config.yaml` + +```yaml +# Default runtime configuration +model: $FOUNDRY_MODEL +timeout: 900 +``` + +### 4. Create `host.json` ```json { @@ -89,7 +93,7 @@ app = create_function_app() } ``` -### 4. Create `requirements.txt` +### 5. Create `requirements.txt` ``` azurefunctions-agents-runtime @@ -97,9 +101,9 @@ azurefunctions-agents-runtime Connector-backed tools are exposed through MCP servers in `mcp.json`, and connector-triggered apps use the Azure Functions Connector Extension through the Functions extension bundle. No package extra is required. -### 5. Set the model provider +### 6. Set the model provider -For local development with OpenAI: +For local development with Microsoft Foundry, sign in with `az login`, then create `local.settings.json`: ```json { @@ -107,13 +111,14 @@ For local development with OpenAI: "Values": { "FUNCTIONS_WORKER_RUNTIME": "python", "AzureWebJobsStorage": "UseDevelopmentStorage=true", - "OPENAI_API_KEY": "sk-...", - "MAF_MODEL": "gpt-4o-mini" + "MAF_PROVIDER": "foundry", + "FOUNDRY_PROJECT_ENDPOINT": "https://..services.ai.azure.com/api/projects/", + "FOUNDRY_MODEL": "gpt-5.4" } } ``` -### 6. Start Azurite (local storage emulator) +### 7. Start Azurite (local storage emulator) The MCP server endpoint and non-HTTP triggers (timer, queue, blob, etc.) require a storage account. Locally, use [Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite) via Docker: @@ -123,7 +128,7 @@ docker run -d --name azurite -p 10000:10000 -p 10001:10001 -p 10002:10002 \ azurite --skipApiVersionCheck --blobHost 0.0.0.0 --queueHost 0.0.0.0 --tableHost 0.0.0.0 ``` -### 7. Run locally +### 8. Run locally ```bash func start @@ -436,7 +441,7 @@ See the [`samples/`](samples/) directory for complete, deployable example apps: ### Required Azure App Settings -Set the model provider env vars described above (e.g. `OPENAI_API_KEY` and `MAF_MODEL`, `AZURE_OPENAI_ENDPOINT` + `AZURE_OPENAI_DEPLOYMENT`, or `FOUNDRY_PROJECT_ENDPOINT` + `FOUNDRY_MODEL`). For Azure OpenAI and Microsoft Foundry, the provider-specific deployment/model setting takes precedence over `MAF_MODEL`. +Set the model provider env vars described above. The preview samples use Microsoft Foundry (`MAF_PROVIDER=foundry`, `FOUNDRY_PROJECT_ENDPOINT`, and `FOUNDRY_MODEL`). Azure OpenAI (`AZURE_OPENAI_ENDPOINT` + `AZURE_OPENAI_DEPLOYMENT`) and OpenAI (`OPENAI_API_KEY` and optionally `MAF_MODEL`) are supported alternatives. For Microsoft Foundry and Azure OpenAI, the provider-specific model/deployment setting takes precedence over `MAF_MODEL`. When the agent uses connector-backed MCP servers, connector triggers, or `execution_sandbox`, the function app's **system-assigned or user-assigned Managed Identity** must be enabled and granted access to the target resource — otherwise `DefaultAzureCredential` will fail to obtain a token. In multi-identity Function Apps, set `AZURE_CLIENT_ID` so the runtime uses the intended managed identity for Azure OpenAI, Foundry, blob-backed session storage, ACA Dynamic Sessions, and ARM/data-plane connector calls. For an individual MCP server, set `auth.client_id` in `mcp.json` to choose a different managed identity just for that server. diff --git a/samples/README.md b/samples/README.md index 01efac57..760e2692 100644 --- a/samples/README.md +++ b/samples/README.md @@ -19,7 +19,7 @@ If you would instead prefer to run locally (for local development, testing, etc. - [Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local) - Python 3.13+ -- an OpenAI API key (https://platform.openai.com/api-keys) +- Azure credentials with access to a Microsoft Foundry project (`az login`) - (Optional) [Azurite](https://learn.microsoft.com/azure/storage/common/storage-use-azurite) for local storage emulation ### 1. Install dependencies @@ -64,17 +64,17 @@ Edit `local.settings.json` and set the required values. See each sample's README **Model provider (required for all samples):** -The Microsoft Agent Framework supports Azure OpenAI, OpenAI, and Microsoft Foundry. The samples default to Azure OpenAI. +The Microsoft Agent Framework supports Microsoft Foundry, Azure OpenAI, and OpenAI. The samples default to Microsoft Foundry and their templates pin `MAF_PROVIDER` to `foundry`. -| Provider | `MAF_PROVIDER` | Required env vars | -| -------------- | --------------- | ---------------------------------------------------------------------------------- | -| Azure OpenAI | `azure_openai` | `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT` (uses `DefaultAzureCredential`) | -| OpenAI | `openai` | `OPENAI_API_KEY` | -| Microsoft Foundry | `foundry` | `FOUNDRY_PROJECT_ENDPOINT` (uses `DefaultAzureCredential`) | +| Provider | `MAF_PROVIDER` | Required env vars | +| --- | --- | --- | +| Microsoft Foundry | `foundry` | `FOUNDRY_PROJECT_ENDPOINT`, `FOUNDRY_MODEL` (uses `DefaultAzureCredential`) | +| Azure OpenAI | `azure_openai` | `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT` (uses `DefaultAzureCredential` unless an API key is set) | +| OpenAI | `openai` | `OPENAI_API_KEY`, optional `MAF_MODEL` | -If `MAF_PROVIDER` is unset, the runtime auto-detects in this order: `AZURE_OPENAI_ENDPOINT` → `FOUNDRY_PROJECT_ENDPOINT` → `OPENAI_API_KEY`. +For Foundry, set `FOUNDRY_PROJECT_ENDPOINT` to your project endpoint and `FOUNDRY_MODEL` to your model deployment name (for example, `gpt-5.4`). Authentication uses `DefaultAzureCredential` — run `az login` locally. -For Azure OpenAI, set `AZURE_OPENAI_ENDPOINT` to your resource endpoint (e.g. `https://.openai.azure.com/`) and `AZURE_OPENAI_DEPLOYMENT` to your model deployment name (e.g. `gpt-5.2`). Authentication uses `DefaultAzureCredential` — run `az login` locally. +OpenAI and Azure OpenAI remain supported alternatives. If you switch providers, update `MAF_PROVIDER` and the provider-specific settings in `local.settings.json`; if `MAF_PROVIDER` is unset, the runtime auto-detects in this order: `AZURE_OPENAI_ENDPOINT` → `FOUNDRY_PROJECT_ENDPOINT` → `OPENAI_API_KEY`. **Sample-specific variables:**