agent/agent-framework
1
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* [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
2026-02-19 18:58:14 +01:00
committed by GitHub
Unverified
parent 7f606a2e3a
commit 5ee06853a1
90 changed files with 642 additions and 718 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/packages/declarative/agent_framework_declarative/__init__.py
-2
View File
@@ -6,7 +6,6 @@ from ._loader import AgentFactory, DeclarativeLoaderError, ProviderLookupError,
from ._workflows import (
AgentExternalInputRequest,
AgentExternalInputResponse,
AgentInvocationError,
DeclarativeWorkflowError,
ExternalInputRequest,
ExternalInputResponse,
@@ -23,7 +22,6 @@ __all__ = [
"AgentExternalInputRequest",
"AgentExternalInputResponse",
"AgentFactory",
"AgentInvocationError",
"DeclarativeLoaderError",
"DeclarativeWorkflowError",
"ExternalInputRequest",
python/packages/declarative/agent_framework_declarative/_loader.py
+2 -2
View File
@@ -16,7 +16,7 @@ from agent_framework import (
FunctionTool as AFFunctionTool,
)
from agent_framework._tools import _create_model_from_json_schema # type: ignore
from agent_framework.exceptions import AgentFrameworkException
from agent_framework.exceptions import AgentException
from dotenv import load_dotenv
from ._models import (
@@ -104,7 +104,7 @@ PROVIDER_TYPE_OBJECT_MAPPING: dict[str, ProviderTypeMapping] = {
}
class DeclarativeLoaderError(AgentFrameworkException):
class DeclarativeLoaderError(AgentException):
"""Exception raised for errors in the declarative loader."""
pass
python/packages/declarative/agent_framework_declarative/_workflows/__init__.py
-2
View File
@@ -31,7 +31,6 @@ from ._executors_agents import (
TOOL_REGISTRY_KEY,
AgentExternalInputRequest,
AgentExternalInputResponse,
AgentInvocationError,
AgentResult,
ExternalLoopState,
InvokeAzureAgentExecutor,
@@ -92,7 +91,6 @@ __all__ = [
"ActionTrigger",
"AgentExternalInputRequest",
"AgentExternalInputResponse",
"AgentInvocationError",
"AgentResult",
"AppendValueExecutor",
"BreakLoopExecutor",
python/packages/declarative/agent_framework_declarative/_workflows/_actions_error.py
+3 -1
View File
@@ -13,6 +13,8 @@ import logging
from collections.abc import AsyncGenerator
from dataclasses import dataclass
from agent_framework.exceptions import WorkflowException
from ._handlers import (
ActionContext,
WorkflowEvent,
@@ -22,7 +24,7 @@ from ._handlers import (
logger = logging.getLogger("agent_framework.declarative")
class WorkflowActionError(Exception):
class WorkflowActionError(WorkflowException):
"""Exception raised by ThrowException action."""
def __init__(self, message: str, code: str | None = None):
python/packages/declarative/agent_framework_declarative/_workflows/_declarative_base.py
+1 -1
View File
@@ -32,7 +32,7 @@ from dataclasses import dataclass
from decimal import Decimal as _Decimal
from typing import Any, Literal, cast
from agent_framework._workflows import (
from agent_framework import (
Executor,
WorkflowContext,
)
python/packages/declarative/agent_framework_declarative/_workflows/_declarative_builder.py
+1 -1
View File
@@ -15,7 +15,7 @@ from __future__ import annotations
from typing import Any
from agent_framework._workflows import (
from agent_framework import (
Workflow,
WorkflowBuilder,
)
python/packages/declarative/agent_framework_declarative/_workflows/_executors_agents.py
+9 -19
View File
@@ -26,6 +26,7 @@ from agent_framework import (
handler,
response_handler,
)
from agent_framework.exceptions import AgentInvalidRequestException, AgentInvalidResponseException
from ._declarative_base import (
ActionComplete,
@@ -243,19 +244,6 @@ TOOL_REGISTRY_KEY = "_tool_registry"
EXTERNAL_LOOP_STATE_KEY = "_external_loop_state"
class AgentInvocationError(Exception):
"""Raised when an agent invocation fails.
Attributes:
agent_name: Name of the agent that failed
message: Error description
"""
def __init__(self, agent_name: str, message: str) -> None:
self.agent_name = agent_name
super().__init__(f"Agent '{agent_name}' invocation failed: {message}")
@dataclass
class AgentResult:
"""Result from an agent invocation."""
@@ -807,7 +795,7 @@ class InvokeAzureAgentExecutor(DeclarativeActionExecutor):
state.set("Agent.error", error_msg)
if result_property:
state.set(result_property, {"error": error_msg})
raise AgentInvocationError(agent_name, "not found in registry")
raise AgentInvalidRequestException(f"Agent '{agent_name}' invocation failed: not found in registry")
iteration = 0
@@ -824,14 +812,14 @@ class InvokeAzureAgentExecutor(DeclarativeActionExecutor):
auto_send=auto_send,
messages_path=messages_path,
)
except AgentInvocationError:
except (AgentInvalidRequestException, AgentInvalidResponseException):
raise # Re-raise our own errors
except Exception as e:
logger.error(f"InvokeAzureAgent: error invoking agent '{agent_name}': {e}")
state.set("Agent.error", str(e))
if result_property:
state.set(result_property, {"error": str(e)})
raise AgentInvocationError(agent_name, str(e)) from e
raise AgentInvalidResponseException(f"Agent '{agent_name}' invocation failed: {e}") from e
# Check external loop condition
if external_loop_when:
@@ -948,7 +936,9 @@ class InvokeAzureAgentExecutor(DeclarativeActionExecutor):
if agent is None:
logger.error(f"InvokeAzureAgent: agent '{agent_name}' not found during loop resumption")
raise AgentInvocationError(agent_name, "not found during loop resumption")
raise AgentInvalidRequestException(
f"Agent '{agent_name}' invocation failed: not found during loop resumption"
)
try:
accumulated_response, all_messages, tool_calls = await self._invoke_agent_and_store_results(
@@ -963,12 +953,12 @@ class InvokeAzureAgentExecutor(DeclarativeActionExecutor):
auto_send=loop_state.auto_send,
messages_path=loop_state.messages_path,
)
except AgentInvocationError:
except (AgentInvalidRequestException, AgentInvalidResponseException):
raise # Re-raise our own errors
except Exception as e:
logger.error(f"InvokeAzureAgent: error invoking agent '{agent_name}' during loop: {e}")
state.set("Agent.error", str(e))
raise AgentInvocationError(agent_name, str(e)) from e
raise AgentInvalidResponseException(f"Agent '{agent_name}' invocation failed: {e}") from e
# Re-evaluate the condition AFTER the agent responds
# This is critical: the agent's response may have set NeedsTicket=true or IsResolved=true
python/packages/declarative/agent_framework_declarative/_workflows/_executors_basic.py
+1 -1
View File
@@ -8,7 +8,7 @@ Each action becomes a node in the workflow graph.
from typing import Any
from agent_framework._workflows import (
from agent_framework import (
WorkflowContext,
handler,
)
python/packages/declarative/agent_framework_declarative/_workflows/_executors_control_flow.py
+1 -1
View File
@@ -16,7 +16,7 @@ The key insight is that control flow becomes GRAPH STRUCTURE, not executor logic
from typing import Any, cast
from agent_framework._workflows import (
from agent_framework import (
WorkflowContext,
handler,
)
python/packages/declarative/agent_framework_declarative/_workflows/_executors_external_input.py
+1 -1
View File
@@ -11,7 +11,7 @@ import uuid
from dataclasses import dataclass, field
from typing import Any
from agent_framework._workflows import (
from agent_framework import (
WorkflowContext,
handler,
response_handler,
python/packages/declarative/agent_framework_declarative/_workflows/_factory.py
+2 -1
View File
@@ -24,6 +24,7 @@ from agent_framework import (
SupportsAgentRun,
Workflow,
)
from agent_framework.exceptions import WorkflowException
from .._loader import AgentFactory
from ._declarative_builder import DeclarativeWorkflowBuilder
@@ -31,7 +32,7 @@ from ._declarative_builder import DeclarativeWorkflowBuilder
logger = logging.getLogger("agent_framework.declarative")
class DeclarativeWorkflowError(Exception):
class DeclarativeWorkflowError(WorkflowException):
"""Exception raised for errors in declarative workflow processing."""
pass
python/packages/declarative/tests/test_graph_coverage.py
+7 -5
View File
@@ -1851,9 +1851,10 @@ class TestAgentExternalLoopCoverage:
assert request.agent_name == "TestAgent"
async def test_agent_executor_agent_error_handling(self, mock_context, mock_state):
"""Test agent executor raises AgentInvocationError on failure."""
"""Test agent executor raises AgentInvalidResponseException on failure."""
from agent_framework.exceptions import AgentInvalidResponseException
from agent_framework_declarative._workflows._executors_agents import (
AgentInvocationError,
InvokeAzureAgentExecutor,
)
@@ -1871,7 +1872,7 @@ class TestAgentExternalLoopCoverage:
}
executor = InvokeAzureAgentExecutor(action_def, agents={"TestAgent": mock_agent})
with pytest.raises(AgentInvocationError) as exc_info:
with pytest.raises(AgentInvalidResponseException) as exc_info:
await executor.handle_action(ActionTrigger(), mock_context)
assert "TestAgent" in str(exc_info.value)
@@ -2375,11 +2376,12 @@ class TestAgentExecutorExternalLoop:
async def test_handle_external_input_response_agent_not_found(self, mock_context, mock_state):
"""Test handling external input raises error when agent not found during resumption."""
from agent_framework.exceptions import AgentInvalidRequestException
from agent_framework_declarative._workflows._executors_agents import (
EXTERNAL_LOOP_STATE_KEY,
AgentExternalInputRequest,
AgentExternalInputResponse,
AgentInvocationError,
ExternalLoopState,
InvokeAzureAgentExecutor,
)
@@ -2411,7 +2413,7 @@ class TestAgentExecutorExternalLoop:
)
response = AgentExternalInputResponse(user_input="continue")
with pytest.raises(AgentInvocationError) as exc_info:
with pytest.raises(AgentInvalidRequestException) as exc_info:
await executor.handle_external_input_response(original_request, response, mock_context)
assert "NonExistentAgent" in str(exc_info.value)
python/packages/declarative/tests/test_graph_executors.py
+4 -3
View File
@@ -415,8 +415,9 @@ class TestAgentExecutors:
@pytest.mark.asyncio
async def test_invoke_agent_not_found(self, mock_context, mock_state):
"""Test InvokeAzureAgentExecutor raises error when agent not found."""
from agent_framework.exceptions import AgentInvalidRequestException
from agent_framework_declarative._workflows import (
AgentInvocationError,
InvokeAzureAgentExecutor,
)
@@ -430,8 +431,8 @@ class TestAgentExecutors:
}
executor = InvokeAzureAgentExecutor(action_def)
# Execute - should raise AgentInvocationError
with pytest.raises(AgentInvocationError) as exc_info:
# Execute - should raise AgentInvalidRequestException
with pytest.raises(AgentInvalidRequestException) as exc_info:
await executor.handle_action(ActionTrigger(), mock_context)
assert "non_existent_agent" in str(exc_info.value)