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/github_copilot/agent_framework_github_copilot/_agent.py
+13 -13
View File
@@ -24,7 +24,7 @@ from agent_framework import (
from agent_framework._settings import load_settings
from agent_framework._tools import FunctionTool, ToolTypes
from agent_framework._types import AgentRunInputs, normalize_tools
from agent_framework.exceptions import ServiceException
from agent_framework.exceptions import AgentException
from copilot import CopilotClient, CopilotSession
from copilot.generated.session_events import SessionEvent, SessionEventType
from copilot.types import (
@@ -199,7 +199,7 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
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,
@@ -259,7 +259,7 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
agent as an async context manager.
Raises:
ServiceException: If the client fails to start.
AgentException: If the client fails to start.
"""
if self._started:
return
@@ -277,7 +277,7 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
await self._client.start()
self._started = True
except Exception as ex:
raise ServiceException(f"Failed to start GitHub Copilot client: {ex}") from ex
raise AgentException(f"Failed to start GitHub Copilot client: {ex}") from ex
async def stop(self) -> None:
"""Stop the Copilot client and clean up resources.
@@ -343,7 +343,7 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
When stream=True: A ResponseStream of AgentResponseUpdate items.
Raises:
ServiceException: If the request fails.
AgentException: If the request fails.
"""
if stream:
@@ -381,7 +381,7 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
try:
response_event = await copilot_session.send_and_wait({"prompt": prompt}, timeout=timeout)
except Exception as ex:
raise ServiceException(f"GitHub Copilot request failed: {ex}") from ex
raise AgentException(f"GitHub Copilot request failed: {ex}") from ex
response_messages: list[Message] = []
response_id: str | None = None
@@ -426,7 +426,7 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
AgentResponseUpdate items.
Raises:
ServiceException: If the request fails.
AgentException: If the request fails.
"""
if not self._started:
await self.start()
@@ -457,7 +457,7 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
queue.put_nowait(None)
elif event.type == SessionEventType.SESSION_ERROR:
error_msg = event.data.message or "Unknown error"
queue.put_nowait(ServiceException(f"GitHub Copilot session error: {error_msg}"))
queue.put_nowait(AgentException(f"GitHub Copilot session error: {error_msg}"))
unsubscribe = copilot_session.on(event_handler)
@@ -565,10 +565,10 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
A CopilotSession instance.
Raises:
ServiceException: If the session cannot be created.
AgentException: If the session cannot be created.
"""
if not self._client:
raise ServiceException("GitHub Copilot client not initialized. Call start() first.")
raise RuntimeError("GitHub Copilot client not initialized. Call start() first.")
try:
if agent_session.service_session_id:
@@ -578,7 +578,7 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
agent_session.service_session_id = session.session_id
return session
except Exception as ex:
raise ServiceException(f"Failed to create GitHub Copilot session: {ex}") from ex
raise AgentException(f"Failed to create GitHub Copilot session: {ex}") from ex
async def _create_session(
self,
@@ -592,7 +592,7 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
runtime_options: Runtime options that take precedence over default_options.
"""
if not self._client:
raise ServiceException("GitHub Copilot client not initialized. Call start() first.")
raise RuntimeError("GitHub Copilot client not initialized. Call start() first.")
opts = runtime_options or {}
config: SessionConfig = {"streaming": streaming}
@@ -621,7 +621,7 @@ class GitHubCopilotAgent(BaseAgent, Generic[OptionsT]):
async def _resume_session(self, session_id: str, streaming: bool) -> CopilotSession:
"""Resume an existing Copilot session by ID."""
if not self._client:
raise ServiceException("GitHub Copilot client not initialized. Call start() first.")
raise RuntimeError("GitHub Copilot client not initialized. Call start() first.")
config: ResumeSessionConfig = {"streaming": streaming}
python/packages/github_copilot/tests/test_github_copilot_agent.py
+10 -10
View File
@@ -14,7 +14,7 @@ from agent_framework import (
Content,
Message,
)
from agent_framework.exceptions import ServiceException
from agent_framework.exceptions import AgentException
from copilot.generated.session_events import Data, SessionEvent, SessionEventType
from agent_framework_github_copilot import GitHubCopilotAgent, GitHubCopilotOptions
@@ -430,7 +430,7 @@ class TestGitHubCopilotAgentRunStreaming:
agent = GitHubCopilotAgent(client=mock_client)
with pytest.raises(ServiceException, match="session error"):
with pytest.raises(AgentException, match="session error"):
async for _ in agent.run("Hello", stream=True):
pass
@@ -835,12 +835,12 @@ class TestGitHubCopilotAgentErrorHandling:
"""Test cases for error handling."""
async def test_start_raises_on_client_error(self, mock_client: MagicMock) -> None:
"""Test that start raises ServiceException when client fails to start."""
"""Test that start raises AgentException when client fails to start."""
mock_client.start.side_effect = Exception("Connection failed")
agent = GitHubCopilotAgent(client=mock_client)
with pytest.raises(ServiceException, match="Failed to start GitHub Copilot client"):
with pytest.raises(AgentException, match="Failed to start GitHub Copilot client"):
await agent.start()
async def test_run_raises_on_send_error(
@@ -848,33 +848,33 @@ class TestGitHubCopilotAgentErrorHandling:
mock_client: MagicMock,
mock_session: MagicMock,
) -> None:
"""Test that run raises ServiceException when send_and_wait fails."""
"""Test that run raises AgentException when send_and_wait fails."""
mock_session.send_and_wait.side_effect = Exception("Request timeout")
agent = GitHubCopilotAgent(client=mock_client)
with pytest.raises(ServiceException, match="GitHub Copilot request failed"):
with pytest.raises(AgentException, match="GitHub Copilot request failed"):
await agent.run("Hello")
async def test_get_or_create_session_raises_on_create_error(
self,
mock_client: MagicMock,
) -> None:
"""Test that _get_or_create_session raises ServiceException when create_session fails."""
"""Test that _get_or_create_session raises AgentException when create_session fails."""
mock_client.create_session.side_effect = Exception("Session creation failed")
agent = GitHubCopilotAgent(client=mock_client)
await agent.start()
with pytest.raises(ServiceException, match="Failed to create GitHub Copilot session"):
with pytest.raises(AgentException, match="Failed to create GitHub Copilot session"):
await agent._get_or_create_session(AgentSession()) # type: ignore
async def test_get_or_create_session_raises_when_client_not_initialized(self) -> None:
"""Test that _get_or_create_session raises ServiceException when client is not initialized."""
"""Test that _get_or_create_session raises RuntimeError when client is not initialized."""
agent = GitHubCopilotAgent()
# Don't call start() - client remains None
with pytest.raises(ServiceException, match="GitHub Copilot client not initialized"):
with pytest.raises(RuntimeError, match="GitHub Copilot client not initialized"):
await agent._get_or_create_session(AgentSession()) # type: ignore