Python: [BREAKING] Redesign Python exception hierarchy (#4082)

* [BREAKING] Redesign Python exception hierarchy

Replace the flat ServiceException family with domain-scoped branches:
- AgentException (with InvalidAuth, InvalidRequest, InvalidResponse, ContentFilter)
- ChatClientException (same consistent suberrors)
- IntegrationException (same + InitializationError)
- WorkflowException (Runner, Convergence, Checkpoint, Validation, Action, Declarative)
- ContentError (AdditionItemMismatch)
- ToolException / ToolExecutionException (unchanged)
- MiddlewareException / MiddlewareTermination (unchanged)

Key changes:
- All Service* exceptions removed (ServiceException, ServiceInitializationError, etc.)
- AgentExecutionException split into AgentInvalidRequest/ResponseException
- AgentInvocationError removed, split into AgentInvalidRequest/ResponseException
- Workflow exceptions moved from _workflows/_exceptions.py into main exceptions.py
- _workflows/__init__.py emptied; main __init__.py imports directly from submodules
- Purview exceptions re-parented under IntegrationException hierarchy
- Init validation errors use built-in ValueError/TypeError instead of custom exceptions
- CODING_STANDARD.md updated with hierarchy design and rationale

Fixes microsoft/agent-framework#3410

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Clarify ToolException vs ToolExecutionException docstrings

ToolException: base class for all tool-related exceptions (preconditions,
connection/init failures).
ToolExecutionException: runtime call failures (tool call failed, reconnect
failed, MCP errors).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix remaining stale imports from agent_framework._workflows

- azurefunctions: _context.py, _app.py, _serialization.py, test_func_utils.py
  used 'from agent_framework._workflows import X' which broke after
  emptying _workflows/__init__.py; changed to direct submodule imports
- azure-ai-search: test still referenced ServiceInitializationError;
  updated to ValueError to match production code

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

python/packages/azure-ai/tests/test_agent_provider.py

@@ -9,7 +9,6 @@ from agent_framework import (
     Agent,
     tool,
 )
-from agent_framework.exceptions import ServiceInitializationError
 from azure.ai.agents.models import (
     Agent as AzureAgent,
 )
@@ -37,7 +36,6 @@ skip_if_azure_ai_integration_tests_disabled = pytest.mark.skipif(
     else "Integration tests are disabled.",
 )
 
-
 # region Provider Initialization Tests
 
 
@@ -90,7 +88,7 @@ def test_provider_init_missing_endpoint_raises(
     with patch("agent_framework_azure_ai._agent_provider.load_settings") as mock_load_settings:
         mock_load_settings.return_value = {"project_endpoint": None, "model_deployment_name": "test-model"}
 
-        with pytest.raises(ServiceInitializationError) as exc_info:
+        with pytest.raises(ValueError) as exc_info:
             AzureAIAgentsProvider(credential=mock_azure_credential)
 
         assert "project endpoint is required" in str(exc_info.value).lower()
@@ -98,7 +96,7 @@ def test_provider_init_missing_endpoint_raises(
 
 def test_provider_init_missing_credential_raises(azure_ai_unit_test_env: dict[str, str]) -> None:
     """Test AzureAIAgentsProvider raises error when credential is missing."""
-    with pytest.raises(ServiceInitializationError) as exc_info:
+    with pytest.raises(ValueError) as exc_info:
         AzureAIAgentsProvider()
 
     assert "credential is required" in str(exc_info.value).lower()
@@ -106,7 +104,6 @@ def test_provider_init_missing_credential_raises(azure_ai_unit_test_env: dict[st
 
 # endregion
 
-
 # region Context Manager Tests
 
 
@@ -142,7 +139,6 @@ async def test_provider_context_manager_does_not_close_external_client(mock_agen
 
 # endregion
 
-
 # region create_agent Tests
 
 
@@ -272,7 +268,7 @@ async def test_create_agent_missing_model_raises(
 
         provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
 
-        with pytest.raises(ServiceInitializationError) as exc_info:
+        with pytest.raises(ValueError) as exc_info:
             await provider.create_agent(name="TestAgent")
 
         assert "model deployment name is required" in str(exc_info.value).lower()
@@ -280,7 +276,6 @@ async def test_create_agent_missing_model_raises(
 
 # endregion
 
-
 # region get_agent Tests
 
 
@@ -332,7 +327,7 @@ async def test_get_agent_with_function_tools(
 
     provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
 
-    with pytest.raises(ServiceInitializationError) as exc_info:
+    with pytest.raises(ValueError) as exc_info:
         await provider.get_agent("agent-with-tools")
 
     assert "get_weather" in str(exc_info.value)
@@ -374,7 +369,6 @@ async def test_get_agent_with_provided_function_tools(
 
 # endregion
 
-
 # region as_agent Tests
 
 
@@ -427,7 +421,7 @@ def test_as_agent_with_function_tools_validates(
 
     provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
 
-    with pytest.raises(ServiceInitializationError) as exc_info:
+    with pytest.raises(ValueError) as exc_info:
         provider.as_agent(mock_agent)
 
     assert "my_function" in str(exc_info.value)
@@ -489,7 +483,7 @@ def test_as_agent_with_dict_function_tools_validates(
 
     provider = AzureAIAgentsProvider(agents_client=mock_agents_client)
 
-    with pytest.raises(ServiceInitializationError) as exc_info:
+    with pytest.raises(ValueError) as exc_info:
         provider.as_agent(mock_agent)
 
     assert "dict_based_function" in str(exc_info.value)
@@ -534,7 +528,6 @@ def test_as_agent_with_dict_function_tools_provided(
 
 # endregion
 
-
 # region Tool Conversion Tests - to_azure_ai_agent_tools
 
 
@@ -659,7 +652,6 @@ def test_to_azure_ai_agent_tools_unsupported_type() -> None:
 
 # endregion
 
-
 # region Tool Conversion Tests - from_azure_ai_agent_tools
 
 
@@ -784,7 +776,6 @@ def test_from_azure_ai_agent_tools_unknown_dict() -> None:
 
 # endregion
 
-
 # region Integration Tests
 
 

python/packages/azure-ai/tests/test_azure_ai_agent_client.py

@@ -22,7 +22,7 @@ from agent_framework import (
 )
 from agent_framework._serialization import SerializationMixin
 from agent_framework._settings import load_settings
-from agent_framework.exceptions import ServiceInitializationError, ServiceInvalidRequestError
+from agent_framework.exceptions import ChatClientInvalidRequestException
 from azure.ai.agents.models import (
     AgentsNamedToolChoice,
     AgentsNamedToolChoiceType,
@@ -165,7 +165,7 @@ def test_azure_ai_chat_client_init_missing_project_endpoint() -> None:
     with patch("agent_framework_azure_ai._chat_client.load_settings") as mock_load_settings:
         mock_load_settings.return_value = {"project_endpoint": None, "model_deployment_name": "test-model"}
 
-        with pytest.raises(ServiceInitializationError, match="project endpoint is required"):
+        with pytest.raises(ValueError, match="project endpoint is required"):
             AzureAIAgentClient(
                 agents_client=None,
                 agent_id=None,
@@ -181,7 +181,7 @@ def test_azure_ai_chat_client_init_missing_model_deployment_for_agent_creation()
     with patch("agent_framework_azure_ai._chat_client.load_settings") as mock_load_settings:
         mock_load_settings.return_value = {"project_endpoint": "https://test.com", "model_deployment_name": None}
 
-        with pytest.raises(ServiceInitializationError, match="model deployment name is required"):
+        with pytest.raises(ValueError, match="model deployment name is required"):
             AzureAIAgentClient(
                 agents_client=None,
                 agent_id=None,  # No existing agent
@@ -193,9 +193,7 @@ def test_azure_ai_chat_client_init_missing_model_deployment_for_agent_creation()
 
 def test_azure_ai_chat_client_init_missing_credential(azure_ai_unit_test_env: dict[str, str]) -> None:
     """Test AzureAIAgentClient.__init__ when credential is missing and no agents_client provided."""
-    with pytest.raises(
-        ServiceInitializationError, match="Azure credential is required when agents_client is not provided"
-    ):
+    with pytest.raises(ValueError, match="Azure credential is required when agents_client is not provided"):
         AzureAIAgentClient(
             agents_client=None,
             agent_id="existing-agent",
@@ -325,7 +323,7 @@ async def test_azure_ai_chat_client_get_agent_id_or_create_missing_model(
     """Test _get_agent_id_or_create when model_deployment_name is missing."""
     client = create_test_azure_ai_chat_client(mock_agents_client)
 
-    with pytest.raises(ServiceInitializationError, match="Model deployment name is required"):
+    with pytest.raises(ValueError, match="Model deployment name is required"):
         await client._get_agent_id_or_create()  # type: ignore
 
 
@@ -2011,7 +2009,7 @@ async def test_azure_ai_chat_client_prepare_options_with_invalid_response_format
     # Invalid response_format (not BaseModel or Mapping)
     chat_options: ChatOptions = {"response_format": "invalid_format"}  # type: ignore[typeddict-item]
 
-    with pytest.raises(ServiceInvalidRequestError, match="response_format must be a Pydantic BaseModel"):
+    with pytest.raises(ChatClientInvalidRequestException, match="response_format must be a Pydantic BaseModel"):
         await client._prepare_options([], chat_options)  # type: ignore
 
 

python/packages/azure-ai/tests/test_azure_ai_client.py

@@ -21,7 +21,6 @@ from agent_framework import (
     tool,
 )
 from agent_framework._settings import load_settings
-from agent_framework.exceptions import ServiceInitializationError
 from azure.ai.projects.aio import AIProjectClient
 from azure.ai.projects.models import (
     ApproximateLocation,
@@ -213,15 +212,13 @@ def test_init_missing_project_endpoint() -> None:
     with patch("agent_framework_azure_ai._client.load_settings") as mock_load_settings:
         mock_load_settings.return_value = {"project_endpoint": None, "model_deployment_name": "test-model"}
 
-        with pytest.raises(ServiceInitializationError, match="Azure AI project endpoint is required"):
+        with pytest.raises(ValueError, match="Azure AI project endpoint is required"):
             AzureAIClient(credential=MagicMock())
 
 
 def test_init_missing_credential(azure_ai_unit_test_env: dict[str, str]) -> None:
     """Test AzureAIClient.__init__ when credential is missing and no project_client provided."""
-    with pytest.raises(
-        ServiceInitializationError, match="Azure credential is required when project_client is not provided"
-    ):
+    with pytest.raises(ValueError, match="Azure credential is required when project_client is not provided"):
         AzureAIClient(
             project_endpoint=azure_ai_unit_test_env["AZURE_AI_PROJECT_ENDPOINT"],
             model_deployment_name=azure_ai_unit_test_env["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
@@ -245,7 +242,7 @@ async def test_get_agent_reference_or_create_missing_agent_name(
     """Test _get_agent_reference_or_create raises when agent_name is missing."""
     client = create_test_azure_ai_client(mock_project_client, agent_name=None)
 
-    with pytest.raises(ServiceInitializationError, match="Agent name is required"):
+    with pytest.raises(ValueError, match="Agent name is required"):
         await client._get_agent_reference_or_create({}, None)  # type: ignore
 
 
@@ -283,7 +280,7 @@ async def test_get_agent_reference_missing_model(
     """Test _get_agent_reference_or_create when model is missing for agent creation."""
     client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent")
 
-    with pytest.raises(ServiceInitializationError, match="Model deployment name is required for agent creation"):
+    with pytest.raises(ValueError, match="Model deployment name is required for agent creation"):
         await client._get_agent_reference_or_create({}, None)  # type: ignore
 
 
@@ -1287,7 +1284,6 @@ def test_from_azure_ai_tools_web_search() -> None:
 
 # endregion
 
-
 # region Integration Tests
 
 

python/packages/azure-ai/tests/test_provider.py

@@ -6,7 +6,6 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest
 from agent_framework import Agent, FunctionTool
 from agent_framework._mcp import MCPTool
-from agent_framework.exceptions import ServiceInitializationError
 from azure.ai.projects.aio import AIProjectClient
 from azure.ai.projects.models import (
     AgentReference,
@@ -110,15 +109,13 @@ def test_provider_init_missing_endpoint() -> None:
     with patch("agent_framework_azure_ai._project_provider.load_settings") as mock_load_settings:
         mock_load_settings.return_value = {"project_endpoint": None, "model_deployment_name": "test-model"}
 
-        with pytest.raises(ServiceInitializationError, match="Azure AI project endpoint is required"):
+        with pytest.raises(ValueError, match="Azure AI project endpoint is required"):
             AzureAIProjectAgentProvider(credential=MagicMock())
 
 
 def test_provider_init_missing_credential(azure_ai_unit_test_env: dict[str, str]) -> None:
     """Test AzureAIProjectAgentProvider initialization when credential is missing."""
-    with pytest.raises(
-        ServiceInitializationError, match="Azure credential is required when project_client is not provided"
-    ):
+    with pytest.raises(ValueError, match="Azure credential is required when project_client is not provided"):
         AzureAIProjectAgentProvider(
             project_endpoint=azure_ai_unit_test_env["AZURE_AI_PROJECT_ENDPOINT"],
         )
@@ -208,7 +205,7 @@ async def test_provider_create_agent_missing_model(mock_project_client: MagicMoc
 
         provider = AzureAIProjectAgentProvider(project_client=mock_project_client)
 
-        with pytest.raises(ServiceInitializationError, match="Model deployment name is required"):
+        with pytest.raises(ValueError, match="Model deployment name is required"):
             await provider.create_agent(name="test-agent")
 
 

python/packages/azure-ai/tests/test_shared.py

@@ -7,7 +7,7 @@ import pytest
 from agent_framework import (
     FunctionTool,
 )
-from agent_framework.exceptions import ServiceInvalidRequestError
+from agent_framework.exceptions import IntegrationInvalidRequestException
 from azure.ai.agents.models import CodeInterpreterToolDefinition
 from pydantic import BaseModel
 
@@ -387,7 +387,7 @@ def test_create_text_format_config_text() -> None:
 
 def test_create_text_format_config_invalid_raises() -> None:
     """Test invalid response_format raises error."""
-    with pytest.raises(ServiceInvalidRequestError):
+    with pytest.raises(IntegrationInvalidRequestException):
         create_text_format_config({"type": "invalid"})
 
 
@@ -400,7 +400,7 @@ def test_convert_response_format_with_format_key() -> None:
 
 def test_convert_response_format_json_schema_missing_schema_raises() -> None:
     """Test json_schema without schema raises error."""
-    with pytest.raises(ServiceInvalidRequestError, match="requires a schema"):
+    with pytest.raises(IntegrationInvalidRequestException, match="requires a schema"):
         _convert_response_format({"type": "json_schema", "json_schema": {}})