Azure Functions Integration for Microsoft Agent Framework

Common errors

• Could not find agent with name and version number

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

• ValueError: Toolset is not available in the client.

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

• HttpResponseError: (None) Invalid tool value(s): azure_function.

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

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• breaking The method for constructing `Message` objects in the core `agent-framework` has changed. Direct use of `Message(role="user", text="Hello")` is deprecated.
  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.
• gotcha 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.
  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`.
• gotcha 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.
  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.

Install

• pip install agent-framework-azurefunctions --pre Install latest beta version

Imports

• AgentFunctionApp

  from agent_framework.azure import AgentFunctionApp

  Main class for registering agents with Azure Functions.
• AzureOpenAIChatClient

  from agent_framework.azure import AzureOpenAIChatClient

  Client for interacting with Azure OpenAI chat models.
• AzureCliCredential

  from azure.identity import AzureCliCredential

  Credential for authenticating via Azure CLI.

Quickstart

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.

import os
from agent_framework.azure import AgentFunctionApp, AzureOpenAIChatClient
from azure.identity import AzureCliCredential

# Ensure environment variables are set for local execution/testing
os.environ['AZURE_OPENAI_ENDPOINT'] = os.environ.get('AZURE_OPENAI_ENDPOINT', 'https://your-resource.openai.azure.com/')
os.environ['AZURE_OPENAI_CHAT_DEPLOYMENT_NAME'] = os.environ.get('AZURE_OPENAI_CHAT_DEPLOYMENT_NAME', 'gpt-4o-mini')

# You might need to set up 'DURABLE_TASK_SCHEDULER_CONNECTION_STRING' and 'TASKHUB_NAME' 
# in local.settings.json or environment variables for Durable Functions. 
# For local development with Azurite and Durable Task Emulator, you'd typically have:
# DURABLE_TASK_SCHEDULER_CONNECTION_STRING='Endpoint=http://localhost:8080;TaskHub=default;Authentication=None'
# TASKHUB_NAME='default'
# AzureWebJobsStorage='UseDevelopmentStorage=true'

# Create an Azure OpenAI client
# For production, consider DefaultAzureCredential or ManagedIdentityCredential
client = AzureOpenAIChatClient(credential=AzureCliCredential())

# Create an agent
agent = client.as_agent(
    name="Assistant",
    instructions="You are a helpful assistant."
)

# Register the agent with the Functions app
# This creates the necessary HTTP endpoints and durable entities.
# For a real Azure Function app, this file would typically be named 'function_app.py'
# and would be discovered by the Azure Functions runtime.
app = AgentFunctionApp(agents=[agent], enable_health_check=True)

# To run this locally, you would typically use Azure Functions Core Tools:
# 1. Install Azure Functions Core Tools (npm install -g azure-functions-core-tools@4 --unsafe-perm true)
# 2. In your project directory, create local.settings.json and host.json as described in the documentation.
# 3. Start Azurite and Durable Task Emulator (e.g., via `azd env up` or manually)
# 4. Run `func start` in your terminal.

# The agent's HTTP endpoint would then be available at /api/agents/Assistant/run
# This quickstart code itself doesn't start the Azure Functions host, it defines the app.