mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
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>
This commit is contained in:
Eduard van Valkenburg
committed by
GitHub
Unverified
GitHub
parent
7f606a2e3a
commit
5ee06853a1
@@ -18,7 +18,6 @@ from agent_framework._mcp import MCPTool
|
||||
from agent_framework._settings import load_settings
|
||||
from agent_framework._tools import ToolTypes
|
||||
from agent_framework.azure._entra_id_authentication import AzureCredentialTypes
|
||||
from agent_framework.exceptions import ServiceInitializationError
|
||||
from azure.ai.agents.aio import AgentsClient
|
||||
from azure.ai.agents.models import Agent as AzureAgent
|
||||
from azure.ai.agents.models import ResponseFormatJsonSchema, ResponseFormatJsonSchemaType
|
||||
@@ -113,7 +112,7 @@ class AzureAIAgentsProvider(Generic[OptionsCoT]):
|
||||
env_file_encoding: Encoding of the .env file.
|
||||
|
||||
Raises:
|
||||
ServiceInitializationError: If required parameters are missing or invalid.
|
||||
ValueError: If required parameters are missing or invalid.
|
||||
"""
|
||||
self._settings = load_settings(
|
||||
AzureAISettings,
|
||||
@@ -130,12 +129,12 @@ class AzureAIAgentsProvider(Generic[OptionsCoT]):
|
||||
else:
|
||||
resolved_endpoint = self._settings.get("project_endpoint")
|
||||
if not resolved_endpoint:
|
||||
raise ServiceInitializationError(
|
||||
raise ValueError(
|
||||
"Azure AI project endpoint is required. Provide 'project_endpoint' parameter "
|
||||
"or set 'AZURE_AI_PROJECT_ENDPOINT' environment variable."
|
||||
)
|
||||
if not credential:
|
||||
raise ServiceInitializationError("Azure credential is required when agents_client is not provided.")
|
||||
raise ValueError("Azure credential is required when agents_client is not provided.")
|
||||
self._agents_client = AgentsClient(
|
||||
endpoint=resolved_endpoint,
|
||||
credential=credential, # type: ignore[arg-type]
|
||||
@@ -199,7 +198,7 @@ class AzureAIAgentsProvider(Generic[OptionsCoT]):
|
||||
Agent: A Agent instance configured with the created agent.
|
||||
|
||||
Raises:
|
||||
ServiceInitializationError: If model deployment name is not available.
|
||||
ValueError: If model deployment name is not available.
|
||||
|
||||
Examples:
|
||||
.. code-block:: python
|
||||
@@ -212,7 +211,7 @@ class AzureAIAgentsProvider(Generic[OptionsCoT]):
|
||||
"""
|
||||
resolved_model = model or self._settings.get("model_deployment_name")
|
||||
if not resolved_model:
|
||||
raise ServiceInitializationError(
|
||||
raise ValueError(
|
||||
"Model deployment name is required. Provide 'model' parameter "
|
||||
"or set 'AZURE_AI_MODEL_DEPLOYMENT_NAME' environment variable."
|
||||
)
|
||||
@@ -290,7 +289,7 @@ class AzureAIAgentsProvider(Generic[OptionsCoT]):
|
||||
Agent: A Agent instance configured with the retrieved agent.
|
||||
|
||||
Raises:
|
||||
ServiceInitializationError: If required function tools are not provided.
|
||||
ValueError: If required function tools are not provided.
|
||||
|
||||
Examples:
|
||||
.. code-block:: python
|
||||
@@ -340,7 +339,7 @@ class AzureAIAgentsProvider(Generic[OptionsCoT]):
|
||||
Agent: A Agent instance configured with the agent.
|
||||
|
||||
Raises:
|
||||
ServiceInitializationError: If required function tools are not provided.
|
||||
ValueError: If required function tools are not provided.
|
||||
|
||||
Examples:
|
||||
.. code-block:: python
|
||||
@@ -449,7 +448,7 @@ class AzureAIAgentsProvider(Generic[OptionsCoT]):
|
||||
"""Validate that required function tools are provided.
|
||||
|
||||
Raises:
|
||||
ServiceInitializationError: If agent has function tools but user
|
||||
ValueError: If agent has function tools but user
|
||||
didn't provide implementations.
|
||||
"""
|
||||
if not agent_tools:
|
||||
@@ -483,7 +482,7 @@ class AzureAIAgentsProvider(Generic[OptionsCoT]):
|
||||
# Check for missing implementations
|
||||
missing = function_tool_names - provided_names
|
||||
if missing:
|
||||
raise ServiceInitializationError(
|
||||
raise ValueError(
|
||||
f"Agent has function tools that require implementations: {missing}. "
|
||||
"Provide these functions via the 'tools' parameter."
|
||||
)
|
||||
|
||||
@@ -36,7 +36,10 @@ from agent_framework import (
|
||||
from agent_framework._settings import load_settings
|
||||
from agent_framework._tools import ToolTypes
|
||||
from agent_framework.azure._entra_id_authentication import AzureCredentialTypes
|
||||
from agent_framework.exceptions import ServiceInitializationError, ServiceInvalidRequestError, ServiceResponseException
|
||||
from agent_framework.exceptions import (
|
||||
ChatClientException,
|
||||
ChatClientInvalidRequestException,
|
||||
)
|
||||
from agent_framework.observability import ChatTelemetryLayer
|
||||
from azure.ai.agents.aio import AgentsClient
|
||||
from azure.ai.agents.models import (
|
||||
@@ -498,20 +501,20 @@ class AzureAIAgentClient(
|
||||
if agents_client is None:
|
||||
resolved_endpoint = azure_ai_settings.get("project_endpoint")
|
||||
if not resolved_endpoint:
|
||||
raise ServiceInitializationError(
|
||||
raise ValueError(
|
||||
"Azure AI project endpoint is required. Set via 'project_endpoint' parameter "
|
||||
"or 'AZURE_AI_PROJECT_ENDPOINT' environment variable."
|
||||
)
|
||||
|
||||
if agent_id is None and not azure_ai_settings.get("model_deployment_name"):
|
||||
raise ServiceInitializationError(
|
||||
raise ValueError(
|
||||
"Azure AI model deployment name is required. Set via 'model_deployment_name' parameter "
|
||||
"or 'AZURE_AI_MODEL_DEPLOYMENT_NAME' environment variable."
|
||||
)
|
||||
|
||||
# Use provided credential
|
||||
if not credential:
|
||||
raise ServiceInitializationError("Azure credential is required when agents_client is not provided.")
|
||||
raise ValueError("Azure credential is required when agents_client is not provided.")
|
||||
agents_client = AgentsClient(
|
||||
endpoint=resolved_endpoint,
|
||||
credential=credential, # type: ignore[arg-type]
|
||||
@@ -606,7 +609,7 @@ class AzureAIAgentClient(
|
||||
# If no agent_id is provided, create a temporary agent
|
||||
if self.agent_id is None:
|
||||
if "model" not in run_options or not run_options["model"]:
|
||||
raise ServiceInitializationError(
|
||||
raise ValueError(
|
||||
"Model deployment name is required for agent creation, "
|
||||
"can also be passed to the get_response methods."
|
||||
)
|
||||
@@ -916,7 +919,7 @@ class AzureAIAgentClient(
|
||||
response_id=response_id,
|
||||
)
|
||||
case AgentStreamEvent.THREAD_RUN_FAILED:
|
||||
raise ServiceResponseException(event_data.last_error.message)
|
||||
raise ChatClientException(event_data.last_error.message)
|
||||
case _:
|
||||
yield ChatResponseUpdate(
|
||||
contents=[],
|
||||
@@ -1159,7 +1162,7 @@ class AzureAIAgentClient(
|
||||
# Runtime JSON schema dict - pass through as-is
|
||||
run_options["response_format"] = response_format
|
||||
else:
|
||||
raise ServiceInvalidRequestError(
|
||||
raise ChatClientInvalidRequestException(
|
||||
"response_format must be a Pydantic BaseModel class or a dict with runtime JSON schema."
|
||||
)
|
||||
|
||||
|
||||
@@ -24,7 +24,6 @@ from agent_framework import (
|
||||
from agent_framework._settings import load_settings
|
||||
from agent_framework._tools import ToolTypes
|
||||
from agent_framework.azure._entra_id_authentication import AzureCredentialTypes
|
||||
from agent_framework.exceptions import ServiceInitializationError
|
||||
from agent_framework.observability import ChatTelemetryLayer
|
||||
from agent_framework.openai import OpenAIResponsesOptions
|
||||
from agent_framework.openai._responses_client import RawOpenAIResponsesClient
|
||||
@@ -188,14 +187,14 @@ class RawAzureAIClient(RawOpenAIResponsesClient[AzureAIClientOptionsT], Generic[
|
||||
if project_client is None:
|
||||
resolved_endpoint = azure_ai_settings.get("project_endpoint")
|
||||
if not resolved_endpoint:
|
||||
raise ServiceInitializationError(
|
||||
raise ValueError(
|
||||
"Azure AI project endpoint is required. Set via 'project_endpoint' parameter "
|
||||
"or 'AZURE_AI_PROJECT_ENDPOINT' environment variable."
|
||||
)
|
||||
|
||||
# Use provided credential
|
||||
if not credential:
|
||||
raise ServiceInitializationError("Azure credential is required when project_client is not provided.")
|
||||
raise ValueError("Azure credential is required when project_client is not provided.")
|
||||
project_client = AIProjectClient(
|
||||
endpoint=resolved_endpoint,
|
||||
credential=credential, # type: ignore[arg-type]
|
||||
@@ -345,7 +344,7 @@ class RawAzureAIClient(RawOpenAIResponsesClient[AzureAIClientOptionsT], Generic[
|
||||
"""
|
||||
# Agent name must be explicitly provided by the user.
|
||||
if self.agent_name is None:
|
||||
raise ServiceInitializationError(
|
||||
raise ValueError(
|
||||
"Agent name is required. Provide 'agent_name' when initializing AzureAIClient "
|
||||
"or 'name' when initializing Agent."
|
||||
)
|
||||
@@ -363,7 +362,7 @@ class RawAzureAIClient(RawOpenAIResponsesClient[AzureAIClientOptionsT], Generic[
|
||||
return {"name": self.agent_name, "version": self.agent_version, "type": "agent_reference"}
|
||||
|
||||
if "model" not in run_options or not run_options["model"]:
|
||||
raise ServiceInitializationError(
|
||||
raise ValueError(
|
||||
"Model deployment name is required for agent creation, "
|
||||
"can also be passed to the get_response methods."
|
||||
)
|
||||
|
||||
@@ -19,7 +19,6 @@ from agent_framework._mcp import MCPTool
|
||||
from agent_framework._settings import load_settings
|
||||
from agent_framework._tools import ToolTypes
|
||||
from agent_framework.azure._entra_id_authentication import AzureCredentialTypes
|
||||
from agent_framework.exceptions import ServiceInitializationError
|
||||
from azure.ai.projects.aio import AIProjectClient
|
||||
from azure.ai.projects.models import (
|
||||
AgentReference,
|
||||
@@ -123,7 +122,7 @@ class AzureAIProjectAgentProvider(Generic[OptionsCoT]):
|
||||
env_file_encoding: Encoding of the environment file.
|
||||
|
||||
Raises:
|
||||
ServiceInitializationError: If required parameters are missing or invalid.
|
||||
ValueError: If required parameters are missing or invalid.
|
||||
"""
|
||||
self._settings = load_settings(
|
||||
AzureAISettings,
|
||||
@@ -140,13 +139,13 @@ class AzureAIProjectAgentProvider(Generic[OptionsCoT]):
|
||||
if project_client is None:
|
||||
resolved_endpoint = self._settings.get("project_endpoint")
|
||||
if not resolved_endpoint:
|
||||
raise ServiceInitializationError(
|
||||
raise ValueError(
|
||||
"Azure AI project endpoint is required. Set via 'project_endpoint' parameter "
|
||||
"or 'AZURE_AI_PROJECT_ENDPOINT' environment variable."
|
||||
)
|
||||
|
||||
if not credential:
|
||||
raise ServiceInitializationError("Azure credential is required when project_client is not provided.")
|
||||
raise ValueError("Azure credential is required when project_client is not provided.")
|
||||
|
||||
project_client = AIProjectClient(
|
||||
endpoint=resolved_endpoint,
|
||||
@@ -186,12 +185,12 @@ class AzureAIProjectAgentProvider(Generic[OptionsCoT]):
|
||||
Agent: A Agent instance configured with the created agent.
|
||||
|
||||
Raises:
|
||||
ServiceInitializationError: If required parameters are missing.
|
||||
ValueError: If required parameters are missing.
|
||||
"""
|
||||
# Resolve model from parameter or environment variable
|
||||
resolved_model = model or self._settings.get("model_deployment_name")
|
||||
if not resolved_model:
|
||||
raise ServiceInitializationError(
|
||||
raise ValueError(
|
||||
"Model deployment name is required. Provide 'model' parameter "
|
||||
"or set 'AZURE_AI_MODEL_DEPLOYMENT_NAME' environment variable."
|
||||
)
|
||||
|
||||
@@ -10,7 +10,7 @@ from typing import Any, cast
|
||||
from agent_framework import (
|
||||
FunctionTool,
|
||||
)
|
||||
from agent_framework.exceptions import ServiceInvalidRequestError
|
||||
from agent_framework.exceptions import IntegrationInvalidRequestException
|
||||
from azure.ai.agents.models import (
|
||||
CodeInterpreterToolDefinition,
|
||||
ToolDefinition,
|
||||
@@ -125,7 +125,7 @@ def to_azure_ai_agent_tools(
|
||||
List of Azure AI V1 SDK tool definitions.
|
||||
|
||||
Raises:
|
||||
ServiceInitializationError: If tool configuration is invalid.
|
||||
ValueError: If tool configuration is invalid.
|
||||
"""
|
||||
if not tools:
|
||||
return []
|
||||
@@ -458,7 +458,7 @@ def create_text_format_config(
|
||||
if format_type == "text":
|
||||
return ResponseTextFormatConfigurationText()
|
||||
|
||||
raise ServiceInvalidRequestError("response_format must be a Pydantic model or mapping.")
|
||||
raise IntegrationInvalidRequestException("response_format must be a Pydantic model or mapping.")
|
||||
|
||||
|
||||
def _convert_response_format(response_format: Mapping[str, Any]) -> dict[str, Any]:
|
||||
@@ -470,11 +470,11 @@ def _convert_response_format(response_format: Mapping[str, Any]) -> dict[str, An
|
||||
if format_type == "json_schema":
|
||||
schema_section = response_format.get("json_schema", response_format)
|
||||
if not isinstance(schema_section, Mapping):
|
||||
raise ServiceInvalidRequestError("json_schema response_format must be a mapping.")
|
||||
raise IntegrationInvalidRequestException("json_schema response_format must be a mapping.")
|
||||
schema_section_typed = cast("Mapping[str, Any]", schema_section)
|
||||
schema: Any = schema_section_typed.get("schema")
|
||||
if schema is None:
|
||||
raise ServiceInvalidRequestError("json_schema response_format requires a schema.")
|
||||
raise IntegrationInvalidRequestException("json_schema response_format requires a schema.")
|
||||
name: str = str(
|
||||
schema_section_typed.get("name")
|
||||
or schema_section_typed.get("title")
|
||||
@@ -495,4 +495,4 @@ def _convert_response_format(response_format: Mapping[str, Any]) -> dict[str, An
|
||||
if format_type in {"json_object", "text"}:
|
||||
return {"type": format_type}
|
||||
|
||||
raise ServiceInvalidRequestError("Unsupported response_format provided for Azure AI client.")
|
||||
raise IntegrationInvalidRequestException("Unsupported response_format provided for Azure AI client.")
|
||||
|
||||
Reference in New Issue
Block a user