{"id":7966,"library":"azure-ai-agentserver-core","title":"Azure AI Agent Server Core","description":"Azure AI Agent Server Core (azure-ai-agentserver-core) provides foundational utilities and a host framework for deploying Azure AI Hosted Agents. It enables developers to host their agents as containers in the cloud, allowing interaction via the `azure-ai-projects` SDK. The library is part of the broader Azure SDK for Python, with a current version of 2.0.0b1, reflecting active development and frequent beta releases within the ecosystem.","status":"active","version":"2.0.0b1","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/ai/azure-ai-agentserver-core","tags":["Azure","AI","Agents","Server","Framework","Cloud","Generative AI"],"install":[{"cmd":"pip install azure-ai-agentserver-core","lang":"bash","label":"Install latest beta"}],"dependencies":[{"reason":"Required Python version","package":"python","version":">=3.10","optional":false},{"reason":"Commonly used for authenticating with Azure services, including Azure AI Foundry projects.","package":"azure-identity","optional":true},{"reason":"Companion SDK for interacting with agents hosted by azure-ai-agentserver-core.","package":"azure-ai-projects","optional":true}],"imports":[{"symbol":"FoundryCBAgent","correct":"from azure.ai.agentserver.core import FoundryCBAgent"},{"symbol":"CreateResponse","correct":"from azure.ai.agentserver.core.models import CreateResponse"},{"symbol":"Response as OpenAIResponse","correct":"from azure.ai.agentserver.core.models import Response as OpenAIResponse"},{"symbol":"ItemContentOutputText","correct":"from azure.ai.agentserver.core.models.projects import ItemContentOutputText"},{"symbol":"ResponsesAssistantMessageItemResource","correct":"from azure.ai.agentserver.core.models.projects import ResponsesAssistantMessageItemResource"},{"symbol":"ResponseTextDeltaEvent","correct":"from azure.ai.agentserver.core.models.projects import ResponseTextDeltaEvent"},{"symbol":"ResponseTextDoneEvent","correct":"from azure.ai.agentserver.core.models.projects import ResponseTextDoneEvent"}],"quickstart":{"code":"import os\nimport datetime\nfrom azure.ai.agentserver.core import FoundryCBAgent\nfrom azure.ai.agentserver.core.models import (\n    CreateResponse,\n    Response as OpenAIResponse,\n)\nfrom azure.ai.agentserver.core.models.projects import (\n    ItemContentOutputText,\n    ResponsesAssistantMessageItemResource,\n    ResponseTextDeltaEvent,\n    ResponseTextDoneEvent,\n)\n\ndef stream_events(text: str):\n    assembled = \"\"\n    for i, token in enumerate(text.split(\" \")):\n        piece = token if i == len(text.split(\" \")) - 1 else token + \" \"\n        assembled += piece\n        yield ResponseTextDeltaEvent(delta=piece)\n    yield ResponseTextDoneEvent(text=assembled)\n\nasync def agent_run(request_body: CreateResponse):\n    print(f\"Agent request received: {request_body.agent}\")\n    if request_body.stream:\n        return stream_events(\"I am a mock agent with no intelligence in stream mode.\")\n\n    # Build assistant output content\n    output_content = [\n        ItemContentOutputText(\n            text=\"I am a mock agent with no intelligence, responding to your request.\",\n            annotations=[],\n        )\n    ]\n    response = OpenAIResponse(\n        metadata={},\n        temperature=0.0,\n        top_p=0.0,\n        user=\"mock_user\",\n        id=\"mock_id\",\n        created_at=datetime.datetime.now(),\n        output=[\n            ResponsesAssistantMessageItemResource(\n                status=\"completed\",\n                content=output_content,\n            )\n        ],\n    )\n    return response\n\nmy_agent = FoundryCBAgent()\nmy_agent.agent_run = agent_run\n\nif __name__ == \"__main__\":\n    # Ensure environment variables are set for actual deployment\n    # For local testing, you might not need all env vars for simple mock agents.\n    # However, for cloud deployment, you'd need specifics like AZURE_AI_PROJECT_ENDPOINT\n    # os.environ['AZURE_AI_PROJECT_ENDPOINT'] = 'your_project_endpoint'\n    # os.environ['AZURE_CLIENT_ID'] = 'your_client_id'\n    # os.environ['AZURE_TENANT_ID'] = 'your_tenant_id'\n    # os.environ['AZURE_CLIENT_SECRET'] = 'your_client_secret'\n\n    print(\"Starting Azure AI Agent Server Core mock agent...\")\n    my_agent.run()","lang":"python","description":"This quickstart demonstrates how to define and run a simple mock agent using `azure-ai-agentserver-core`. It sets up a `FoundryCBAgent` with an `agent_run` method that can handle streaming or non-streaming responses. This example focuses on the server-side implementation of an agent that would be hosted in Azure AI Foundry. For actual deployment, environment variables for Azure authentication and project endpoint would be required."},"warnings":[{"fix":"Migrate agent definitions and interactions to use the new `FoundryAgent` pattern, focusing on connecting to pre-configured agents rather than creating them programmatically from the core framework. Refer to the latest Azure AI Agent Framework documentation and samples for correct usage.","message":"The Agent Framework, which `azure-ai-agentserver-core` is part of, underwent a significant architectural shift leading up to its 1.0.0 release. Provider-specific implementations (e.g., for OpenAI or Azure AI Projects directly creating agents) were moved out of the core package into dedicated, lightweight packages.","severity":"breaking","affected_versions":"<1.0.0 of underlying agent framework components"},{"fix":"Understand the distinction: use `azure-ai-agentserver-core` to *implement* the agent's server-side logic, and `azure-ai-projects` (or `azure-ai-agents`) to *build client applications* that interact with the hosted agent.","message":"This library (`azure-ai-agentserver-core`) is primarily a *host framework* for your agent's logic. To interact with or manage agents hosted in Azure AI Foundry (e.g., sending messages, creating threads), you typically use the `azure-ai-projects` client library or `azure-ai-agents` SDK.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Regularly consult the official Azure SDK for Python release notes and documentation. Pin dependencies to specific beta versions during development and test thoroughly before upgrading.","message":"As a beta package (indicated by `b1` in the version), the API of `azure-ai-agentserver-core` is subject to change. Breaking changes may occur in future beta or stable releases without prior deprecation warnings typical of stable versions.","severity":"gotcha","affected_versions":"All beta versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Refactor your agent code to use the `FoundryCBAgent` from `azure.ai.agentserver.core` and follow the current patterns for defining and hosting agents, which assume agents are pre-configured in Azure AI Foundry. Consult the latest quickstart and migration guides.","cause":"Attempting to import or use an old `agent_framework` pattern (e.g., `AzureAIProjectAgentProvider`) which was part of a previous architectural iteration and is no longer included in the leaner core.","error":"ModuleNotFoundError: No module named 'agent_framework.azure'"},{"fix":"Verify that all necessary environment variables (e.g., `AZURE_AI_PROJECT_ENDPOINT`) are correctly set. Ensure the identity running the agent (local developer or deployed service principal/managed identity) has the required 'Azure AI Developer' or custom equivalent roles on the Azure AI Foundry project resource.","cause":"Incorrect or missing environment variables for Azure AI Foundry project endpoint, authentication credentials (e.g., `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`), or insufficient role-based access control (RBAC) permissions for the agent's identity in Azure.","error":"Agent fails to run locally or on cloud with generic configuration errors or authentication failures."}]}