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/core/tests/azure/test_azure_assistants_client.py

@@ -21,7 +21,6 @@ from agent_framework import (
 )
 from agent_framework._settings import SecretString
 from agent_framework.azure import AzureOpenAIAssistantsClient
-from agent_framework.exceptions import ServiceInitializationError
 
 skip_if_azure_integration_tests_disabled = pytest.mark.skipif(
     os.getenv("RUN_INTEGRATION_TESTS", "false").lower() != "true"
@@ -120,7 +119,7 @@ def test_azure_assistants_client_init_auto_create_client(
 
 def test_azure_assistants_client_init_validation_fail() -> None:
     """Test AzureOpenAIAssistantsClient initialization with validation failure."""
-    with pytest.raises(ServiceInitializationError):
+    with pytest.raises(ValueError):
         # Force failure by providing invalid deployment name type - this should cause validation to fail
         AzureOpenAIAssistantsClient(deployment_name=123, api_key="valid-key")  # type: ignore
 
@@ -128,7 +127,7 @@ def test_azure_assistants_client_init_validation_fail() -> None:
 @pytest.mark.parametrize("exclude_list", [["AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"]], indirect=True)
 def test_azure_assistants_client_init_missing_deployment_name(azure_openai_unit_test_env: dict[str, str]) -> None:
     """Test AzureOpenAIAssistantsClient initialization with missing deployment name."""
-    with pytest.raises(ServiceInitializationError):
+    with pytest.raises(ValueError):
         AzureOpenAIAssistantsClient(api_key=azure_openai_unit_test_env.get("AZURE_OPENAI_API_KEY", "test-key"))
 
 
@@ -607,7 +606,7 @@ def test_azure_assistants_client_no_authentication_error() -> None:
         }
 
         # Test missing authentication raises error
-        with pytest.raises(ServiceInitializationError, match="api_key, credential, or a client"):
+        with pytest.raises(ValueError, match="api_key, credential, or a client"):
             AzureOpenAIAssistantsClient(
                 deployment_name="test-deployment",
                 endpoint="https://test-endpoint.openai.azure.com",

python/packages/core/tests/azure/test_azure_chat_client.py

@@ -28,7 +28,7 @@ from agent_framework import (
 )
 from agent_framework._telemetry import USER_AGENT_KEY
 from agent_framework.azure import AzureOpenAIChatClient
-from agent_framework.exceptions import ServiceInitializationError, ServiceResponseException
+from agent_framework.exceptions import ChatClientException
 from agent_framework.openai import (
     ContentFilterResultSeverity,
     OpenAIContentFilterException,
@@ -93,13 +93,13 @@ def test_init_endpoint(azure_openai_unit_test_env: dict[str, str]) -> None:
 
 @pytest.mark.parametrize("exclude_list", [["AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"]], indirect=True)
 def test_init_with_empty_deployment_name(azure_openai_unit_test_env: dict[str, str]) -> None:
-    with pytest.raises(ServiceInitializationError):
+    with pytest.raises(ValueError):
         AzureOpenAIChatClient()
 
 
 @pytest.mark.parametrize("exclude_list", [["AZURE_OPENAI_ENDPOINT", "AZURE_OPENAI_BASE_URL"]], indirect=True)
 def test_init_with_empty_endpoint_and_base_url(azure_openai_unit_test_env: dict[str, str]) -> None:
-    with pytest.raises(ServiceInitializationError):
+    with pytest.raises(ValueError):
         AzureOpenAIChatClient()
 
 
@@ -554,7 +554,7 @@ async def test_bad_request_non_content_filter(
 
     azure_chat_client = AzureOpenAIChatClient()
 
-    with pytest.raises(ServiceResponseException, match="service failed to complete the prompt"):
+    with pytest.raises(ChatClientException, match="service failed to complete the prompt"):
         await azure_chat_client.get_response(
             messages=chat_history,
         )

python/packages/core/tests/azure/test_azure_responses_client.py

@@ -21,7 +21,6 @@ from agent_framework import (
     tool,
 )
 from agent_framework.azure import AzureOpenAIResponsesClient
-from agent_framework.exceptions import ServiceInitializationError
 
 skip_if_azure_integration_tests_disabled = pytest.mark.skipif(
     os.getenv("RUN_INTEGRATION_TESTS", "false").lower() != "true"
@@ -81,7 +80,7 @@ def test_init(azure_openai_unit_test_env: dict[str, str]) -> None:
 
 def test_init_validation_fail() -> None:
     # Test successful initialization
-    with pytest.raises(ServiceInitializationError):
+    with pytest.raises(ValueError):
         AzureOpenAIResponsesClient(api_key="34523", deployment_name={"test": "dict"})  # type: ignore
 
 
@@ -113,7 +112,7 @@ def test_init_with_default_header(azure_openai_unit_test_env: dict[str, str]) ->
 
 @pytest.mark.parametrize("exclude_list", [["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"]], indirect=True)
 def test_init_with_empty_model_id(azure_openai_unit_test_env: dict[str, str]) -> None:
-    with pytest.raises(ServiceInitializationError):
+    with pytest.raises(ValueError):
         AzureOpenAIResponsesClient()
 
 
@@ -212,7 +211,7 @@ def test_create_client_from_project_with_endpoint() -> None:
 
 def test_create_client_from_project_missing_endpoint() -> None:
     """Test _create_client_from_project raises error when endpoint is missing."""
-    with pytest.raises(ServiceInitializationError, match="project endpoint is required"):
+    with pytest.raises(ValueError, match="project endpoint is required"):
         AzureOpenAIResponsesClient._create_client_from_project(
             project_client=None,
             project_endpoint=None,
@@ -222,7 +221,7 @@ def test_create_client_from_project_missing_endpoint() -> None:
 
 def test_create_client_from_project_missing_credential() -> None:
     """Test _create_client_from_project raises error when credential is missing."""
-    with pytest.raises(ServiceInitializationError, match="credential is required"):
+    with pytest.raises(ValueError, match="credential is required"):
         AzureOpenAIResponsesClient._create_client_from_project(
             project_client=None,
             project_endpoint="https://test-project.services.ai.azure.com",

python/packages/core/tests/azure/test_entra_id_authentication.py

@@ -9,7 +9,7 @@ from azure.core.credentials_async import AsyncTokenCredential
 from agent_framework.azure._entra_id_authentication import (
     resolve_credential_to_token_provider,
 )
-from agent_framework.exceptions import ServiceInvalidAuthError
+from agent_framework.exceptions import ChatClientInvalidAuthException
 
 TOKEN_ENDPOINT = "https://cognitiveservices.azure.com/.default"
 
@@ -51,11 +51,11 @@ def test_resolve_callable_provider_passthrough() -> None:
 
 
 def test_resolve_missing_endpoint_raises() -> None:
-    """Test that missing token endpoint raises ServiceInvalidAuthError."""
+    """Test that missing token endpoint raises ChatClientInvalidAuthException."""
     mock_credential = MagicMock(spec=TokenCredential)
 
-    with pytest.raises(ServiceInvalidAuthError, match="A token endpoint must be provided"):
+    with pytest.raises(ChatClientInvalidAuthException, match="A token endpoint must be provided"):
         resolve_credential_to_token_provider(mock_credential, "")
 
-    with pytest.raises(ServiceInvalidAuthError, match="A token endpoint must be provided"):
+    with pytest.raises(ChatClientInvalidAuthException, match="A token endpoint must be provided"):
         resolve_credential_to_token_provider(mock_credential, None)  # type: ignore[arg-type]