Edit

Share via

Migrate from hub based to Foundry projects

This guide helps existing customers with hub based projects migrate to the new Foundry projects to access the latest platform capabilities.

Azure AI Foundry is transitioning to a unified platform-as-a-service, replacing the previous resource model that required management of multiple Azure services. As we see AI workloads grow more complex, the Foundry project:

  • Simplifies platform setup and governance
  • Enhances workflows that span multiple models and Foundry tools
  • Reinforces governance capabilities

Learn more.

Important

New generative AI and model-centric features are available only through the AI Foundry resource and its Foundry projects. Currently, some capabilities still require a hub next to your Foundry resource. For a comparison of capabilities, see What type of project do I need?

New Foundry projects overview

Foundry projects are designed to unify and simplify the composition of developer workflows, and the management of core building blocks of AI applications:

  • Models
  • Agents & their tools
  • Observability, security, and trust

Previously, AI Foundry project's capabilities required the management of multiple Azure resources and SDKs for workflows in the backend to compose these components.

Screenshot of a diagram showing Azure AI Foundry architecture.

New capabilities include:

  • Access to Foundry API which is designed to build and evaluate API-first agentic applications that compose Agents, Evaluations, Models Indexes, Data in a unified experience, and with a consistent contract across model providers.

  • Azure AI Foundry SDK wraps the Foundry API making it easy to integrate capabilities into code whether your application is built in Python, C#, JavaScript/TypeScript or Java.

  • Agents, Models and Tooling connections are managed together on Foundry for permission management, networking, cost analysis, and policy configuration. Previously certain tools and models were accessed via Azure Machine Learning's hub, requiring also the provisioning of extra storage and key vault resources.

  • Projects are now child resources; they might be assigned their own admin controls like Azure RBAC, but by default share common settings from their parent resource. This principle aims to take IT admins out of the day-to-day loop. Once security, resource connectivity and governance are established at the resource level, as developer you can create your own project as a folder to organize your work.

Important

Foundry projects feature set aren't yet on full parity with hub based projects. For an up-to-date view on supported features, see this support matrix.

How to switch to Foundry project

You'll create new Foundry projects in the AI Foundry models resource from your hub based project. This process allows the new projects to access work originally done in the hub based project.

Screenshot shows the upgrade path from hub based to Foundry project types.

What can you take forward to the new project type?

  • Model deployments
  • Data files
  • Fine-tuned models
  • Assistants
  • Vector stores

Limitations:

  • Your Preview Agent's state, including messages, thread, and files can't be moved. However, you can recreate your agent using code in your new project.
  • Open-source model deployments aren't currently supported in Foundry projects.
  • Your hub based project will not have access to any of the new projects created on the AI Foundry models resource.

In the following sections, we walk through how you can move from hub based projects to Foundry projects:

  1. Locate your existing AI Foundry resource
  2. Create a new Foundry project on the AI resource.

Once you have your new project, you might want to:

1. Locate your existing AI Foundry resource

Most Azure AI Foundry users already have an 'AI Foundry' (formerly called 'AI Services') resource, which was previously created alongside your hub-based project to access model deployments.

Note

If you don't have an existing AI Foundry resource, most common because your hub was using Azure OpenAI for accessing model deployments, you must create a new AI Foundry resource first. You can connect your existing Azure OpenAI resource for continued access to existing model deployments. Other configuration steps apply for use with Agent service. See details in Create a project to build with agents (Bicep) and Agent standard setup.

  1. In Azure AI Foundry portal, open your hub based project.

  2. In the left pane, select Management center.

  3. Select Connected resources under the Hub section.

  4. Find the AI Foundry models connection, and select the link to view its details.

    Screenshot of AI Foundry connection details.

  5. Follow the link in the connection details to open your Foundry resource overview page.

    Screenshot of Foundry resource in management center.

2. Create your new project

New capabilities, including Agent service, are only accessible via projects, which organize your development work as a folder for each use case. You can create multiple of them, to organize the work for use cases with similar setup and connectivity requirements.

You can create a new project in one of two ways:

  • In the Management center:

    1. In the left pane, select Management center to manage the Foundry resource.

    2. Select Overview under the Resource section.

    3. Select New project to create a project in this resource. This will create a Foundry project.

      Screenshot of creating a project in management center.

    4. Once the project is created, in the left pane, select Go to project.

  • In the Agents section of your resource:

    1. In the left pane, select Agents

    2. Since the resource doesn't yet have a project, you are prompted to create one.

      Screenshot of Agents tab prompting to create a new Foundry project.

You're now ready to start building agents in general availability and with the latest capabilities. Get started using SDK or Agent playground.

Screenshot of agent building interface.

(Optional) Recreate connections

If your hub based project used connections to access tools, data sources, or models, you can recreate those connections on your Foundry resource, without the use of a hub.

In the Management center, add any connections to tools and data you used before in your initial hub based project.

(Optional) Migrate code agents

Any code agents build using the preview of Agent service require the following upgrades as you move to Agent service in general availability on Foundry projects:

  1. Install the latest version of your preferred SDK client.

  2. Update your project client to use the Foundry API. Instead of a connection string, you now use the Azure AI Foundry project endpoint. For example, in Python:

    from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project = AIProjectClient(
  endpoint="your_project_endpoint",  # Replace with your endpoint
  credential=DefaultAzureCredential())

  3. Update your script to reflect any class structure changes between the preview and stable SDK packages.

See the SDK migration guide on how to update your existing code.

(Optional) Clean up hub based projects

If you no longer require access to your hub based projects, delete them from your Azure subscription.

There are some reasons you might want to keep hubs and hub based projects around in your subscription:

  • Access to select features that aren't supported yet in Foundry projects. See this support matrix.

  • Use cases that are focused on custom machine learning model training. A hub based project is built on the Azure Machine Learning stack and continues to be accessible via Azure Machine Learning Studio/CLI/SDK.

  1. In Azure AI Foundry portal, open your hub based project.

  2. Select Management center.

  3. Select Overview under the Hub section.

  4. Select any projects you no longer want to keep.

  5. Select Delete project.

  6. Delete any projects you no longer want to keep.

  7. In the Hub properties section on the right, select Delete hub if you want to delete the hub and all its projects. This link will open the Azure portal for you to delete the hub.

Learn more