{"id":6954,"library":"agent-framework-azurefunctions","title":"Azure Functions Integration for Microsoft Agent Framework","description":"agent-framework-azurefunctions is a Python library that enables hosting Microsoft Agent Framework agents on Azure Durable Functions. It provides capabilities for agents to persist state, replay conversation history, and automatically recover from failures. Currently, the library is in a beta status (version 1.0.0b260409) and is actively developed as part of the broader Microsoft Agent Framework ecosystem.","status":"active","version":"1.0.0b260409","language":"en","source_language":"en","source_url":"https://github.com/microsoft/agent-framework","tags":["AI Agents","Azure Functions","Serverless","Microsoft Agent Framework","Durable Functions","Python"],"install":[{"cmd":"pip install agent-framework-azurefunctions --pre","lang":"bash","label":"Install latest beta version"}],"dependencies":[{"reason":"Required to run Azure Functions locally and deploy to Azure.","package":"Azure Functions Core Tools","optional":false},{"reason":"Core components of the Microsoft Agent Framework that this library extends.","package":"agent-framework","optional":false},{"reason":"Used for authenticating with Azure services, such as Azure OpenAI.","package":"azure-identity","optional":false}],"imports":[{"note":"Main class for registering agents with Azure Functions.","symbol":"AgentFunctionApp","correct":"from agent_framework.azure import AgentFunctionApp"},{"note":"Client for interacting with Azure OpenAI chat models.","symbol":"AzureOpenAIChatClient","correct":"from agent_framework.azure import AzureOpenAIChatClient"},{"note":"Credential for authenticating via Azure CLI.","symbol":"AzureCliCredential","correct":"from azure.identity import AzureCliCredential"}],"quickstart":{"code":"import os\nfrom agent_framework.azure import AgentFunctionApp, AzureOpenAIChatClient\nfrom azure.identity import AzureCliCredential\n\n# Ensure environment variables are set for local execution/testing\nos.environ['AZURE_OPENAI_ENDPOINT'] = os.environ.get('AZURE_OPENAI_ENDPOINT', 'https://your-resource.openai.azure.com/')\nos.environ['AZURE_OPENAI_CHAT_DEPLOYMENT_NAME'] = os.environ.get('AZURE_OPENAI_CHAT_DEPLOYMENT_NAME', 'gpt-4o-mini')\n\n# You might need to set up 'DURABLE_TASK_SCHEDULER_CONNECTION_STRING' and 'TASKHUB_NAME' \n# in local.settings.json or environment variables for Durable Functions. \n# For local development with Azurite and Durable Task Emulator, you'd typically have:\n# DURABLE_TASK_SCHEDULER_CONNECTION_STRING='Endpoint=http://localhost:8080;TaskHub=default;Authentication=None'\n# TASKHUB_NAME='default'\n# AzureWebJobsStorage='UseDevelopmentStorage=true'\n\n# Create an Azure OpenAI client\n# For production, consider DefaultAzureCredential or ManagedIdentityCredential\nclient = AzureOpenAIChatClient(credential=AzureCliCredential())\n\n# Create an agent\nagent = client.as_agent(\n    name=\"Assistant\",\n    instructions=\"You are a helpful assistant.\"\n)\n\n# Register the agent with the Functions app\n# This creates the necessary HTTP endpoints and durable entities.\n# For a real Azure Function app, this file would typically be named 'function_app.py'\n# and would be discovered by the Azure Functions runtime.\napp = AgentFunctionApp(agents=[agent], enable_health_check=True)\n\n# To run this locally, you would typically use Azure Functions Core Tools:\n# 1. Install Azure Functions Core Tools (npm install -g azure-functions-core-tools@4 --unsafe-perm true)\n# 2. In your project directory, create local.settings.json and host.json as described in the documentation.\n# 3. Start Azurite and Durable Task Emulator (e.g., via `azd env up` or manually)\n# 4. Run `func start` in your terminal.\n\n# The agent's HTTP endpoint would then be available at /api/agents/Assistant/run\n# This quickstart code itself doesn't start the Azure Functions host, it defines the app.","lang":"python","description":"This quickstart demonstrates how to define an `AgentFunctionApp` and register a simple AI agent powered by Azure OpenAI. To run this, you need Azure Functions Core Tools, a `local.settings.json` file for environment variables (including `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`, `AzureWebJobsStorage`, `DURABLE_TASK_SCHEDULER_CONNECTION_STRING`, `TASKHUB_NAME`), and a `host.json` for extension bundle configuration. The code configures an `AgentFunctionApp` which will be picked up by the Azure Functions runtime when deployed or run locally."},"warnings":[{"fix":"Always refer to the latest documentation and release notes before upgrading. Plan for potential code adjustments when updating to new beta versions or the eventual GA release.","message":"The `agent-framework-azurefunctions` package is currently in beta. While the core `agent-framework` has reached 1.0.0 General Availability, this specific integration is still under active development, and future updates may introduce breaking changes to its API or behavior.","severity":"breaking","affected_versions":"1.0.0b*"},{"fix":"Migrate agent creation and interaction logic to use `agent-framework-foundry` for Azure AI Foundry integrations. Review the official migration guides for detailed steps on adapting to the new provider-leading client design and package structure. Generic OpenAI clients now require explicit Azure routing signals (`credential` or `azure_endpoint`) if `OPENAI_API_KEY` is also set, otherwise they might default to non-Azure OpenAI.","message":"The Microsoft Agent Framework, including its Azure integrations, underwent a significant architectural shift with the 1.0.0 release. The `agent-framework-azure-ai` package was deprecated, and its functionality for Python embeddings and model-endpoint settings moved to `agent-framework-foundry`. Additionally, the framework shifted to a 'provider-leading client design', emphasizing connecting to pre-configured agents in Azure AI Foundry rather than creating them via older provider patterns.","severity":"breaking","affected_versions":"Prior to 1.0.0 and subsequent beta releases"},{"fix":"Construct text messages using `Message(role=\"user\", contents=[\"Hello\"])` instead. This applies anywhere you directly construct messages, including workflows, custom middleware, and orchestration helpers.","message":"The method for constructing `Message` objects in the core `agent-framework` has changed. Direct use of `Message(role=\"user\", text=\"Hello\")` is deprecated.","severity":"breaking","affected_versions":"agent-framework < 1.0.0, indirectly affecting agent-framework-azurefunctions users"},{"fix":"Ensure `npm install -g azure-functions-core-tools@4 --unsafe-perm true` is run. Use `azd env up` or manually start Azurite and the DTS emulator, and configure `local.settings.json` with `AzureWebJobsStorage`, `DURABLE_TASK_SCHEDULER_CONNECTION_STRING`, and `TASKHUB_NAME`.","message":"Running Durable Agent Functions locally requires specific local development dependencies: Azure Functions Core Tools, Azurite (for Azure Storage emulation), and the Durable Task Scheduler (DTS) emulator.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor detailed logs from the Azure Function host (e.g., in Application Insights or local console output) for actual error messages. Do not solely rely on the HTTP response status for definitive success/failure of durable agent runs.","message":"Durable Agent Run failures may incorrectly report a 'success' status in the HTTP response, even if an underlying error (e.g., 404 from OpenAI service) occurred.","severity":"gotcha","affected_versions":"Undetermined beta versions (observed in issue reports)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your agent is explicitly deployed and provisioned in your Azure AI Foundry project (`client.create_agent(...)` and wait for `provisioningState == 'Succeeded'`). Verify that the agent name and version in `get_agent(\"MyAgent\", \"1.0.0\")` precisely match the registered agent. Double-check your `local.settings.json` and environment variables, especially `PROJECT_CONNECTION_STRING`, which needs to point to the correct AI project.","cause":"The agent was not pre-created or registered in your Azure AI Foundry project, or there's a mismatch in the agent's name/version between your code and the registered agent, or `PROJECT_CONNECTION_STRING` environment variable is incorrectly configured.","error":"Could not find agent with name and version number"},{"fix":"Instead of importing a pre-built `ToolSet` object, import the individual functions into the file where the agent is initialized. Then, construct the `FunctionTool` and `ToolSet` instances in the same file where you create the agent. Alternatively, implement a factory function in your tools module that returns the `ToolSet`, and call this factory function in your agent definition file.","cause":"This typically occurs when defining custom `FunctionTool` objects or `ToolSet` instances in one Python module and importing them into another module where the agent is created. The Azure AI client performs runtime validation on the toolset and expects live function references in the current execution context, which can be broken by cross-module imports of pre-built toolset objects.","error":"ValueError: Toolset is not available in the client."},{"fix":"Verify that your Azure Function tool configuration aligns with the SDK's `Function Tool Specifications`. Ensure that the Azure Function is properly deployed with the expected trigger type (e.g., a Queue trigger for non-streaming scenarios) and that its name and parameters match the agent's tool definition precisely.","cause":"This error indicates an issue with how an Azure Function is configured as a tool for the agent. This might be due to incorrect tool specifications or not meeting the SDK's requirements, such as expecting queue triggers for non-streaming scenarios.","error":"HttpResponseError: (None) Invalid tool value(s): azure_function."}]}