Forum Discussion

sr6442527's avatar
sr6442527
Copper Contributor
Dec 02, 2025

Import error: Cannot import name "PromptAgentDefinition" from "azure.ai.projects.models"

Hello,

I am trying to build the agentic retrieval using Azure Ai search. During the creation of agent i am getting "ImportError: cannot import name 'PromptAgentDefinition' from 'azure.ai.projects.models'".  Looked into possible ways of building without it but I need the mcp connection.

This is the documentation i am following: https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-create-pipeline?tabs=search-perms%2Csearch-development%2Cfoundry-setup 

Note: There is no Promptagentdefinition in the directory of azure.ai.projects.models.

['ApiKeyCredentials', 'AzureAISearchIndex', 'BaseCredentials', 'BlobReference', 'BlobReferenceSasCredential', 'Connection', 'ConnectionType', 'CosmosDBIndex', 'CredentialType', 'CustomCredential', 'DatasetCredential', 'DatasetType', 'DatasetVersion', 'Deployment', 'DeploymentType', 'EmbeddingConfiguration', 'EntraIDCredentials', 'EvaluatorIds', 'FieldMapping', 'FileDatasetVersion', 'FolderDatasetVersion', 'Index', 'IndexType', 'ManagedAzureAISearchIndex', 'ModelDeployment', 'ModelDeploymentSku', 'NoAuthenticationCredentials', 'PendingUploadRequest', 'PendingUploadResponse', 'PendingUploadType', 'SASCredentials', 'TYPE_CHECKING', '__all__', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__', '__spec__', '_enums', '_models', '_patch', '_patch_all', '_patch_evaluations', '_patch_sdk']
Traceback (most recent call last):

 

Please let me know what i should do and if there is any other alternative.

Thanks in advance.

AI Platform
azure ai
azure ai foundry
azure ai services
AzureAI

3 Replies

  • Surya_Narayana's avatar
    Surya_Narayana
    MCT
    Dec 08, 2025

    hi sr6442527​ You’re running into a SDK / docs mismatch, not a code problem.

    PromptAgentDefinition does not exist in the current public azure.ai.projects Python package — even though it appears in some Microsoft documentation and samples. That class is part of an internal / preview / renamed abstraction and hasn’t been shipped (or has already been removed/renamed) in the SDK you installed.

    That’s why it’s not in your directory listing

    The correct approach now (no PromptAgentDefinition)

    You do NOT need PromptAgentDefinition to use:

    Agentic retrieval
    Azure AI Search
    MCP / tool connection
    Multi-step grounding

    The new pattern uses Agent + ConnectedAgentTool + AzureAISearchIndex from the same package you’re importing.

    Here’s the working replacement pattern 👇

    Correct imports (CURRENT SDK)

    from azure.ai.projects import AIProjectClient

    from azure.ai.projects.models import (

        AzureAISearchIndex,

        ConnectedAgentTool,

        Agent,

        ToolDefinition

    )

    from azure.identity import DefaultAzureCredential

    Attach Azure AI Search to your Agent

    client = AIProjectClient(

        endpoint=PROJECT_ENDPOINT,

        credential=DefaultAzureCredential()

    )

     

    search_index = AzureAISearchIndex(

        index_name="your-index-name",

        endpoint="https://<your-search>.search.windows.net",

        credential=DefaultAzureCredential()

    )

     

    search_tool = ConnectedAgentTool(

        name="search_tool",

        index=search_index,

        description="Search internal knowledge base"

    )

    Create the Agent (replacement for PromptAgentDefinition)

    agent = client.agents.create_agent(

        name="agentic-retrieval-agent",

        instructions="Answer based only on the search index provided.",

        tools=[search_tool],

        model="gpt-4o"  # or your deployment

    )

    That is now the official way to create an agent with retrieval in current SDKs.

    You're basically writing the same idea — but using Agent + ConnectedAgentTool instead of PromptAgentDefinition.

     

    If you REALLY need MCP behavior

    If your use case is true MCP (multi-connected pipeline), then use:

    from azure.ai.projects.models import ConnectedAgentTool

    And define multiple connections (graph, search, blob, etc):

    tools = [

        ConnectedAgentTool(name="kb", index=kb_index),

        ConnectedAgentTool(name="crm", index=crm_index),

        ConnectedAgentTool(name="finance", index=finance_index)

    ]

    agent = client.agents.create_agent(

        name="mcp-agent",

        model="gpt-4o",

        tools=tools,

        instructions="Use the correct source before answering"

    )

    This actually gives you better orchestration logic than old PromptAgentDefinition.

     

    • sr6442527's avatar
      sr6442527
      Copper Contributor
      Dec 09, 2025

      Thank you Surya_Narayana​ I will try this out as an alternative. 

      I updated the version of azure.ai.projects and all the dependencies which I need are now available in the new version.

Resources