Airflow Summit 2026 is coming August 31 - September 2 in Austin, TX. Register now to secure your spot!

Azure AI Foundry Hosted Agents Operators¶

Azure AI Foundry Hosted agents let you run a containerized agent in Microsoft Foundry Agent Service. Build and push your agent image to Azure Container Registry first, then use these operators to create agent versions, invoke the hosted endpoint, and clean up the deployment.

Prerequisite Tasks¶

To use these operators, you must do a few things:

Create necessary resources using AZURE PORTAL or AZURE CLI.
Install API libraries via pip.
pip install 'apache-airflow[azure]'
Detailed information is available Installation of Airflow®
Setup Connection.

The operators use the azure_ai_agents_default connection by default. Configure the Azure AI Foundry project endpoint in the connection host field or in the endpoint connection extra. The endpoint format is:

https://<aiservices-id>.services.ai.azure.com/api/projects/<project-name>

The container image must be available in Azure Container Registry and must implement one of the Hosted agent protocols exposed by Microsoft Foundry, such as responses or invocations.

CreateAzureAIAgentOperator¶

To create an Azure AI Hosted agent from a container image, use the CreateAzureAIAgentOperator. The operator returns the created Hosted agent version as a serializable dictionary. Optional agent fields such as metadata, description, and blueprint_reference can be passed through to the Foundry API.

tests/system/microsoft/azure/example_azure_ai_agents.py[source]

create_agent = CreateAzureAIAgentOperator(
    task_id="create_agent",
    agent_name=AGENT_NAME,
    definition=HOSTED_AGENT_DEFINITION,
    poll_interval=10,
    timeout=900,
    deferrable=False,
    azure_ai_agents_conn_id=AZURE_AI_AGENTS_CONN_ID,
    endpoint=ENDPOINT,
)

UpdateAzureAIAgentOperator¶

Azure AI Hosted agent updates are published as new immutable versions. To create a new version, use the UpdateAzureAIAgentOperator. The operator accepts the same parameters as CreateAzureAIAgentOperator and returns the newly created Hosted agent version as a serializable dictionary.

tests/system/microsoft/azure/example_azure_ai_agents.py[source]

update_agent = UpdateAzureAIAgentOperator(
    task_id="update_agent",
    agent_name=AGENT_NAME,
    definition=UPDATED_AGENT_DEFINITION,
    poll_interval=10,
    timeout=900,
    deferrable=False,
    azure_ai_agents_conn_id=AZURE_AI_AGENTS_CONN_ID,
    endpoint=ENDPOINT,
)

Set deferrable=True to release the worker slot while the new version deploys; the wait then runs in the triggerer. The same parameter is available on CreateAzureAIAgentOperator.

tests/system/microsoft/azure/example_azure_ai_agents.py[source]

update_agent_deferrable = UpdateAzureAIAgentOperator(
    task_id="update_agent_deferrable",
    agent_name=AGENT_NAME,
    definition=UPDATED_AGENT_DEFINITION,
    poll_interval=10,
    timeout=900,
    deferrable=True,
    azure_ai_agents_conn_id=AZURE_AI_AGENTS_CONN_ID,
    endpoint=ENDPOINT,
)

RunAzureAIAgentOperator¶

To invoke an Azure AI Hosted agent, use the RunAzureAIAgentOperator. The responses protocol sends the payload to the agent’s OpenAI-compatible endpoint, and the invocations protocol posts it to the agent’s invocations endpoint. Pass agent_session_id to reuse an existing Hosted agent session with the invocations protocol and user_isolation_key to scope endpoint resources to a specific end user. The operator returns the JSON-compatible protocol response.

tests/system/microsoft/azure/example_azure_ai_agents.py[source]

run_agent = RunAzureAIAgentOperator(
    task_id="run_agent",
    agent_name=AGENT_NAME,
    protocol=RUN_AGENT_PROTOCOL,
    input_data=RUN_AGENT_INPUT,
    azure_ai_agents_conn_id=AZURE_AI_AGENTS_CONN_ID,
    endpoint=ENDPOINT,
)

DeleteAzureAIAgentOperator¶

To delete an Azure AI Hosted agent and all of its versions, use the DeleteAzureAIAgentOperator. Pass agent_version to delete only one version. Set force=True to also delete active sessions associated with the agent or version. The operator returns the serialized deletion response.

tests/system/microsoft/azure/example_azure_ai_agents.py[source]

delete_agent = DeleteAzureAIAgentOperator(
    task_id="delete_agent",
    agent_name=AGENT_NAME,
    force=True,
    poll_interval=10,
    timeout=900,
    trigger_rule=TriggerRule.ALL_DONE,
    azure_ai_agents_conn_id=AZURE_AI_AGENTS_CONN_ID,
    endpoint=ENDPOINT,
)

Reference¶

For further information, look at:

Was this entry helpful?