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/copilotstudio/agent_framework_copilotstudio/_acquire_token.py
+6 -6
View File
@@ -6,7 +6,7 @@
import logging
from typing import Any
from agent_framework.exceptions import ServiceException
from agent_framework.exceptions import AgentException
from msal import PublicClientApplication
logger = logging.getLogger(__name__)
@@ -39,13 +39,13 @@ def acquire_token(
The access token string.
Raises:
ServiceException: If authentication token cannot be acquired.
AgentException: If authentication token cannot be acquired.
"""
if not client_id:
raise ServiceException("Client ID is required for token acquisition.")
raise ValueError("Client ID is required for token acquisition.")
if not tenant_id:
raise ServiceException("Tenant ID is required for token acquisition.")
raise ValueError("Tenant ID is required for token acquisition.")
authority = f"https://login.microsoftonline.com/{tenant_id}"
target_scopes = scopes or DEFAULT_SCOPES
@@ -87,9 +87,9 @@ def acquire_token(
)
except Exception as ex:
logger.error("Interactive token acquisition failed with exception: %s", ex)
raise ServiceException(f"Failed to acquire authentication token: {ex}") from ex
raise AgentException(f"Failed to acquire authentication token: {ex}") from ex
if not token:
raise ServiceException("Authentication token cannot be acquired.")
raise AgentException("Authentication token cannot be acquired.")
return token
python/packages/copilotstudio/agent_framework_copilotstudio/_agent.py
+8 -8
View File
@@ -19,7 +19,7 @@ from agent_framework import (
)
from agent_framework._settings import load_settings
from agent_framework._types import AgentRunInputs
from agent_framework.exceptions import ServiceException, ServiceInitializationError
from agent_framework.exceptions import AgentException
from microsoft_agents.copilotstudio.client import AgentType, ConnectionSettings, CopilotClient, PowerPlatformCloud
from ._acquire_token import acquire_token
@@ -113,7 +113,7 @@ class CopilotStudioAgent(BaseAgent):
env_file_encoding: Encoding of the .env file, defaults to 'utf-8'.
Raises:
ServiceInitializationError: If required configuration is missing or invalid.
ValueError: If required configuration is missing or invalid.
"""
super().__init__(
id=id,
@@ -136,12 +136,12 @@ class CopilotStudioAgent(BaseAgent):
if not settings:
if not copilot_studio_settings["environmentid"]:
raise ServiceInitializationError(
raise ValueError(
"Copilot Studio environment ID is required. Set via 'environment_id' parameter "
"or 'COPILOTSTUDIOAGENT__ENVIRONMENTID' environment variable."
)
if not copilot_studio_settings["schemaname"]:
raise ServiceInitializationError(
raise ValueError(
"Copilot Studio agent identifier/schema name is required. Set via 'agent_identifier' parameter "
"or 'COPILOTSTUDIOAGENT__SCHEMANAME' environment variable."
)
@@ -156,13 +156,13 @@ class CopilotStudioAgent(BaseAgent):
if not token:
if not copilot_studio_settings["agentappid"]:
raise ServiceInitializationError(
raise ValueError(
"Copilot Studio client ID is required. Set via 'client_id' parameter "
"or 'COPILOTSTUDIOAGENT__AGENTAPPID' environment variable."
)
if not copilot_studio_settings["tenantid"]:
raise ServiceInitializationError(
raise ValueError(
"Copilot Studio tenant ID is required. Set via 'tenant_id' parameter "
"or 'COPILOTSTUDIOAGENT__TENANTID' environment variable."
)
@@ -303,7 +303,7 @@ class CopilotStudioAgent(BaseAgent):
The conversation ID for the new conversation.
Raises:
ServiceException: If the conversation could not be started.
AgentException: If the conversation could not be started.
"""
conversation_id: str | None = None
@@ -312,7 +312,7 @@ class CopilotStudioAgent(BaseAgent):
conversation_id = activity.conversation.id
if not conversation_id:
raise ServiceException("Failed to start a new conversation.")
raise AgentException("Failed to start a new conversation.")
return conversation_id
python/packages/copilotstudio/tests/test_acquire_token.py
+11 -11
View File
@@ -3,7 +3,7 @@
from unittest.mock import MagicMock, patch
import pytest
from agent_framework.exceptions import ServiceException
from agent_framework.exceptions import AgentException
from agent_framework_copilotstudio._acquire_token import DEFAULT_SCOPES, acquire_token
@@ -12,23 +12,23 @@ class TestAcquireToken:
"""Test class for token acquisition functionality."""
def test_acquire_token_missing_client_id(self) -> None:
"""Test that acquire_token raises ServiceException when client_id is missing."""
with pytest.raises(ServiceException, match="Client ID is required for token acquisition"):
"""Test that acquire_token raises ValueError when client_id is missing."""
with pytest.raises(ValueError, match="Client ID is required for token acquisition"):
acquire_token(client_id="", tenant_id="test-tenant-id")
def test_acquire_token_missing_tenant_id(self) -> None:
"""Test that acquire_token raises ServiceException when tenant_id is missing."""
with pytest.raises(ServiceException, match="Tenant ID is required for token acquisition"):
"""Test that acquire_token raises ValueError when tenant_id is missing."""
with pytest.raises(ValueError, match="Tenant ID is required for token acquisition"):
acquire_token(client_id="test-client-id", tenant_id="")
def test_acquire_token_none_client_id(self) -> None:
"""Test that acquire_token raises ServiceException when client_id is None."""
with pytest.raises(ServiceException, match="Client ID is required for token acquisition"):
"""Test that acquire_token raises ValueError when client_id is None."""
with pytest.raises(ValueError, match="Client ID is required for token acquisition"):
acquire_token(client_id=None, tenant_id="test-tenant-id") # type: ignore
def test_acquire_token_none_tenant_id(self) -> None:
"""Test that acquire_token raises ServiceException when tenant_id is None."""
with pytest.raises(ServiceException, match="Tenant ID is required for token acquisition"):
"""Test that acquire_token raises ValueError when tenant_id is None."""
with pytest.raises(ValueError, match="Tenant ID is required for token acquisition"):
acquire_token(client_id="test-client-id", tenant_id=None) # type: ignore
@patch("agent_framework_copilotstudio._acquire_token.PublicClientApplication")
@@ -186,7 +186,7 @@ class TestAcquireToken:
mock_error_response = {"error": "access_denied", "error_description": "User denied consent"}
mock_pca.acquire_token_interactive.return_value = mock_error_response
with pytest.raises(ServiceException, match="Authentication token cannot be acquired"):
with pytest.raises(AgentException, match="Authentication token cannot be acquired"):
acquire_token(
client_id="test-client-id",
tenant_id="test-tenant-id",
@@ -203,7 +203,7 @@ class TestAcquireToken:
# Interactive acquisition throws exception
mock_pca.acquire_token_interactive.side_effect = Exception("Authentication service unavailable")
with pytest.raises(ServiceException, match="Failed to acquire authentication token"):
with pytest.raises(AgentException, match="Failed to acquire authentication token"):
acquire_token(
client_id="test-client-id",
tenant_id="test-tenant-id",
python/packages/copilotstudio/tests/test_copilot_agent.py
+9 -9
View File
@@ -5,7 +5,7 @@ from unittest.mock import MagicMock, patch
import pytest
from agent_framework import AgentResponse, AgentResponseUpdate, AgentSession, Content, Message
from agent_framework.exceptions import ServiceException, ServiceInitializationError
from agent_framework.exceptions import AgentException
from microsoft_agents.copilotstudio.client import CopilotClient
from agent_framework_copilotstudio import CopilotStudioAgent
@@ -48,7 +48,7 @@ class TestCopilotStudioAgent:
"agentappid": "test-client",
}
with pytest.raises(ServiceInitializationError, match="environment ID is required"):
with pytest.raises(ValueError, match="environment ID is required"):
CopilotStudioAgent()
@patch("agent_framework_copilotstudio._acquire_token.acquire_token")
@@ -62,7 +62,7 @@ class TestCopilotStudioAgent:
"agentappid": "test-client",
}
with pytest.raises(ServiceInitializationError, match="agent identifier"):
with pytest.raises(ValueError, match="agent identifier"):
CopilotStudioAgent()
@patch("agent_framework_copilotstudio._acquire_token.acquire_token")
@@ -76,7 +76,7 @@ class TestCopilotStudioAgent:
"agentappid": "test-client",
}
with pytest.raises(ServiceInitializationError, match="tenant ID is required"):
with pytest.raises(ValueError, match="tenant ID is required"):
CopilotStudioAgent()
@patch("agent_framework_copilotstudio._acquire_token.acquire_token")
@@ -90,7 +90,7 @@ class TestCopilotStudioAgent:
"agentappid": None,
}
with pytest.raises(ServiceInitializationError, match="client ID is required"):
with pytest.raises(ValueError, match="client ID is required"):
CopilotStudioAgent()
def test_init_with_client(self, mock_copilot_client: MagicMock) -> None:
@@ -109,7 +109,7 @@ class TestCopilotStudioAgent:
"agentappid": "test-client",
}
with pytest.raises(ServiceInitializationError, match="environment ID is required"):
with pytest.raises(ValueError, match="environment ID is required"):
CopilotStudioAgent()
@patch("agent_framework_copilotstudio._acquire_token.acquire_token")
@@ -123,7 +123,7 @@ class TestCopilotStudioAgent:
"agentappid": "test-client",
}
with pytest.raises(ServiceInitializationError, match="agent identifier"):
with pytest.raises(ValueError, match="agent identifier"):
CopilotStudioAgent()
async def test_run_with_string_message(self, mock_copilot_client: MagicMock, mock_activity: MagicMock) -> None:
@@ -188,7 +188,7 @@ class TestCopilotStudioAgent:
mock_copilot_client.start_conversation.return_value = create_async_generator([])
with pytest.raises(ServiceException, match="Failed to start a new conversation"):
with pytest.raises(AgentException, match="Failed to start a new conversation"):
await agent.run("test message")
async def test_run_streaming_with_string_message(self, mock_copilot_client: MagicMock) -> None:
@@ -315,6 +315,6 @@ class TestCopilotStudioAgent:
mock_copilot_client.start_conversation.return_value = create_async_generator([])
with pytest.raises(ServiceException, match="Failed to start a new conversation"):
with pytest.raises(AgentException, match="Failed to start a new conversation"):
async for _ in agent.run("test message", stream=True):
pass