Issue with Integrating Azure Function into AI Foundry Agent — Role and Requirement of Capability Host

Question

Issue with Integrating Azure Function into AI Foundry Agent — Role and Requirement of Capability Host

Mian Omair 0

Background and Objective:

I am building an AI Agent in Azure AI Foundry which needs to invoke an Azure Function dynamically during conversations.

Example Scenario: A user asks about weather information → the agent triggers an Azure Function ("GetWeather") → the function processes the request and returns results.

This example is simplified but meant to understand the full production-grade process of connecting Azure Functions as callable tools inside AI Foundry Agents.

Steps Taken:

Using the Python SDK (azure-ai-projects), I tried defining an agent with a tool of type azure_function.

The tool definition binds the Azure Function via Storage Queue input and output bindings (no HTTP trigger for now).

Attempted agent creation with this tool specified.

Problem Encountered:

While creating the agent, I get this error:

azure.core.exceptions.HttpResponseError: (None) Invalid tool value(s): azure_function
Code: None
Message: Invalid tool value(s): azure_function

This suggests that azure_function tool type is not directly accepted unless further setup is done.

Investigation and Current Understanding:

From documentation and forums, I learned about Capability Hosts, a new experimental concept in Azure ML and AI Foundry:

Capability Hosts seem to act as a bridge layer, allowing agents to interact with external resources like Functions, Storage, Databases, etc.

It is mentioned that certain tools like azure_function, storage_blob, etc., require an active Capability Host.

I attempted to create a Capability Host using the CLI (az ml capability-host create) but ran into YAML validation errors (specifically around connections field not being recognized).

Structured Questions Needing Clarification:

High-Level Flow

What is the full end-to-end process required to enable an AI Foundry Agent to invoke an Azure Function? (From agent creation, linking external resources, to actual runtime invocation)

Necessity of Capability Host

Is creating a Capability Host mandatory to allow an agent to use a tool of type azure_function?

If yes, what components need to be part of a Capability Host?

If no, is there an alternative simpler mechanism when using Storage Queue-based bindings only?

Role and Significance of Capability Host

What exactly does a Capability Host do?

Does it merely act as a credential and connection broker?

Does it also route execution requests dynamically to registered resources?

Correct Capability Host Definition

What is the correct YAML structure to create a Capability Host that supports Azure Function tool execution? (Especially since the error I encountered suggests my YAML is invalid around connections field)

Example of error faced:

Validation for CapabilityHostSchema failed:
{
  "connections": [
    "Unknown field."
  ]
}

My original capabilityhost.yml:

name: mg-voice-agent-capability-host
description: Capability host for MG AI voice agent project
connections:
  ai_services_connections:
    - mgaiagentshub17057533407_aoai
  storage_connections:
    - MG-AI-AGENTS-PROJECT-1/workspaceblobstore

Portal / UI Options

Is there a way to create and manage Capability Hosts via the Azure Portal or Azure ML Studio interface instead of CLI and YAML? (If yes, where exactly?)

✅ Summary: I want to create an AI agent that can call an Azure Function, understand whether Capability Host is mandatory, how to correctly define and configure it and how the agent-resource interaction is established.

Mian Omair 0

Following is the code for reference:

python
CopyEdit
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import ToolResources
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

# Get connection strings from environment variables
project_connection_string = os.getenv("PROJECT_CONNECTION_STRING")
storage_connection_string = os.getenv("STORAGE_CONNECTION_STRING")

# Validate required environment variables
if not project_connection_string:
    raise ValueError("PROJECT_CONNECTION_STRING is missing.")
if not storage_connection_string:
    raise ValueError("STORAGE_CONNECTION_STRING is missing.")

# Initialize AI Project Client
project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=project_connection_string,
)

# Empty ToolResources (no additional resources registered yet)
empty_tool_resources = ToolResources()

# Define the Azure Function tool using storage queues for input and output
tools = [
    {
        "type": "azure_function",
        "azure_function": {
            "function": {
                "name": "GetWeather",
                "description": "Retrieve the weather details for a specific location.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "City or place name to get weather information."
                        }
                    },
                    "required": ["location"]
                }
            },
            "input_binding": {
                "type": "storage_queue",
                "storage_queue": {
                    "queue_service_uri": storage_connection_string,
                    "queue_name": "getweather-input"
                }
            },
            "output_binding": {
                "type": "storage_queue",
                "storage_queue": {
                    "queue_service_uri": storage_connection_string,
                    "queue_name": "getweather-output"
                }
            }
        }
    }
]

# Attempt to create the AI Agent
try:
    agent = project_client.agents.create_agent(
        model="gpt-4o-mini",
        name="azure-function-agent-single-getweather",
        instructions="You are a weather assistant. When a user asks about the weather, call the GetWeather function.",
        headers={"x-ms-enable-preview": "true"},  # Required for experimental tool types
        tools=tools,
        tool_resources=empty_tool_resources,
    )
    print(f"✅ Agent created successfully: {agent.name} (ID: {agent.id})")

except Exception as e:
    print("❌ Failed to create agent.")
    print(e)

Manas Mohanty 3,210 Reputation points Microsoft External Staff

2025-04-28T12:12:59.2233333+00:00
Hi Mian Omair

As per Azure function usage documentation, I could not find mention of Capability Hosts. It would be great if you can share relevant threads mentioning them as requirement.

Anomaly found in above code at my side was usage of tool_resource while creating the client.

tool_resources=empty_tool_resources,

in Agent creation

As pre-requisite mentioned in above doc., we need models which were released after November 6, 2023.

I am also doing minimal repro at my side and connecting with team internally on this.

Thank you for your patience.
Manas Mohanty 3,210 Reputation points Microsoft External Staff

2025-04-28T14:22:08.2233333+00:00
Hi Mian Omair

I am able to replicate below error from default documentation usage and checking with team internally on it.

Code: None Message: Invalid tool value(s): azure_function

Thank you.
Manas Mohanty 3,210 Reputation points Microsoft External Staff

2025-04-28T16:02:01.6733333+00:00
Hi Mian Omair

Could you use them as extra params in below command and let us know.

az ml capability-host create --name my-host-name --resource-group my-resource-group --workspace-name my-workspace

Thank you
Mian Omair 0 Reputation points

2025-04-28T19:40:10.0266667+00:00
Hi Manas Mohanty,

I have already tried several potential approaches for creating OpenAI service connections, including defining them in a YAML file and manually passing them through the command line, but none of them worked.

Try 1: az ml capability-host create --name my-host-name --resource-group my-resource-group --workspace-name my-workspaceCommand group 'ml capability-host' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Class CapabilityHostSchema: This is an experimental class, and may change at any time. Please see https://aka.ms/azuremlexperimental for more information.

Class CapabilityHost: This is an experimental class, and may change at any time. Please see https://aka.ms/azuremlexperimental for more information.

Method capability_hosts: This is an experimental method, and may change at any time. Please see https://aka.ms/azuremlexperimental for more information.

Method begin_create_or_update: This is an experimental method, and may change at any time. Please see https://aka.ms/azuremlexperimental for more information.

*For Project workspace kind, OpenAI service connections are required.

Try 2: az ml capability-host create --name mg-voice-agent-capability-host --resource-group MG-AI-VOICE-AGENT --workspace-name MG-AI-AGENTS-PROJECT-1 --ai-services-connections my openai-service*

Command group 'ml capability-host' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Class CapabilityHostSchema: This is an experimental class, and may change at any time. Please see https://aka.ms/azuremlexperimental for more information.

The command failed with an unexpected error. Here is the traceback:

Validation for CapabilityHostSchema failed:

{

"ai_services_connections": [

*"Not a valid list."*

]

}

The easiest way to author a specification file is using IntelliSense and auto-completion Azure ML VS code extension provides: https://code.visualstudio.com/docs/datascience/azure-machine-learning. To set up: https://learn.microsoft.com/azure/machine-learning/how-to-setup-vs-code

Traceback (most recent call last):

File "/home/zubair-ashfaque/.azure/cliextensions/ml/azext_mlv2/manual/vendored_curated_sdk/azure/ai/ml/entities/_util.py", line 192, in load_from_dict

*return schema(context=context).load(data, **kwargs)* *^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*

File "/home/zubair-ashfaque/.azure/cliextensions/ml/marshmallow/schema.py", line 792, in load

*return self._do_load(* *^^^^^^^^^^^^^^*

File "/home/zubair-ashfaque/.azure/cliextensions/ml/marshmallow/schema.py", line 999, in _do_load

*raise exc*

marshmallow.exceptions.ValidationError: {'ai_services_connections': ['Not a valid list.']}

The above exception was the direct cause of the following exception:

Traceback (most recent call last):

File "/opt/az/lib/python3.12/site-packages/knack/cli.py", line 233, in invoke

*cmd_result = self.invocation.execute(args)* *^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*

File "/opt/az/lib/python3.12/site-packages/azure/cli/core/commands/init.py", line 666, in execute

*raise ex*

File "/opt/az/lib/python3.12/site-packages/azure/cli/core/commands/init.py", line 734, in _run_jobs_serially

*results.append(self._run_job(expanded_arg, cmd_copy))* *^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*

File "/opt/az/lib/python3.12/site-packages/azure/cli/core/commands/init.py", line 703, in _run_job

*result = cmd_copy(params)* *^^^^^^^^^^^^^^^^*

File "/opt/az/lib/python3.12/site-packages/azure/cli/core/commands/init.py", line 336, in call

*return self.handler(*args, **kwargs)* *^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*

File "/opt/az/lib/python3.12/site-packages/azure/cli/core/commands/command_operation.py", line 120, in handler

*return op(**command_args)* *^^^^^^^^^^^^^^^^^^*

File "/home/zubair-ashfaque/.azure/cliextensions/ml/azext_mlv2/manual/custom/capability_host.py", line 85, in ml_capability_host_create

*log_and_raise_error(err, debug, yaml_operation=yaml_operation)*

File "/home/zubair-ashfaque/.azure/cliextensions/ml/azext_mlv2/manual/custom/raise_error.py", line 185, in log_and_raise_error

*raise cli_error*

File "/home/zubair-ashfaque/.azure/cliextensions/ml/azext_mlv2/manual/custom/capability_host.py", line 68, in ml_capability_host_create

*capability_host = load_capability_host(* *^^^^^^^^^^^^^^^^^^^^^*

File "/home/zubair-ashfaque/.azure/cliextensions/ml/azext_mlv2/manual/vendored_curated_sdk/azure/ai/ml/entities/_load_functions.py", line 1103, in load_capability_host

*return cast(CapabilityHost, load_common(CapabilityHost, source, relative_origin, params_override, **kwargs))* *^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*

File "/home/zubair-ashfaque/.azure/cliextensions/ml/azext_mlv2/manual/vendored_curated_sdk/azure/ai/ml/entities/_load_functions.py", line 132, in load_common

*raise e*

File "/home/zubair-ashfaque/.azure/cliextensions/ml/azext_mlv2/manual/vendored_curated_sdk/azure/ai/ml/entities/_load_functions.py", line 106, in load_common

*return _load_common_raising_marshmallow_error(cls, yaml_dict, relative_origin, params_override, **kwargs)* *^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*

File "/home/zubair-ashfaque/.azure/cliextensions/ml/azext_mlv2/manual/vendored_curated_sdk/azure/ai/ml/entities/_load_functions.py", line 166, in _load_common_raising_marshmallow_error

*res: Resource = cls._load(data=yaml_dict, yaml_path=relative_origin, params_override=params_override, **kwargs)* *^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*

File "/home/zubair-ashfaque/.azure/cliextensions/ml/azext_mlv2/manual/vendored_curated_sdk/azure/ai/ml/entities/_workspace/_ai_workspaces/capability_host.py", line 144, in _load

*return cls(**load_from_dict(CapabilityHostSchema, data, context, **kwargs))* *^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^*

File "/home/zubair-ashfaque/.azure/cliextensions/ml/azext_mlv2/manual/vendored_curated_sdk/azure/ai/ml/entities/_util.py", line 195, in load_from_dict

*raise ValidationError(decorate_validation_error(schema, pretty_error, additional_message)) from e*

marshmallow.exceptions.ValidationError: Validation for CapabilityHostSchema failed:

{

"ai_services_connections": [

*"Not a valid list."*

]

}

The easiest way to author a specification file is using IntelliSense and auto-completion Azure ML VS code extension provides: https://code.visualstudio.com/docs/datascience/azure-machine-learning. To set up: https://learn.microsoft.com/azure/machine-learning/how-to-setup-vs-code

To check existing issues, please visit: https://github.com/Azure/azure-cli/issues

zubair-ashfaque@zubair-ashfaque-ThinkPad:~/MG-AI/mg-voice-agent$

*

in following the post it was mentioned to use
*
https://github.com/Azure/azure-sdk-for-python/issues/40477

BR,
Mian
JAYA SHANKAR G S 2,350 Reputation points Microsoft External Staff

2025-04-30T04:08:22.8966667+00:00

Hello @Mian Omair ,

We can be able to reproduce the same issue via both REST api and sdk, checking with internal for more on this issue will update once we get the details.

Thank you
Mian Omair 0 Reputation points

2025-05-01T10:54:34.9133333+00:00

Hi Manas Mohanty,

any update ?

BR,
Mian
Sampath 2,345 Reputation points Microsoft External Staff

2025-05-01T15:40:52.3733333+00:00

Hello @Mian Omair , we are still check with back-end team.
JAYA SHANKAR G S 2,350 Reputation points Microsoft External Staff

2025-05-02T04:18:07.14+00:00

Hello @Mian Omair ,

We are checking with internal product team on this issue, we will update you once we get back the details.

Thank you

1 answer

Your answer

Manas Mohanty 3,210 Reputation points Microsoft External Staff

2025-04-28T12:12:59.2233333+00:00

Hi Mian Omair

As per Azure function usage documentation, I could not find mention of Capability Hosts. It would be great if you can share relevant threads mentioning them as requirement.

Anomaly found in above code at my side was usage of tool_resource while creating the client.

tool_resources=empty_tool_resources,

in Agent creation

As pre-requisite mentioned in above doc., we need models which were released after November 6, 2023.

I am also doing minimal repro at my side and connecting with team internally on this.

Thank you for your patience.
Manas Mohanty 3,210 Reputation points Microsoft External Staff

2025-04-28T14:22:08.2233333+00:00

Hi Mian Omair

I am able to replicate below error from default documentation usage and checking with team internally on it.

Code: None Message: Invalid tool value(s): azure_function

Thank you.
Manas Mohanty 3,210 Reputation points Microsoft External Staff

2025-04-28T16:02:01.6733333+00:00

Hi Mian Omair

Could you use them as extra params in below command and let us know.

az ml capability-host create --name my-host-name --resource-group my-resource-group --workspace-name my-workspace

Thank you
JAYA SHANKAR G S 2,350 Reputation points Microsoft External Staff

2025-04-30T04:08:22.8966667+00:00

Hello @Mian Omair ,

We can be able to reproduce the same issue via both REST api and sdk, checking with internal for more on this issue will update once we get the details.

Thank you
Mian Omair 0 Reputation points

2025-05-01T10:54:34.9133333+00:00

Hi Manas Mohanty,

any update ?

BR,
Mian
Sampath 2,345 Reputation points Microsoft External Staff

2025-05-01T15:40:52.3733333+00:00

Hello @Mian Omair , we are still check with back-end team.
JAYA SHANKAR G S 2,350 Reputation points Microsoft External Staff

2025-05-02T04:18:07.14+00:00

Hello @Mian Omair ,

We are checking with internal product team on this issue, we will update you once we get back the details.

Thank you

Answer 1

Hello @Mian Omair ,

We got update from product team, issue is happening because there is no capability host created on this project, which essentially makes this an Basic Agent Project, for which the azure function tool is not supported.

So, you need to create a Standard Agent project setup with capability host which can be created with custom template.

Go to this page, click on Deploy to Azure under standard agent setup.

User's image

You will be redirected to custom deployment page like below, fill the required details and deploy it.

User's image

After successfully deployed, run the agent creation code and it successfully created.

User's image

For existing resources, you can use this bicep template

If you have any query, please let us know in the comments or in private message.

Thank you

Share via

Issue with Integrating Azure Function into AI Foundry Agent — Role and Requirement of Capability Host

1 answer

Your answer