diff --git a/examples/demos/procurement_agent/project/workflow.py b/examples/demos/procurement_agent/project/workflow.py index 115c2d2f6..f5ab413fb 100644 --- a/examples/demos/procurement_agent/project/workflow.py +++ b/examples/demos/procurement_agent/project/workflow.py @@ -129,21 +129,27 @@ async def on_task_event_send(self, params: SendEventParams) -> None: First event: Triggers the initial agent workflow execution. Subsequent events: Feed the wait_for_human tool's human_queue. """ - if self._state is None: - raise ValueError("State is not initialized") - - if params.event.content is None: + # Skip events this agent can't handle instead of raising: an exception here fails + # the workflow task, and Temporal replays the signal forever, wedging the task. + # Any content type can be displayed, but an event can arrive with no content. + content = params.event.content + if content is None: workflow.logger.warning("Received event with no content") return + # A signal can arrive before on_task_create has initialised state (e.g. with + # signal-with-start): wait for it rather than drop the user's message. + while self._state is None: + await workflow.wait_condition(lambda: self._state is not None) + # Display the user's message in the UI - await adk.messages.create(task_id=params.task.id, content=params.event.content) + await adk.messages.create(task_id=params.task.id, content=content) # After the first event, all subsequent events are human responses to wait_for_human if self._workflow_started: # Extract text content and put it in the human_queue for wait_for_human tool - if isinstance(params.event.content, TextContent): - await self.human_queue.put(params.event.content.content) + if isinstance(content, TextContent): + await self.human_queue.put(content.content) @workflow.run @override @@ -386,38 +392,44 @@ async def send_event(self, event: str) -> None: Receives event strings from external systems with validation. Events should be JSON strings with event_type and required fields. Example: {"event_type":"Submittal_Approved","item":"Steel Beams"} + + Invalid events are logged and dropped, never raised: an exception in a signal + handler fails the workflow task, and Temporal replays the signal forever. The + sender never sees the error either way, since signals do not return results. """ # Validate event is not None or empty if not event: logger.error("Received empty or None event") - raise ValueError("Event cannot be empty or None") + return # Validate event is a string if not isinstance(event, str): logger.error(f"Event must be string, got {type(event)}") - raise ValueError(f"Event must be a string, received {type(event).__name__}") + return # Validate event length (prevent DoS) if len(event) > 50000: # 50KB limit logger.error(f"Event too large: {len(event)} characters") - raise ValueError(f"Event exceeds maximum size (50KB)") + return - # Validate event is valid JSON + # Validate event is valid JSON. Catch ValueError, not just its subclass JSONDecodeError: an integer + # literal longer than Python's int digit limit raises a plain ValueError, and deeply nested input + # raises RecursionError. try: event_data = json.loads(event) - except json.JSONDecodeError as e: + except (ValueError, RecursionError) as e: logger.error(f"Event is not valid JSON: {e}") - raise ValueError(f"Event must be valid JSON: {e}") from e + return # Validate event has required structure if not isinstance(event_data, dict): logger.error(f"Event JSON must be an object, got {type(event_data)}") - raise ValueError("Event must be a JSON object") + return # Validate event_type field exists if "event_type" not in event_data: logger.error("Event missing 'event_type' field") - raise ValueError("Event must contain 'event_type' field") + return # Validate event_type is one of the allowed types event_type_str = event_data["event_type"] @@ -425,10 +437,7 @@ async def send_event(self, event: str) -> None: if event_type_str not in valid_event_types: logger.error(f"Invalid event_type: {event_type_str}. Valid types: {valid_event_types}") - raise ValueError( - f"Invalid event_type '{event_type_str}'. " - f"Must be one of: {', '.join(valid_event_types)}" - ) + return # Validate event structure based on type using Pydantic models try: @@ -448,7 +457,7 @@ async def send_event(self, event: str) -> None: except Exception as e: logger.error(f"Event validation failed for {event_type_str}: {e}") - raise ValueError(f"Invalid event structure for {event_type_str}: {e}") from e + return logger.info(f"Validated event type: {event_type_str}") await self.event_queue.put(event) \ No newline at end of file diff --git a/examples/tutorials/10_async/10_temporal/000_hello_acp/conftest.py b/examples/tutorials/10_async/10_temporal/000_hello_acp/conftest.py new file mode 100644 index 000000000..3dab9c4a9 --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/000_hello_acp/conftest.py @@ -0,0 +1,46 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at000-hello-acp", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at000-hello-acp", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/000_hello_acp/project/workflow.py b/examples/tutorials/10_async/10_temporal/000_hello_acp/project/workflow.py index e45ecd897..3e2191092 100644 --- a/examples/tutorials/10_async/10_temporal/000_hello_acp/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/000_hello_acp/project/workflow.py @@ -33,10 +33,18 @@ def __init__(self): @workflow.signal(name=SignalName.RECEIVE_EVENT) @override async def on_task_event_send(self, params: SendEventParams) -> None: + # Skip events this agent can't handle instead of raising: an exception here fails + # the workflow task, and Temporal replays the signal forever, wedging the task. + # Any content type can be echoed back, but an event can arrive with no content. + content = params.event.content + if content is None: + logger.warning("Ignoring event with no content for task %s", params.task.id) + return + logger.info(f"Received task message instruction: {params}") # 2. Echo back the client's message to show it in the UI. This is not done by default so the agent developer has full control over what is shown to the user. - await adk.messages.create(task_id=params.task.id, content=params.event.content) + await adk.messages.create(task_id=params.task.id, content=content) # 3. Send a simple response message. # In future tutorials, this is where we'll add more sophisticated response logic. diff --git a/examples/tutorials/10_async/10_temporal/000_hello_acp/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/000_hello_acp/tests/test_agent.py index 65204ac36..e27f5bfc3 100644 --- a/examples/tutorials/10_async/10_temporal/000_hello_acp/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/000_hello_acp/tests/test_agent.py @@ -5,6 +5,9 @@ - Non-streaming event sending and polling - Streaming event sending +It also unit-tests the workflow's signal handler offline (TestOfflineSignalHandler), +which needs no running agent, Temporal or network. + To run these tests: 1. Make sure the agent is running (via docker-compose or `agentex agents run`) 2. Set the AGENTEX_API_BASE_URL environment variable if not using default @@ -19,6 +22,8 @@ import uuid import asyncio from typing import Any +from datetime import datetime, timezone +from unittest.mock import AsyncMock, patch import pytest import pytest_asyncio @@ -30,8 +35,17 @@ from agentex import AsyncAgentex from agentex.types import TaskMessage +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent +from agentex.types.text_content import TextContent from agentex.types.agent_rpc_params import ParamsCreateTaskRequest +from agentex.types.reasoning_content import ReasoningContent from agentex.types.text_content_param import TextContentParam +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent # Configuration from environment variables AGENTEX_API_BASE_URL = os.environ.get("AGENTEX_API_BASE_URL", "http://localhost:5003") @@ -185,5 +199,87 @@ async def stream_messages() -> None: assert user_echo_found, "User message echo not found in stream" assert agent_response_found, "Agent response not found in stream" + +# --------------------------------------------------------------------------- +# Offline signal-handler tests (no running agent, Temporal or network needed) +# --------------------------------------------------------------------------- + +TASK_ID = "task-offline-1" + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id=TASK_ID), + event=Event(id="event-1", agent_id="agent-1", task_id=TASK_ID, sequence_id=1, content=content), + ) + + +# Every content type a caller can send. This handler only echoes the content back, so +# all of them are valid input: the one thing it cannot echo is an event with no content. +ECHOED_CONTENTS = [ + pytest.param(TextContent(author="user", content="Hello!"), id="text"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="get_weather", tool_call_id="call-1", arguments={"city": "Paris"}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +class TestOfflineSignalHandler: + """Unit tests for ``on_task_event_send`` that need no running agent, Temporal or network. + + The handler is called directly with real ``SendEventParams``; ``adk.messages.create`` + is mocked, so nothing leaves the process. + """ + + @staticmethod + def _workflow(): + from project.workflow import At000HelloAcpWorkflow + + # Build the instance without Temporal: skip __init__ and set what it would set. + wf = At000HelloAcpWorkflow.__new__(At000HelloAcpWorkflow) + wf.display_name = AGENT_NAME + wf._complete_task = False + return wf + + @pytest.mark.asyncio + async def test_event_without_content_is_ignored(self): + """No content: return without raising (that would wedge the task) and send nothing.""" + with patch("project.workflow.adk.messages.create", new=AsyncMock()) as create: + wf = self._workflow() + await wf.on_task_event_send(_send_event_params(None)) + + create.assert_not_awaited() + assert wf._complete_task is False + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", ECHOED_CONTENTS) + async def test_event_is_echoed_then_answered(self, content): + """Any content type is echoed back unchanged, then the agent replies.""" + with patch("project.workflow.adk.messages.create", new=AsyncMock()) as create: + wf = self._workflow() + await wf.on_task_event_send(_send_event_params(content)) + + assert create.await_count == 2 + echo, reply = create.await_args_list + assert echo.kwargs == {"task_id": TASK_ID, "content": content} + assert reply.kwargs["task_id"] == TASK_ID + assert isinstance(reply.kwargs["content"], TextContent) + assert reply.kwargs["content"].author == "agent" + + if __name__ == "__main__": pytest.main([__file__, "-v"]) \ No newline at end of file diff --git a/examples/tutorials/10_async/10_temporal/010_agent_chat/conftest.py b/examples/tutorials/10_async/10_temporal/010_agent_chat/conftest.py new file mode 100644 index 000000000..72159f5f5 --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/010_agent_chat/conftest.py @@ -0,0 +1,46 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at010-agent-chat", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at010-agent-chat", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/010_agent_chat/project/workflow.py b/examples/tutorials/10_async/10_temporal/010_agent_chat/project/workflow.py index 7db940733..8286b0095 100644 --- a/examples/tutorials/10_async/10_temporal/010_agent_chat/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/010_agent_chat/project/workflow.py @@ -166,26 +166,38 @@ def __init__(self): @workflow.signal(name=SignalName.RECEIVE_EVENT) @override async def on_task_event_send(self, params: SendEventParams) -> None: - logger.info(f"Received task message instruction: {params}") - - if not params.event.content: + # Skip events this agent can't handle instead of raising: an exception here + # fails the workflow task, and Temporal replays the signal forever, wedging the + # task. Content can be missing, a non-text type, or not written by the user. + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", + params.task.id, + getattr(content, "type", None), + ) return - if params.event.content.type != "text": - raise ValueError(f"Expected text message, got {params.event.content.type}") - if params.event.content.author != "user": - raise ValueError( - f"Expected user message, got {params.event.content.author}" + if content.author != "user": + logger.warning( + "Ignoring non-user event for task %s (author=%s)", + params.task.id, + content.author, ) + return + + logger.info(f"Received task message instruction: {params}") - if self._state is None: - raise ValueError("State is not initialized") + # A signal can arrive before on_task_create has initialised the state (e.g. + # with signal-with-start): wait for it rather than drop the user's message. + while self._state is None: + await workflow.wait_condition(lambda: self._state is not None) # Increment the turn number self._state.turn_number += 1 # Add the new user message to the message history self._state.input_list.append( - {"role": "user", "content": params.event.content.content} + {"role": "user", "content": content.content} ) async with adk.tracing.span( @@ -197,7 +209,7 @@ async def on_task_event_send(self, params: SendEventParams) -> None: await adk.messages.create( task_id=params.task.id, trace_id=params.task.id, - content=params.event.content, + content=content, parent_span_id=span.id if span else None, ) diff --git a/examples/tutorials/10_async/10_temporal/010_agent_chat/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/010_agent_chat/tests/test_agent.py index f8c3e1aa8..4dd5a8d5e 100644 --- a/examples/tutorials/10_async/10_temporal/010_agent_chat/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/010_agent_chat/tests/test_agent.py @@ -19,6 +19,9 @@ 3. Ensure OPENAI_API_KEY is set in the environment 4. Run: pytest test_agent.py -v +The workflow's signal handler is also unit-tested offline (TestOfflineSignalHandler); +those tests need no running agent, Temporal, network or API key. + Configuration: - AGENTEX_API_BASE_URL: Base URL for the AgentEx server (default: http://localhost:5003) - AGENT_NAME: Name of the agent to test (default: at010-agent-chat) @@ -27,6 +30,11 @@ import os import uuid import asyncio +from types import SimpleNamespace +from typing import Any +from datetime import datetime, timezone +from contextlib import contextmanager +from unittest.mock import AsyncMock, patch import pytest import pytest_asyncio @@ -37,9 +45,17 @@ from agentex import AsyncAgentex from agentex.types import TaskMessage, TextContent +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent from agentex.types.agent_rpc_params import ParamsCreateTaskRequest from agentex.types.agent_rpc_result import StreamTaskMessageDone, StreamTaskMessageFull +from agentex.types.reasoning_content import ReasoningContent from agentex.types.text_content_param import TextContentParam +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent # Configuration from environment variables AGENTEX_API_BASE_URL = os.environ.get("AGENTEX_API_BASE_URL", "http://localhost:5003") @@ -273,5 +289,141 @@ async def stream_messages() -> None: assert agent_response_found, "Agent response not found in stream" +# --------------------------------------------------------------------------- +# Offline signal-handler tests (no running agent, Temporal, network or API key) +# --------------------------------------------------------------------------- + +TASK_ID = "task-offline-1" +USER_TEXT = TextContent(author="user", content="What is 2 + 2?") + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id=TASK_ID), + event=Event(id="event-1", agent_id="agent-1", task_id=TASK_ID, sequence_id=1, content=content), + ) + + +# Event content a caller can send that this handler must not process: Event.content is +# optional, only TextContent carries text, and the agent only answers user messages. +IGNORED_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="calculator", tool_call_id="call-1", arguments={"a": 1}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="calculator", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="calculator", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), + pytest.param(TextContent(author="agent", content="I am not the user"), id="agent-text"), +] + + +class _FakeSpan: + id = "span-offline-1" + output: Any = None + + async def __aenter__(self): + return self + + async def __aexit__(self, *exc_info): + return False + + +@contextmanager +def _mock_adk(): + """Mock the ``adk`` calls the handler makes, so nothing leaves the process.""" + run_result = SimpleNamespace( + final_input_list=[ + {"role": "user", "content": USER_TEXT.content}, + {"role": "assistant", "content": "4"}, + ] + ) + with patch("project.workflow.adk.messages.create", new=AsyncMock()) as create, patch( + "project.workflow.adk.tracing.span", return_value=_FakeSpan() + ) as span, patch( + "project.workflow.adk.providers.openai.run_agent_streamed_auto_send", + new=AsyncMock(return_value=run_result), + ) as run_agent: + yield create, span, run_agent + + +class TestOfflineSignalHandler: + """Unit tests for ``on_task_event_send``, called directly with real ``SendEventParams``.""" + + @staticmethod + def _workflow(): + from project.workflow import StateModel, At010AgentChatWorkflow + + # Build the instance without Temporal: skip __init__ and set what it would set, + # plus the state on_task_create initialises. + wf = At010AgentChatWorkflow.__new__(At010AgentChatWorkflow) + wf.display_name = AGENT_NAME + wf._complete_task = False + wf._state = StateModel(input_list=[], turn_number=0) + return wf + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", IGNORED_CONTENTS) + async def test_unprocessable_event_is_ignored(self, content): + """Return without raising (that would wedge the task) and without side effects.""" + with _mock_adk() as (create, span, run_agent): + wf = self._workflow() + await wf.on_task_event_send(_send_event_params(content)) + + create.assert_not_awaited() + span.assert_not_called() + run_agent.assert_not_awaited() + assert wf._state.turn_number == 0 + assert wf._state.input_list == [] + + @pytest.mark.asyncio + async def test_user_text_event_runs_a_turn(self): + """A user text event is echoed, added to the history and answered by the agent.""" + with _mock_adk() as (create, span, run_agent): + wf = self._workflow() + await wf.on_task_event_send(_send_event_params(USER_TEXT)) + + assert wf._state.turn_number == 1 + span.assert_called_once() + # The first message is the echo of the user's own message. + assert create.await_args_list[0].kwargs["content"] == USER_TEXT + run_agent.assert_awaited_once() + assert run_agent.await_args.kwargs["input_list"] == [{"role": "user", "content": USER_TEXT.content}] + assert wf._state.input_list == run_agent.return_value.final_input_list + + @pytest.mark.asyncio + async def test_event_before_state_is_initialised_waits_for_it(self): + """An event handled before on_task_create has run waits for the state, not raises.""" + from project.workflow import StateModel + + wf = self._workflow() + wf._state = None + + async def _wait_condition(condition): + assert not condition() + wf._state = StateModel(input_list=[], turn_number=0) # on_task_create runs + assert condition() + + with _mock_adk() as (create, _span, _run_agent), patch( + "project.workflow.workflow.wait_condition", new=AsyncMock(side_effect=_wait_condition) + ) as wait_condition: + await wf.on_task_event_send(_send_event_params(USER_TEXT)) + + wait_condition.assert_awaited_once() + assert wf._state.turn_number == 1 + assert create.await_args_list[0].kwargs["content"] == USER_TEXT + + if __name__ == "__main__": pytest.main([__file__, "-v"]) diff --git a/examples/tutorials/10_async/10_temporal/020_state_machine/conftest.py b/examples/tutorials/10_async/10_temporal/020_state_machine/conftest.py new file mode 100644 index 000000000..0057c93aa --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/020_state_machine/conftest.py @@ -0,0 +1,46 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at020-state-machine", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at020-state-machine", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/020_state_machine/project/workflow.py b/examples/tutorials/10_async/10_temporal/020_state_machine/project/workflow.py index aa88de687..1931e6cc5 100644 --- a/examples/tutorials/10_async/10_temporal/020_state_machine/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/020_state_machine/project/workflow.py @@ -48,9 +48,18 @@ def __init__(self): @override @workflow.signal(name=SignalName.RECEIVE_EVENT) async def on_task_event_send(self, params: SendEventParams) -> None: + # Skip events this agent can't handle instead of raising: an exception here fails + # the workflow task, and Temporal replays the signal forever, wedging the task. + # Content can be missing or a non-text type (data, tool request/response, ...). + message = params.event.content + if not isinstance(message, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", params.task.id, getattr(message, "type", None) + ) + return + deep_research_data = self.state_machine.get_state_machine_data() task = params.task - message = params.event.content # If waiting for user input, handle the message if self.state_machine.get_current_state() == DeepResearchState.WAITING_FOR_USER_INPUT: diff --git a/examples/tutorials/10_async/10_temporal/020_state_machine/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/020_state_machine/tests/test_agent.py index fac8605aa..08b4de742 100644 --- a/examples/tutorials/10_async/10_temporal/020_state_machine/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/020_state_machine/tests/test_agent.py @@ -19,6 +19,9 @@ 3. Ensure OPENAI_API_KEY is set in the environment 4. Run: pytest test_agent.py -v +The workflow's signal handler is also unit-tested offline (TestOfflineSignalHandler); +those tests need no running agent, Temporal, network or API key. + Configuration: - AGENTEX_API_BASE_URL: Base URL for the AgentEx server (default: http://localhost:5003) - AGENT_NAME: Name of the agent to test (default: at020-state-machine) @@ -27,6 +30,9 @@ import os import uuid import asyncio +from typing import Any +from datetime import datetime, timezone +from unittest.mock import AsyncMock, patch import pytest import pytest_asyncio @@ -36,9 +42,18 @@ ) from agentex import AsyncAgentex +from agentex.types.span import Span +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent +from agentex.types.text_content import TextContent from agentex.types.agent_rpc_params import ParamsCreateTaskRequest +from agentex.types.reasoning_content import ReasoningContent from agentex.types.text_content_param import TextContentParam from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent # Configuration from environment variables AGENTEX_API_BASE_URL = os.environ.get("AGENTEX_API_BASE_URL", "http://localhost:5003") @@ -189,5 +204,115 @@ async def stream_second_turn() -> None: assert uses_tool_requests, "Did not use tool requests" +# --------------------------------------------------------------------------- +# Offline signal-handler tests (no running agent, Temporal, network or API key) +# --------------------------------------------------------------------------- + +TASK_ID = "task-offline-1" +USER_TEXT = TextContent(author="user", content="Research the history of solid-state batteries") + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id=TASK_ID), + event=Event(id="event-1", agent_id="agent-1", task_id=TASK_ID, sequence_id=1, content=content), + ) + + +# Event content a caller can send that this handler must not process: Event.content is +# optional, and only TextContent carries the text the research is about. +IGNORED_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="web_search", tool_call_id="call-1", arguments={"query": "x"}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="web_search", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="web_search", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +class TestOfflineSignalHandler: + """Unit tests for ``on_task_event_send``, called directly with real ``SendEventParams``.""" + + @staticmethod + def _workflow(): + from project.workflow import At020StateMachineWorkflow + from project.state_machines.deep_research import DeepResearchData, DeepResearchState, DeepResearchStateMachine + from project.workflows.deep_research.clarify_user_query import ClarifyUserQueryWorkflow + from project.workflows.deep_research.waiting_for_user_input import WaitingForUserInputWorkflow + from project.workflows.deep_research.performing_deep_research import PerformingDeepResearchWorkflow + + from agentex.lib.sdk.state_machine.state import State + + # Build the instance without Temporal: skip __init__ and set what it would set. + wf = At020StateMachineWorkflow.__new__(At020StateMachineWorkflow) + wf.display_name = AGENT_NAME + wf.state_machine = DeepResearchStateMachine( + initial_state=DeepResearchState.WAITING_FOR_USER_INPUT, + states=[ + State(name=DeepResearchState.CLARIFYING_USER_QUERY, workflow=ClarifyUserQueryWorkflow()), + State(name=DeepResearchState.WAITING_FOR_USER_INPUT, workflow=WaitingForUserInputWorkflow()), + State(name=DeepResearchState.PERFORMING_DEEP_RESEARCH, workflow=PerformingDeepResearchWorkflow()), + ], + state_machine_data=DeepResearchData(), + trace_transitions=True, + ) + return wf + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", IGNORED_CONTENTS) + async def test_unprocessable_event_is_ignored(self, content): + """Return without raising (that would wedge the task) and without side effects.""" + from project.state_machines.deep_research import DeepResearchData, DeepResearchState + + with patch("project.workflow.adk.messages.create", new=AsyncMock()) as create, patch( + "project.workflow.adk.tracing.start_span", new=AsyncMock() + ) as start_span: + wf = self._workflow() + await wf.on_task_event_send(_send_event_params(content)) + + create.assert_not_awaited() + start_span.assert_not_awaited() + assert wf.state_machine.get_current_state() == DeepResearchState.WAITING_FOR_USER_INPUT + assert wf.state_machine.get_state_machine_data() == DeepResearchData() + + @pytest.mark.asyncio + async def test_user_text_event_starts_clarifying_the_query(self): + """The first user message becomes the research query and moves the state machine on.""" + from project.state_machines.deep_research import DeepResearchState + + span = Span(id="span-offline-1", name="Turn 2", start_time=datetime.now(timezone.utc), trace_id=TASK_ID) + with patch("project.workflow.adk.messages.create", new=AsyncMock()) as create, patch( + "project.workflow.adk.tracing.start_span", new=AsyncMock(return_value=span) + ) as start_span: + wf = self._workflow() + await wf.on_task_event_send(_send_event_params(USER_TEXT)) + + data = wf.state_machine.get_state_machine_data() + assert data is not None + assert data.user_query == USER_TEXT.content + assert data.current_turn == 2 + start_span.assert_awaited_once() + assert start_span.await_args.kwargs["input"] == {"task_id": TASK_ID, "message": USER_TEXT.content} + assert data.current_span is span + assert wf.state_machine.get_current_state() == DeepResearchState.CLARIFYING_USER_QUERY + # The user's message is echoed back under the turn's span. + create.assert_awaited_once() + assert create.await_args.kwargs["content"] == TextContent(author="user", content=USER_TEXT.content) + assert create.await_args.kwargs["parent_span_id"] == span.id + + if __name__ == "__main__": pytest.main([__file__, "-v"]) diff --git a/examples/tutorials/10_async/10_temporal/030_custom_activities/conftest.py b/examples/tutorials/10_async/10_temporal/030_custom_activities/conftest.py new file mode 100644 index 000000000..94113f34c --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/030_custom_activities/conftest.py @@ -0,0 +1,46 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at030-custom-activities", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at030-custom-activities", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/030_custom_activities/project/workflow.py b/examples/tutorials/10_async/10_temporal/030_custom_activities/project/workflow.py index 0fa85bbb9..a8bd8269f 100644 --- a/examples/tutorials/10_async/10_temporal/030_custom_activities/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/030_custom_activities/project/workflow.py @@ -16,6 +16,7 @@ CompleteWorkflowActivityParams, ) from agentex.lib.utils.logging import make_logger +from agentex.types.data_content import DataContent from agentex.types.text_content import TextContent from agentex.lib.environment_variables import EnvironmentVariables from agentex.lib.core.temporal.types.workflow import SignalName @@ -54,26 +55,35 @@ def __init__(self): self._incoming_queue: asyncio.Queue[Any] = asyncio.Queue() self._processing_tasks: List[asyncio.Task[Any]] = [] self._batch_size = BATCH_SIZE - self._state: StateModel + # None until on_task_create runs: a signal can be handled before that (e.g. with + # signal-with-start), so the handler below must not assume the state exists. + self._state: StateModel | None = None @workflow.signal(name=SignalName.RECEIVE_EVENT) @override async def on_task_event_send(self, params: SendEventParams) -> None: - if params.event.content is None: + # Skip events this agent can't handle instead of raising: an exception here fails + # the workflow task, and Temporal replays the signal forever, wedging the task. + # Text events are queued for batch processing; data events control the queue. + content = params.event.content + if not isinstance(content, (TextContent, DataContent)): + logger.warning( + "Ignoring unsupported event for task %s (type=%s)", params.task.id, getattr(content, "type", None) + ) return - if params.event.content.type == "text": + if isinstance(content, TextContent): if self._incoming_queue.qsize() >= MAX_QUEUE_DEPTH: logger.warning(f"Queue is at max depth of {MAX_QUEUE_DEPTH}. Dropping event.") if self._state: self._state.total_events_dropped += 1 else: - await self._incoming_queue.put(params.event.content) + await self._incoming_queue.put(content) return - elif params.event.content.type == "data": - received_data = params.event.content.data + else: # DataContent: controls the queue + received_data = content.data try: received_data = IncomingEventData.model_validate(received_data) except Exception as e: @@ -87,8 +97,6 @@ async def on_task_event_send(self, params: SendEventParams) -> None: await BatchProcessingUtils.handle_task_cancellation(self._processing_tasks, params.task.id) else: logger.info(f"Received IncomingEventData: {received_data} with no known action.") - else: - logger.info(f"Received event: {params.event.content} with no action.") @workflow.run diff --git a/examples/tutorials/10_async/10_temporal/030_custom_activities/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/030_custom_activities/tests/test_agent.py index b839332c7..31c8d8f78 100644 --- a/examples/tutorials/10_async/10_temporal/030_custom_activities/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/030_custom_activities/tests/test_agent.py @@ -5,6 +5,9 @@ - Non-streaming event sending and polling - Streaming event sending +It also unit-tests the workflow's signal handler offline (TestOfflineSignalHandler), +which needs no running agent, Temporal or network. + To run these tests: 1. Make sure the agent is running (via docker-compose or `agentex agents run`) 2. Set the AGENTEX_API_BASE_URL environment variable if not using default @@ -16,11 +19,25 @@ """ import os +import asyncio +from typing import Any +from datetime import datetime, timezone +from contextlib import contextmanager +from unittest.mock import AsyncMock, patch import pytest import pytest_asyncio from agentex import AsyncAgentex +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent +from agentex.types.text_content import TextContent +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent # Configuration from environment variables AGENTEX_API_BASE_URL = os.environ.get("AGENTEX_API_BASE_URL", "http://localhost:5003") @@ -132,5 +149,138 @@ async def test_send_event_and_stream(self, client: AsyncAgentex, agent_id: str): pass +# --------------------------------------------------------------------------- +# Offline signal-handler tests (no running agent, Temporal or network needed) +# --------------------------------------------------------------------------- + +TASK_ID = "task-offline-1" +USER_TEXT = TextContent(author="user", content="Hello what can you do? EVENT NUM: 0") + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id=TASK_ID), + event=Event(id="event-1", agent_id="agent-1", task_id=TASK_ID, sequence_id=1, content=content), + ) + + +# Event content a caller can send that this handler must not act on: Event.content is +# optional, only text events are queued, and data events only act on known controls. +IGNORED_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data-no-action"), + pytest.param(DataContent(author="user", data={"unexpected": {"nested": [1, 2]}}), id="data-unexpected-keys"), + pytest.param(DataContent(author="user", data={"clear_queue": "not-a-bool"}), id="data-invalid-value"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="process", tool_call_id="call-1", arguments={"a": 1}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="process", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="process", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +@contextmanager +def _mock_side_effects(): + """Mock what the handler can trigger, so nothing leaves the process.""" + with patch("project.workflow.adk.messages.create", new=AsyncMock()) as create, patch( + "project.workflow.BatchProcessingUtils.handle_queue_clear", new=AsyncMock() + ) as clear_queue, patch( + "project.workflow.BatchProcessingUtils.handle_task_cancellation", new=AsyncMock() + ) as cancel_tasks: + yield create, clear_queue, cancel_tasks + + +class TestOfflineSignalHandler: + """Unit tests for ``on_task_event_send``, called directly with real ``SendEventParams``.""" + + @staticmethod + def _workflow(): + from project.workflow import BATCH_SIZE, At030CustomActivitiesWorkflow + + # Build the instance without Temporal: skip __init__ and set what it would set. + wf = At030CustomActivitiesWorkflow.__new__(At030CustomActivitiesWorkflow) + wf.display_name = AGENT_NAME + wf._incoming_queue = asyncio.Queue() + wf._processing_tasks = [] + wf._batch_size = BATCH_SIZE + wf._state = None + return wf + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", IGNORED_CONTENTS) + async def test_unprocessable_event_is_ignored(self, content): + """Return without raising (that would wedge the task) and without side effects.""" + with _mock_side_effects() as (create, clear_queue, cancel_tasks): + wf = self._workflow() + await wf.on_task_event_send(_send_event_params(content)) + + assert wf._incoming_queue.qsize() == 0 + create.assert_not_awaited() + clear_queue.assert_not_awaited() + cancel_tasks.assert_not_awaited() + + @pytest.mark.asyncio + async def test_text_event_is_queued_for_batch_processing(self): + with _mock_side_effects() as (create, _clear_queue, _cancel_tasks): + wf = self._workflow() + await wf.on_task_event_send(_send_event_params(USER_TEXT)) + + assert wf._incoming_queue.qsize() == 1 + assert wf._incoming_queue.get_nowait() == USER_TEXT + create.assert_not_awaited() + + @pytest.mark.asyncio + async def test_data_event_runs_the_queue_controls(self): + content = DataContent(author="user", data={"clear_queue": True, "cancel_running_tasks": True}) + with _mock_side_effects() as (_create, clear_queue, cancel_tasks): + wf = self._workflow() + await wf.on_task_event_send(_send_event_params(content)) + + clear_queue.assert_awaited_once_with(wf._incoming_queue, TASK_ID) + cancel_tasks.assert_awaited_once_with(wf._processing_tasks, TASK_ID) + + @pytest.mark.asyncio + async def test_text_event_on_a_full_queue_before_task_create_is_dropped(self): + """A full queue drops the event without raising, even before on_task_create ran.""" + from project.workflow import MAX_QUEUE_DEPTH, At030CustomActivitiesWorkflow + + # The real __init__ this time: the state it leaves behind is what is under test. + wf = At030CustomActivitiesWorkflow() + for _ in range(MAX_QUEUE_DEPTH): + wf._incoming_queue.put_nowait(USER_TEXT) + + with _mock_side_effects(): + await wf.on_task_event_send(_send_event_params(USER_TEXT)) + + assert wf._incoming_queue.qsize() == MAX_QUEUE_DEPTH + + @pytest.mark.asyncio + async def test_text_event_on_a_full_queue_is_counted_as_dropped(self): + from project.workflow import MAX_QUEUE_DEPTH + from project.shared_models import StateModel + + wf = self._workflow() + wf._state = StateModel() + for _ in range(MAX_QUEUE_DEPTH): + wf._incoming_queue.put_nowait(USER_TEXT) + + with _mock_side_effects(): + await wf.on_task_event_send(_send_event_params(USER_TEXT)) + + assert wf._incoming_queue.qsize() == MAX_QUEUE_DEPTH + assert wf._state.total_events_dropped == 1 + + if __name__ == "__main__": pytest.main([__file__, "-v"]) \ No newline at end of file diff --git a/examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails/conftest.py b/examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails/conftest.py new file mode 100644 index 000000000..630267014 --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails/conftest.py @@ -0,0 +1,46 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at050-agent-chat-guardrails", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at050-agent-chat-guardrails", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails/project/workflow.py b/examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails/project/workflow.py index b54c8fade..285513c3e 100644 --- a/examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails/project/workflow.py @@ -359,21 +359,35 @@ def __init__(self): @workflow.signal(name=SignalName.RECEIVE_EVENT) @override async def on_task_event_send(self, params: SendEventParams) -> None: - if not params.event.content: + # Skip events this agent can't handle instead of raising: an exception here + # fails the workflow task, and Temporal replays the signal forever, wedging the + # task. Content can be missing, a non-text type, or not written by the user. + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", + params.task.id, + getattr(content, "type", None), + ) return - if params.event.content.type != "text": - raise ValueError(f"Expected text message, got {params.event.content.type}") - if params.event.content.author != "user": - raise ValueError(f"Expected user message, got {params.event.content.author}") + if content.author != "user": + logger.warning( + "Ignoring non-user event for task %s (author=%s)", + params.task.id, + content.author, + ) + return - if self._state is None: - raise ValueError("State is not initialized") + # A signal can arrive before on_task_create has initialised the state (e.g. + # with signal-with-start): wait for it rather than drop the user's message. + while self._state is None: + await workflow.wait_condition(lambda: self._state is not None) # Increment the turn number self._state.turn_number += 1 # Add the new user message to the message history - self._state.input_list.append({"role": "user", "content": params.event.content.content}) + self._state.input_list.append({"role": "user", "content": content.content}) async with adk.tracing.span( trace_id=params.task.id, @@ -386,7 +400,7 @@ async def on_task_event_send(self, params: SendEventParams) -> None: await adk.messages.create( task_id=params.task.id, trace_id=params.task.id, - content=params.event.content, + content=content, parent_span_id=span.id if span else None, ) diff --git a/examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails/tests/test_agent.py index 1b1f7a400..e93a36678 100644 --- a/examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/050_agent_chat_guardrails/tests/test_agent.py @@ -5,6 +5,9 @@ - Non-streaming event sending and polling - Streaming event sending +It also unit-tests the workflow's signal handler offline (TestOfflineSignalHandler), +which needs no running agent, Temporal, network or API key. + To run these tests: 1. Make sure the agent is running (via docker-compose or `agentex agents run`) 2. Set the AGENTEX_API_BASE_URL environment variable if not using default @@ -16,11 +19,25 @@ """ import os +from types import SimpleNamespace +from typing import Any +from datetime import datetime, timezone +from contextlib import contextmanager +from unittest.mock import AsyncMock, patch import pytest import pytest_asyncio from agentex import AsyncAgentex +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent +from agentex.types.text_content import TextContent +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent # Configuration from environment variables AGENTEX_API_BASE_URL = os.environ.get("AGENTEX_API_BASE_URL", "http://localhost:5003") @@ -132,5 +149,144 @@ async def test_send_event_and_stream(self, client: AsyncAgentex, agent_id: str): pass +# --------------------------------------------------------------------------- +# Offline signal-handler tests (no running agent, Temporal, network or API key) +# --------------------------------------------------------------------------- + +TASK_ID = "task-offline-1" +USER_TEXT = TextContent(author="user", content="What is 2 + 2?") + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id=TASK_ID), + event=Event(id="event-1", agent_id="agent-1", task_id=TASK_ID, sequence_id=1, content=content), + ) + + +# Event content a caller can send that this handler must not process: Event.content is +# optional, only TextContent carries text, and the agent only answers user messages. +IGNORED_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="calculator", tool_call_id="call-1", arguments={"a": 1}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="calculator", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="calculator", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), + pytest.param(TextContent(author="agent", content="I am not the user"), id="agent-text"), +] + + +class _FakeSpan: + id = "span-offline-1" + output: Any = None + + async def __aenter__(self): + return self + + async def __aexit__(self, *exc_info): + return False + + +@contextmanager +def _mock_adk(): + """Mock the ``adk`` calls the handler makes, so nothing leaves the process.""" + run_result = SimpleNamespace( + final_input_list=[ + {"role": "user", "content": USER_TEXT.content}, + {"role": "assistant", "content": "4"}, + ] + ) + with patch("project.workflow.adk.messages.create", new=AsyncMock()) as create, patch( + "project.workflow.adk.tracing.span", return_value=_FakeSpan() + ) as span, patch( + "project.workflow.adk.providers.openai.run_agent_streamed_auto_send", + new=AsyncMock(return_value=run_result), + ) as run_agent: + yield create, span, run_agent + + +class TestOfflineSignalHandler: + """Unit tests for ``on_task_event_send``, called directly with real ``SendEventParams``.""" + + @staticmethod + def _workflow(): + from project.workflow import StateModel, At050AgentChatGuardrailsWorkflow + + # Build the instance without Temporal: skip __init__ and set what it would set, + # plus the state on_task_create initialises. + wf = At050AgentChatGuardrailsWorkflow.__new__(At050AgentChatGuardrailsWorkflow) + wf.display_name = AGENT_NAME + wf._complete_task = False + wf._state = StateModel(input_list=[], turn_number=0) + return wf + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", IGNORED_CONTENTS) + async def test_unprocessable_event_is_ignored(self, content): + """Return without raising (that would wedge the task) and without side effects.""" + with _mock_adk() as (create, span, run_agent): + wf = self._workflow() + await wf.on_task_event_send(_send_event_params(content)) + + create.assert_not_awaited() + span.assert_not_called() + run_agent.assert_not_awaited() + assert wf._state.turn_number == 0 + assert wf._state.input_list == [] + + @pytest.mark.asyncio + async def test_user_text_event_runs_a_guarded_turn(self): + """A user text event is echoed, added to the history and answered with guardrails on.""" + with _mock_adk() as (create, span, run_agent): + wf = self._workflow() + await wf.on_task_event_send(_send_event_params(USER_TEXT)) + + assert wf._state.turn_number == 1 + span.assert_called_once() + # The first message is the echo of the user's own message. + assert create.await_args_list[0].kwargs["content"] == USER_TEXT + run_agent.assert_awaited_once() + kwargs = run_agent.await_args.kwargs + assert kwargs["input_list"] == [{"role": "user", "content": USER_TEXT.content}] + assert len(kwargs["input_guardrails"]) == 2 + assert len(kwargs["output_guardrails"]) == 2 + assert wf._state.input_list == run_agent.return_value.final_input_list + + @pytest.mark.asyncio + async def test_event_before_state_is_initialised_waits_for_it(self): + """An event handled before on_task_create has run waits for the state, not raises.""" + from project.workflow import StateModel + + wf = self._workflow() + wf._state = None + + async def _wait_condition(condition): + assert not condition() + wf._state = StateModel(input_list=[], turn_number=0) # on_task_create runs + assert condition() + + with _mock_adk() as (create, _span, _run_agent), patch( + "project.workflow.workflow.wait_condition", new=AsyncMock(side_effect=_wait_condition) + ) as wait_condition: + await wf.on_task_event_send(_send_event_params(USER_TEXT)) + + wait_condition.assert_awaited_once() + assert wf._state.turn_number == 1 + assert create.await_args_list[0].kwargs["content"] == USER_TEXT + + if __name__ == "__main__": pytest.main([__file__, "-v"]) \ No newline at end of file diff --git a/examples/tutorials/10_async/10_temporal/060_open_ai_agents_sdk_hello_world/conftest.py b/examples/tutorials/10_async/10_temporal/060_open_ai_agents_sdk_hello_world/conftest.py new file mode 100644 index 000000000..3052026a9 --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/060_open_ai_agents_sdk_hello_world/conftest.py @@ -0,0 +1,49 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at060-open-ai-agents-sdk-hello-world", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at060-open-ai-agents-sdk-hello-world", + # project.workflow refuses to import without an OpenAI key. The offline tests never call OpenAI, so a + # placeholder is enough when no real key is set. + "OPENAI_API_KEY": "offline-test-placeholder", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/060_open_ai_agents_sdk_hello_world/project/workflow.py b/examples/tutorials/10_async/10_temporal/060_open_ai_agents_sdk_hello_world/project/workflow.py index 29141482e..c999fa41c 100644 --- a/examples/tutorials/10_async/10_temporal/060_open_ai_agents_sdk_hello_world/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/060_open_ai_agents_sdk_hello_world/project/workflow.py @@ -118,10 +118,22 @@ async def on_task_event_send(self, params: SendEventParams) -> None: - If the LLM call fails, Temporal automatically retries it - The entire conversation is durable and survives process restarts """ + # Skip events this agent can't handle instead of raising: an exception here fails + # the workflow task, and Temporal replays the signal forever, wedging the task. + # Content can be missing or a non-text type (data, tool request/response, ...). + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", params.task.id, getattr(content, "type", None) + ) + return + logger.info(f"Received task message instruction: {params}") - if self._state is None: - raise ValueError("State is not initialized") + # A signal can arrive before on_task_create has initialised state (e.g. with + # signal-with-start): wait for it rather than raising. + while self._state is None: + await workflow.wait_condition(lambda: self._state is not None) # Increment turn number for tracing self._state.turn_number += 1 @@ -130,14 +142,14 @@ async def on_task_event_send(self, params: SendEventParams) -> None: self._trace_id = params.task.id # Add the user message to conversation history - self._state.input_list.append({"role": "user", "content": params.event.content.content}) + self._state.input_list.append({"role": "user", "content": content.content}) # ============================================================================ # STEP 1: Echo User Message # ============================================================================ # Echo back the client's message to show it in the UI. This is not done by default # so the agent developer has full control over what is shown to the user. - await adk.messages.create(task_id=params.task.id, content=params.event.content) + await adk.messages.create(task_id=params.task.id, content=content) # ============================================================================ # STEP 2: Wrap execution in tracing span @@ -216,7 +228,8 @@ async def on_task_event_send(self, params: SendEventParams) -> None: self._state.input_list.append(msg) # Set span output for tracing - include full state - span.output = self._state.model_dump() + if span: + span.output = self._state.model_dump() # ============================================================================ # WHAT YOU'LL SEE IN TEMPORAL UI: diff --git a/examples/tutorials/10_async/10_temporal/060_open_ai_agents_sdk_hello_world/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/060_open_ai_agents_sdk_hello_world/tests/test_agent.py index 437a8f16c..c9ee2034b 100644 --- a/examples/tutorials/10_async/10_temporal/060_open_ai_agents_sdk_hello_world/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/060_open_ai_agents_sdk_hello_world/tests/test_agent.py @@ -6,6 +6,9 @@ - Non-streaming event sending and polling - Streaming event sending +The offline tests (``TestOfflineSignalHandler``) need no running agent: they call the +workflow's signal handler directly. + To run these tests: 1. Make sure the agent is running (via docker-compose or `agentex agents run`) 2. Set the AGENTEX_API_BASE_URL environment variable if not using default @@ -18,6 +21,10 @@ import os import uuid +from types import SimpleNamespace +from typing import Any +from datetime import datetime, timezone +from unittest.mock import AsyncMock, patch import pytest import pytest_asyncio @@ -27,8 +34,17 @@ ) from agentex import AsyncAgentex +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent from agentex.types.task_message import TaskMessage +from agentex.types.text_content import TextContent from agentex.types.agent_rpc_params import ParamsCreateTaskRequest +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent # Configuration from environment variables AGENTEX_API_BASE_URL = os.environ.get("AGENTEX_API_BASE_URL", "http://localhost:5003") @@ -128,5 +144,153 @@ async def test_send_event_and_stream(self, client: AsyncAgentex, agent_id: str): pass +# --------------------------------------------------------------------------- +# Offline tests (always run -- no Temporal, network, or API keys needed) +# --------------------------------------------------------------------------- + +# Event content a caller can legitimately send that this agent can't process. +NON_TEXT_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], content=["step"]), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="lookup", tool_call_id="call-1", arguments={}), id="tool-request" + ), + pytest.param( + ToolResponseContent(author="user", name="lookup", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="lookup", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +class _FakeSpan: + id = "span-offline-1" + output: Any = None + + async def __aenter__(self): + return self + + async def __aexit__(self, *_a): + pass + + +class _NoSpan: + """What ``adk.tracing.span`` yields when the span could not be started.""" + + async def __aenter__(self): + return None + + async def __aexit__(self, *_a): + pass + + +def _event_params(content: Any) -> SendEventParams: + """Real SendEventParams, shaped like the payload the worker decodes from the signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id="task-offline-1"), + event=Event(id="event-1", agent_id="agent-1", task_id="task-offline-1", sequence_id=1, content=content), + ) + + +def _workflow(): + """A workflow instance with the attributes __init__ and on_task_create would set.""" + from project.workflow import StateModel, At060OpenAiAgentsSdkHelloWorldWorkflow + + wf = At060OpenAiAgentsSdkHelloWorldWorkflow.__new__(At060OpenAiAgentsSdkHelloWorldWorkflow) + wf.display_name = AGENT_NAME + wf._complete_task = False + wf._state = StateModel(input_list=[{"role": "user", "content": "earlier message"}], turn_number=1) + wf._task_id = None + wf._trace_id = None + wf._parent_span_id = None + return wf + + +@pytest.fixture +def side_effects(): + """Mock everything the handler calls that needs Temporal, the Agentex server or OpenAI.""" + with patch("project.workflow.adk.messages.create", new=AsyncMock()) as create, patch( + "project.workflow.adk.tracing.span", return_value=_FakeSpan() + ) as span, patch("project.workflow.Runner.run", new=AsyncMock(return_value=SimpleNamespace())) as run: + yield SimpleNamespace(create=create, span=span, run=run) + + +class TestOfflineSignalHandler: + """The RECEIVE_EVENT signal handler, called directly on a workflow instance. + + A signal handler must never raise on an event it can't process: Temporal would + fail the workflow task and replay the signal forever, so the task would never + handle another message. + """ + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", NON_TEXT_CONTENTS) + async def test_non_text_event_is_ignored_without_side_effects(self, content, side_effects, caplog): + wf = _workflow() + state_before = wf._state.model_dump() + params = _event_params(content) + assert params.event.content is content + + await wf.on_task_event_send(params) + + side_effects.create.assert_not_awaited() + side_effects.span.assert_not_called() + side_effects.run.assert_not_awaited() + assert wf._state.model_dump() == state_before + assert (wf._task_id, wf._trace_id, wf._parent_span_id) == (None, None, None) + assert "Ignoring non-text event for task task-offline-1" in caplog.text + + @pytest.mark.asyncio + async def test_user_text_event_runs_the_agent(self, side_effects): + wf = _workflow() + content = TextContent(author="user", content="Hello how is life?") + + await wf.on_task_event_send(_event_params(content)) + + side_effects.create.assert_awaited_once_with(task_id="task-offline-1", content=content) + side_effects.run.assert_awaited_once() + assert wf._state.turn_number == 2 + assert wf._state.input_list[-1] == {"role": "user", "content": "Hello how is life?"} + assert wf._task_id == "task-offline-1" + + @pytest.mark.asyncio + async def test_user_text_event_runs_when_tracing_yields_no_span(self, side_effects): + # Tracing is best effort: when the span can't be started the turn must still run, not raise on span.output. + side_effects.span.return_value = _NoSpan() + wf = _workflow() + + await wf.on_task_event_send(_event_params(TextContent(author="user", content="Hello how is life?"))) + + side_effects.run.assert_awaited_once() + assert wf._state.turn_number == 2 + assert wf._parent_span_id is None + + @pytest.mark.asyncio + async def test_event_before_state_is_initialised_waits_instead_of_raising(self, side_effects): + from project.workflow import StateModel + + wf = _workflow() + wf._state = None + + async def _wait_until_on_task_create_sets_state(condition, **_kw): + assert not condition() + wf._state = StateModel(input_list=[], turn_number=0) + assert condition() + + with patch("project.workflow.workflow.wait_condition", new=_wait_until_on_task_create_sets_state): + await wf.on_task_event_send(_event_params(TextContent(author="user", content="first message"))) + + assert wf._state.turn_number == 1 + assert wf._state.input_list == [{"role": "user", "content": "first message"}] + side_effects.create.assert_awaited_once() + side_effects.run.assert_awaited_once() + + if __name__ == "__main__": pytest.main([__file__, "-v"]) diff --git a/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools/conftest.py b/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools/conftest.py new file mode 100644 index 000000000..ae46898f4 --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools/conftest.py @@ -0,0 +1,49 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at070-open-ai-agents-sdk-tools", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at070-open-ai-agents-sdk-tools", + # project.workflow refuses to import without an OpenAI key. The offline tests never call OpenAI, so a + # placeholder is enough when no real key is set. + "OPENAI_API_KEY": "offline-test-placeholder", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools/project/workflow.py b/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools/project/workflow.py index f22011c21..11424731c 100644 --- a/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools/project/workflow.py @@ -127,10 +127,22 @@ def __init__(self): @workflow.signal(name=SignalName.RECEIVE_EVENT) async def on_task_event_send(self, params: SendEventParams) -> None: + # Skip events this agent can't handle instead of raising: an exception here fails + # the workflow task, and Temporal replays the signal forever, wedging the task. + # Content can be missing or a non-text type (data, tool request/response, ...). + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", params.task.id, getattr(content, "type", None) + ) + return + logger.info(f"Received task message instruction: {params}") - if self._state is None: - raise ValueError("State is not initialized") + # A signal can arrive before on_task_create has initialised state (e.g. with + # signal-with-start): wait for it rather than raising. + while self._state is None: + await workflow.wait_condition(lambda: self._state is not None) # Increment turn number for tracing self._state.turn_number += 1 @@ -139,11 +151,11 @@ async def on_task_event_send(self, params: SendEventParams) -> None: self._trace_id = params.task.id # Add the user message to conversation history - self._state.input_list.append({"role": "user", "content": params.event.content.content}) + self._state.input_list.append({"role": "user", "content": content.content}) # Echo back the client's message to show it in the UI. This is not done by default # so the agent developer has full control over what is shown to the user. - await adk.messages.create(task_id=params.task.id, content=params.event.content) + await adk.messages.create(task_id=params.task.id, content=content) # ============================================================================ # OpenAI Agents SDK + Temporal Integration: Two Patterns for Tool Creation @@ -272,7 +284,8 @@ async def on_task_event_send(self, params: SendEventParams) -> None: self._state.input_list.append(msg) # Set span output for tracing - include full state - span.output = self._state.model_dump() + if span: + span.output = self._state.model_dump() # ============================================================================ # PATTERN 2: Multiple Activities Within Tools @@ -309,7 +322,7 @@ async def on_task_event_send(self, params: SendEventParams) -> None: # # Run the agent - when it calls move_money tool, it will create TWO activities: # # 1. withdraw_money activity # # 2. deposit_money activity (only after withdraw succeeds) - # result = await Runner.run(money_mover_agent, params.event.content.content) + # result = await Runner.run(money_mover_agent, content.content) # ============================================================================ # PATTERN COMPARISON SUMMARY: diff --git a/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools/tests/test_agent.py index e5f2982f9..6f8557576 100644 --- a/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/070_open_ai_agents_sdk_tools/tests/test_agent.py @@ -5,6 +5,9 @@ - Non-streaming event sending and polling - Streaming event sending +The offline tests (``TestOfflineSignalHandler``) need no running agent: they call the +workflow's signal handler directly. + To run these tests: 1. Make sure the agent is running (via docker-compose or `agentex agents run`) 2. Set the AGENTEX_API_BASE_URL environment variable if not using default @@ -17,6 +20,11 @@ import os import uuid +import asyncio +from types import SimpleNamespace +from typing import Any +from datetime import datetime, timezone +from unittest.mock import AsyncMock, patch import pytest import pytest_asyncio @@ -26,8 +34,17 @@ ) from agentex import AsyncAgentex +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent from agentex.types.task_message import TaskMessage +from agentex.types.text_content import TextContent from agentex.types.agent_rpc_params import ParamsCreateTaskRequest +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent # Configuration from environment variables AGENTEX_API_BASE_URL = os.environ.get("AGENTEX_API_BASE_URL", "http://localhost:5003") @@ -154,5 +171,154 @@ async def test_send_event_and_stream(self, client: AsyncAgentex, agent_id: str): pass +# --------------------------------------------------------------------------- +# Offline tests (always run -- no Temporal, network, or API keys needed) +# --------------------------------------------------------------------------- + +# Event content a caller can legitimately send that this agent can't process. +NON_TEXT_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], content=["step"]), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="lookup", tool_call_id="call-1", arguments={}), id="tool-request" + ), + pytest.param( + ToolResponseContent(author="user", name="lookup", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="lookup", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +class _FakeSpan: + id = "span-offline-1" + output: Any = None + + async def __aenter__(self): + return self + + async def __aexit__(self, *_a): + pass + + +class _NoSpan: + """What ``adk.tracing.span`` yields when the span could not be started.""" + + async def __aenter__(self): + return None + + async def __aexit__(self, *_a): + pass + + +def _event_params(content: Any) -> SendEventParams: + """Real SendEventParams, shaped like the payload the worker decodes from the signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id="task-offline-1"), + event=Event(id="event-1", agent_id="agent-1", task_id="task-offline-1", sequence_id=1, content=content), + ) + + +def _workflow(): + """A workflow instance with the attributes __init__ and on_task_create would set.""" + from project.workflow import StateModel, At070OpenAiAgentsSdkToolsWorkflow + + wf = At070OpenAiAgentsSdkToolsWorkflow.__new__(At070OpenAiAgentsSdkToolsWorkflow) + wf.display_name = AGENT_NAME + wf._complete_task = False + wf._state = StateModel(input_list=[{"role": "user", "content": "earlier message"}], turn_number=1) + wf._pending_confirmation = asyncio.Queue() + wf._task_id = None + wf._trace_id = None + wf._parent_span_id = None + return wf + + +@pytest.fixture +def side_effects(): + """Mock everything the handler calls that needs Temporal, the Agentex server or OpenAI.""" + with patch("project.workflow.adk.messages.create", new=AsyncMock()) as create, patch( + "project.workflow.adk.tracing.span", return_value=_FakeSpan() + ) as span, patch("project.workflow.Runner.run", new=AsyncMock(return_value=SimpleNamespace())) as run: + yield SimpleNamespace(create=create, span=span, run=run) + + +class TestOfflineSignalHandler: + """The RECEIVE_EVENT signal handler, called directly on a workflow instance. + + A signal handler must never raise on an event it can't process: Temporal would + fail the workflow task and replay the signal forever, so the task would never + handle another message. + """ + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", NON_TEXT_CONTENTS) + async def test_non_text_event_is_ignored_without_side_effects(self, content, side_effects, caplog): + wf = _workflow() + state_before = wf._state.model_dump() + params = _event_params(content) + assert params.event.content is content + + await wf.on_task_event_send(params) + + side_effects.create.assert_not_awaited() + side_effects.span.assert_not_called() + side_effects.run.assert_not_awaited() + assert wf._state.model_dump() == state_before + assert (wf._task_id, wf._trace_id, wf._parent_span_id) == (None, None, None) + assert "Ignoring non-text event for task task-offline-1" in caplog.text + + @pytest.mark.asyncio + async def test_user_text_event_runs_the_agent(self, side_effects): + wf = _workflow() + content = TextContent(author="user", content="What is the weather in New York City?") + + await wf.on_task_event_send(_event_params(content)) + + side_effects.create.assert_awaited_once_with(task_id="task-offline-1", content=content) + side_effects.run.assert_awaited_once() + assert wf._state.turn_number == 2 + assert wf._state.input_list[-1] == {"role": "user", "content": "What is the weather in New York City?"} + assert wf._task_id == "task-offline-1" + + @pytest.mark.asyncio + async def test_user_text_event_runs_when_tracing_yields_no_span(self, side_effects): + # Tracing is best effort: when the span can't be started the turn must still run, not raise on span.output. + side_effects.span.return_value = _NoSpan() + wf = _workflow() + + await wf.on_task_event_send(_event_params(TextContent(author="user", content="Hello how is life?"))) + + side_effects.run.assert_awaited_once() + assert wf._state.turn_number == 2 + assert wf._parent_span_id is None + + @pytest.mark.asyncio + async def test_event_before_state_is_initialised_waits_instead_of_raising(self, side_effects): + from project.workflow import StateModel + + wf = _workflow() + wf._state = None + + async def _wait_until_on_task_create_sets_state(condition, **_kw): + assert not condition() + wf._state = StateModel(input_list=[], turn_number=0) + assert condition() + + with patch("project.workflow.workflow.wait_condition", new=_wait_until_on_task_create_sets_state): + await wf.on_task_event_send(_event_params(TextContent(author="user", content="first message"))) + + assert wf._state.turn_number == 1 + assert wf._state.input_list == [{"role": "user", "content": "first message"}] + side_effects.create.assert_awaited_once() + side_effects.run.assert_awaited_once() + + if __name__ == "__main__": pytest.main([__file__, "-v"]) \ No newline at end of file diff --git a/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/conftest.py b/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/conftest.py new file mode 100644 index 000000000..5abbeab2d --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/conftest.py @@ -0,0 +1,49 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at080-open-ai-agents-sdk-human-in-the-loop", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at080-open-ai-agents-sdk-human-in-the-loop", + # project.workflow refuses to import without an OpenAI key. The offline tests never call OpenAI, so a + # placeholder is enough when no real key is set. + "OPENAI_API_KEY": "offline-test-placeholder", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/project/workflow.py b/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/project/workflow.py index 3428aa836..336c52ead 100644 --- a/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/project/workflow.py @@ -114,10 +114,22 @@ async def on_task_event_send(self, params: SendEventParams) -> None: When the agent needs human approval, it calls wait_for_confirmation which spawns a child workflow that waits for external signals before continuing. """ + # Skip events this agent can't handle instead of raising: an exception here fails + # the workflow task, and Temporal replays the signal forever, wedging the task. + # Content can be missing or a non-text type (data, tool request/response, ...). + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", params.task.id, getattr(content, "type", None) + ) + return + logger.info(f"Received task message instruction: {params}") - if self._state is None: - raise ValueError("State is not initialized") + # A signal can arrive before on_task_create has initialised state (e.g. with + # signal-with-start): wait for it rather than raising. + while self._state is None: + await workflow.wait_condition(lambda: self._state is not None) # Increment turn number for tracing self._state.turn_number += 1 @@ -126,10 +138,10 @@ async def on_task_event_send(self, params: SendEventParams) -> None: self._trace_id = params.task.id # Add the user message to conversation history - self._state.input_list.append({"role": "user", "content": params.event.content.content}) + self._state.input_list.append({"role": "user", "content": content.content}) # Echo user message back to UI - await adk.messages.create(task_id=params.task.id, content=params.event.content) + await adk.messages.create(task_id=params.task.id, content=content) # ============================================================================ # STREAMING SETUP: Store task_id for the Interceptor @@ -206,7 +218,8 @@ async def on_task_event_send(self, params: SendEventParams) -> None: self._state.input_list.append(msg) # Set span output for tracing - include full state - span.output = self._state.model_dump() + if span: + span.output = self._state.model_dump() @workflow.run async def on_task_create(self, params: CreateTaskParams) -> str: diff --git a/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/tests/test_agent.py index 3a0386ffb..09244e709 100644 --- a/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/080_open_ai_agents_sdk_human_in_the_loop/tests/test_agent.py @@ -7,6 +7,9 @@ - Sending Temporal signals to approve/reject - Verifying workflow completes after approval +The offline tests (``TestOfflineSignalHandler``) need no running agent or Temporal: +they call the workflow's signal handler directly. + To run these tests: 1. Make sure the agent is running (via docker-compose or `agentex agents run`) 2. Make sure Temporal is running (localhost:7233) @@ -22,6 +25,10 @@ import os import uuid import asyncio +from types import SimpleNamespace +from typing import Any +from datetime import datetime, timezone +from unittest.mock import AsyncMock, patch import pytest import pytest_asyncio @@ -34,8 +41,17 @@ ) from agentex import AsyncAgentex +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent from agentex.types.task_message import TaskMessage +from agentex.types.text_content import TextContent from agentex.types.agent_rpc_params import ParamsCreateTaskRequest +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent # Configuration from environment variables AGENTEX_API_BASE_URL = os.environ.get("AGENTEX_API_BASE_URL", "http://localhost:5003") @@ -179,5 +195,154 @@ async def test_send_event_and_stream(self, client: AsyncAgentex, agent_id: str): pass +# --------------------------------------------------------------------------- +# Offline tests (always run -- no Temporal, network, or API keys needed) +# --------------------------------------------------------------------------- + +# Event content a caller can legitimately send that this agent can't process. +NON_TEXT_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], content=["step"]), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="lookup", tool_call_id="call-1", arguments={}), id="tool-request" + ), + pytest.param( + ToolResponseContent(author="user", name="lookup", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="lookup", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +class _FakeSpan: + id = "span-offline-1" + output: Any = None + + async def __aenter__(self): + return self + + async def __aexit__(self, *_a): + pass + + +class _NoSpan: + """What ``adk.tracing.span`` yields when the span could not be started.""" + + async def __aenter__(self): + return None + + async def __aexit__(self, *_a): + pass + + +def _event_params(content: Any) -> SendEventParams: + """Real SendEventParams, shaped like the payload the worker decodes from the signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id="task-offline-1"), + event=Event(id="event-1", agent_id="agent-1", task_id="task-offline-1", sequence_id=1, content=content), + ) + + +def _workflow(): + """A workflow instance with the attributes __init__ and on_task_create would set.""" + from project.workflow import StateModel, At080OpenAiAgentsSdkHumanInTheLoopWorkflow + + wf = At080OpenAiAgentsSdkHumanInTheLoopWorkflow.__new__(At080OpenAiAgentsSdkHumanInTheLoopWorkflow) + wf.display_name = AGENT_NAME + wf._complete_task = False + wf._state = StateModel(input_list=[{"role": "user", "content": "earlier message"}], turn_number=1) + wf._pending_confirmation = asyncio.Queue() + wf._task_id = None + wf._trace_id = None + wf._parent_span_id = None + return wf + + +@pytest.fixture +def side_effects(): + """Mock everything the handler calls that needs Temporal, the Agentex server or OpenAI.""" + with patch("project.workflow.adk.messages.create", new=AsyncMock()) as create, patch( + "project.workflow.adk.tracing.span", return_value=_FakeSpan() + ) as span, patch("project.workflow.Runner.run", new=AsyncMock(return_value=SimpleNamespace())) as run: + yield SimpleNamespace(create=create, span=span, run=run) + + +class TestOfflineSignalHandler: + """The RECEIVE_EVENT signal handler, called directly on a workflow instance. + + A signal handler must never raise on an event it can't process: Temporal would + fail the workflow task and replay the signal forever, so the task would never + handle another message. + """ + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", NON_TEXT_CONTENTS) + async def test_non_text_event_is_ignored_without_side_effects(self, content, side_effects, caplog): + wf = _workflow() + state_before = wf._state.model_dump() + params = _event_params(content) + assert params.event.content is content + + await wf.on_task_event_send(params) + + side_effects.create.assert_not_awaited() + side_effects.span.assert_not_called() + side_effects.run.assert_not_awaited() + assert wf._state.model_dump() == state_before + assert (wf._task_id, wf._trace_id, wf._parent_span_id) == (None, None, None) + assert "Ignoring non-text event for task task-offline-1" in caplog.text + + @pytest.mark.asyncio + async def test_user_text_event_runs_the_agent(self, side_effects): + wf = _workflow() + content = TextContent(author="user", content="Please confirm my order") + + await wf.on_task_event_send(_event_params(content)) + + side_effects.create.assert_awaited_once_with(task_id="task-offline-1", content=content) + side_effects.run.assert_awaited_once() + assert wf._state.turn_number == 2 + assert wf._state.input_list[-1] == {"role": "user", "content": "Please confirm my order"} + assert wf._task_id == "task-offline-1" + + @pytest.mark.asyncio + async def test_user_text_event_runs_when_tracing_yields_no_span(self, side_effects): + # Tracing is best effort: when the span can't be started the turn must still run, not raise on span.output. + side_effects.span.return_value = _NoSpan() + wf = _workflow() + + await wf.on_task_event_send(_event_params(TextContent(author="user", content="Hello how is life?"))) + + side_effects.run.assert_awaited_once() + assert wf._state.turn_number == 2 + assert wf._parent_span_id is None + + @pytest.mark.asyncio + async def test_event_before_state_is_initialised_waits_instead_of_raising(self, side_effects): + from project.workflow import StateModel + + wf = _workflow() + wf._state = None + + async def _wait_until_on_task_create_sets_state(condition, **_kw): + assert not condition() + wf._state = StateModel(input_list=[], turn_number=0) + assert condition() + + with patch("project.workflow.workflow.wait_condition", new=_wait_until_on_task_create_sets_state): + await wf.on_task_event_send(_event_params(TextContent(author="user", content="first message"))) + + assert wf._state.turn_number == 1 + assert wf._state.input_list == [{"role": "user", "content": "first message"}] + side_effects.create.assert_awaited_once() + side_effects.run.assert_awaited_once() + + if __name__ == "__main__": pytest.main([__file__, "-v"]) diff --git a/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/conftest.py b/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/conftest.py new file mode 100644 index 000000000..d29fac770 --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/conftest.py @@ -0,0 +1,46 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "claude-mvp-agent", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "ClaudeMvpWorkflow", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/project/__init__.py b/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/project/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/project/run_worker.py b/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/project/run_worker.py index a969cd760..25c205bf8 100644 --- a/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/project/run_worker.py +++ b/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/project/run_worker.py @@ -14,7 +14,6 @@ # Import workflow from project.workflow import ClaudeMvpWorkflow - from agentex.lib.utils.logging import make_logger from agentex.lib.environment_variables import EnvironmentVariables from agentex.lib.core.temporal.activities import get_all_activities diff --git a/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/project/workflow.py b/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/project/workflow.py index c22045152..9f049e3e1 100644 --- a/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/project/workflow.py @@ -91,10 +91,22 @@ def __init__(self): async def on_task_event_send(self, params: SendEventParams): """Handle user message - run Claude agent""" - logger.info(f"Received task message: {params.event.content.content[:100]}...") + # Skip events this agent can't handle instead of raising: an exception here fails + # the workflow task, and Temporal replays the signal forever, wedging the task. + # Content can be missing or a non-text type (data, tool request/response, ...). + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", params.task.id, getattr(content, "type", None) + ) + return + + logger.info(f"Received task message: {content.content[:100]}...") - if self._state is None: - raise ValueError("State is not initialized") + # A signal can arrive before on_task_create has initialised state and created the + # workspace (e.g. with signal-with-start): wait for both rather than raising. + while self._state is None or self._workspace_path is None: + await workflow.wait_condition(lambda: self._state is not None and self._workspace_path is not None) self._task_id = params.task.id self._trace_id = params.task.id @@ -103,7 +115,7 @@ async def on_task_event_send(self, params: SendEventParams): # Echo user message to UI await adk.messages.create( task_id=params.task.id, - content=params.event.content + content=content ) # Wrap in tracing span - THIS IS REQUIRED for ContextInterceptor to work! @@ -111,7 +123,7 @@ async def on_task_event_send(self, params: SendEventParams): trace_id=params.task.id, name=f"Turn {self._state.turn_number}", input={ - "prompt": params.event.content.content, + "prompt": content.content, "session_id": self._state.claude_session_id, }, ) as span: @@ -139,7 +151,7 @@ async def on_task_event_send(self, params: SendEventParams): result = await workflow.execute_activity( run_claude_agent_activity, args=[ - params.event.content.content, # prompt + content.content, # prompt self._workspace_path, # workspace ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "Task"], # allowed tools (Task for subagents!) "acceptEdits", # permission mode diff --git a/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/tests/test_agent.py index 9b93b1b76..f17d2efb2 100644 --- a/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/090_claude_agents_sdk_mvp/tests/test_agent.py @@ -1,4 +1,8 @@ import os +from types import SimpleNamespace +from typing import Any +from datetime import datetime, timezone +from unittest.mock import AsyncMock, patch # import uuid # import asyncio @@ -11,6 +15,15 @@ # send_event_and_poll_yielding, # ) from agentex import AsyncAgentex +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent +from agentex.types.text_content import TextContent +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent # from agentex.types import TaskMessage # from agentex.types.agent_rpc_params import ParamsCreateTaskRequest @@ -63,5 +76,140 @@ async def test_send_event_and_stream(self, client: AsyncAgentex, agent_id: str): pass +# --------------------------------------------------------------------------- +# Offline tests (always run -- no Temporal, network, or API keys needed) +# --------------------------------------------------------------------------- + +WORKSPACE = "/workspaces/task-offline-1" + +# Event content a caller can legitimately send that this agent can't process. +NON_TEXT_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], content=["step"]), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="lookup", tool_call_id="call-1", arguments={}), id="tool-request" + ), + pytest.param( + ToolResponseContent(author="user", name="lookup", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="lookup", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +class _FakeSpan: + id = "span-offline-1" + output: Any = None + + async def __aenter__(self): + return self + + async def __aexit__(self, *_a): + pass + + +def _event_params(content: Any) -> SendEventParams: + """Real SendEventParams, shaped like the payload the worker decodes from the signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id="task-offline-1"), + event=Event(id="event-1", agent_id="agent-1", task_id="task-offline-1", sequence_id=1, content=content), + ) + + +def _workflow(): + """A workflow instance with the attributes __init__ and on_task_create would set.""" + from project.workflow import StateModel, ClaudeMvpWorkflow + + wf = ClaudeMvpWorkflow.__new__(ClaudeMvpWorkflow) + wf.display_name = AGENT_NAME + wf._complete_task = False + wf._state = StateModel(claude_session_id="session-earlier", turn_number=1) + wf._task_id = None + wf._trace_id = None + wf._parent_span_id = None + wf._workspace_path = WORKSPACE + return wf + + +@pytest.fixture +def side_effects(): + """Mock everything the handler calls that needs Temporal, the Agentex server or Claude.""" + with patch("project.workflow.adk.messages.create", new=AsyncMock()) as create, patch( + "project.workflow.adk.tracing.span", return_value=_FakeSpan() + ) as span, patch( + "project.workflow.workflow.execute_activity", new=AsyncMock(return_value={"session_id": "session-new"}) + ) as execute_activity: + yield SimpleNamespace(create=create, span=span, execute_activity=execute_activity) + + +class TestOfflineSignalHandler: + """The RECEIVE_EVENT signal handler, called directly on a workflow instance. + + A signal handler must never raise on an event it can't process: Temporal would + fail the workflow task and replay the signal forever, so the task would never + handle another message. + """ + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", NON_TEXT_CONTENTS) + async def test_non_text_event_is_ignored_without_side_effects(self, content, side_effects, caplog): + wf = _workflow() + state_before = wf._state.model_dump() + params = _event_params(content) + assert params.event.content is content + + await wf.on_task_event_send(params) + + side_effects.create.assert_not_awaited() + side_effects.span.assert_not_called() + side_effects.execute_activity.assert_not_awaited() + assert wf._state.model_dump() == state_before + assert (wf._task_id, wf._trace_id, wf._parent_span_id) == (None, None, None) + assert "Ignoring non-text event for task task-offline-1" in caplog.text + + @pytest.mark.asyncio + async def test_user_text_event_runs_claude(self, side_effects): + wf = _workflow() + content = TextContent(author="user", content="Create a hello.py file") + + await wf.on_task_event_send(_event_params(content)) + + side_effects.create.assert_awaited_once_with(task_id="task-offline-1", content=content) + side_effects.execute_activity.assert_awaited_once() + prompt, workspace, *_ = side_effects.execute_activity.await_args.kwargs["args"] + assert (prompt, workspace) == ("Create a hello.py file", WORKSPACE) + assert wf._state.turn_number == 2 + assert wf._state.claude_session_id == "session-new" + + @pytest.mark.asyncio + async def test_event_before_workspace_is_ready_waits_instead_of_raising(self, side_effects): + from project.workflow import StateModel + + wf = _workflow() + wf._state = None + wf._workspace_path = None + + async def _wait_until_on_task_create_finishes(condition, **_kw): + assert not condition() + wf._state = StateModel(claude_session_id=None, turn_number=0) + assert not condition() # state is set before the workspace activity returns + wf._workspace_path = WORKSPACE + assert condition() + + with patch("project.workflow.workflow.wait_condition", new=_wait_until_on_task_create_finishes): + await wf.on_task_event_send(_event_params(TextContent(author="user", content="first message"))) + + assert wf._state.turn_number == 1 + side_effects.create.assert_awaited_once() + prompt, workspace, *_ = side_effects.execute_activity.await_args.kwargs["args"] + assert (prompt, workspace) == ("first message", WORKSPACE) + + if __name__ == "__main__": pytest.main([__file__, "-v"]) diff --git a/examples/tutorials/10_async/10_temporal/100_gemini_litellm/conftest.py b/examples/tutorials/10_async/10_temporal/100_gemini_litellm/conftest.py new file mode 100644 index 000000000..280c8cd19 --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/100_gemini_litellm/conftest.py @@ -0,0 +1,46 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at100-gemini-litellm", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at100-gemini-litellm", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/100_gemini_litellm/project/workflow.py b/examples/tutorials/10_async/10_temporal/100_gemini_litellm/project/workflow.py index 249bdaa50..3d11ec647 100644 --- a/examples/tutorials/10_async/10_temporal/100_gemini_litellm/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/100_gemini_litellm/project/workflow.py @@ -112,10 +112,21 @@ async def on_task_event_send(self, params: SendEventParams) -> None: - The agent interface remains identical to OpenAI examples - Temporal durability works the same way regardless of model provider """ + # Validate before any side effect, and return instead of raising: an + # exception here fails the workflow task, and Temporal retries it forever. + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", params.task.id, getattr(content, "type", None) + ) + return + logger.info(f"Received task message instruction: {params}") - if self._state is None: - raise ValueError("State is not initialized") + # A signal can be delivered before on_task_create initialises the state + # (e.g. with signal-with-start), so wait for it rather than drop the message. + while self._state is None: + await workflow.wait_condition(lambda: self._state is not None) # Increment turn number for tracing self._state.turn_number += 1 @@ -124,12 +135,12 @@ async def on_task_event_send(self, params: SendEventParams) -> None: self._trace_id = params.task.id # Add the user message to conversation history - self._state.input_list.append({"role": "user", "content": params.event.content.content}) + self._state.input_list.append({"role": "user", "content": content.content}) # ============================================================================ # STEP 1: Echo User Message # ============================================================================ - await adk.messages.create(task_id=params.task.id, content=params.event.content) + await adk.messages.create(task_id=params.task.id, content=content) # ============================================================================ # STEP 2: Wrap execution in tracing span @@ -182,7 +193,8 @@ async def on_task_event_send(self, params: SendEventParams) -> None: self._state.input_list.append(msg) # Set span output for tracing - span.output = self._state.model_dump() + if span: + span.output = self._state.model_dump() # Send the response to the user await adk.messages.create( diff --git a/examples/tutorials/10_async/10_temporal/100_gemini_litellm/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/100_gemini_litellm/tests/test_agent.py new file mode 100644 index 000000000..c3d5a7bfa --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/100_gemini_litellm/tests/test_agent.py @@ -0,0 +1,206 @@ +"""Offline tests for the Gemini + LiteLLM Temporal tutorial's signal handler. + +These tests do NOT require Temporal, a running Agentex server, or a Gemini API +key. They call ``on_task_event_send`` directly with real event payloads, with +its collaborators (``adk.messages``, tracing, ``Runner`` and +``workflow.wait_condition``) patched, and check that: + +- a user text event is echoed, run through the agent, and the reply sent; +- an event that arrives before ``on_task_create`` has initialised the state + waits for it instead of being dropped; +- an event the handler cannot process (no content, or content that is not + text) is ignored without raising and without side effects. + +To run: ``pytest tests/test_agent.py -v`` +""" + +from __future__ import annotations + +import os +from types import SimpleNamespace +from typing import Any +from datetime import datetime, timezone +from unittest.mock import AsyncMock, MagicMock, call + +import pytest + +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent +from agentex.types.text_content import TextContent +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent + +AGENT_NAME = os.environ.get("AGENT_NAME", "at100-gemini-litellm") +TASK_ID = "task-offline" + +# Event content a caller can send that the handler cannot process: Event.content +# is optional, and only TextContent carries a ``content: str``. +NON_TEXT_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="get_weather", tool_call_id="call-1", arguments={"city": "Paris"}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id=TASK_ID), + event=Event(id="event-1", agent_id="agent-1", task_id=TASK_ID, sequence_id=1, content=content), + ) + + +class _FakeSpan: + id = "span-1" + output: Any = None + + async def __aenter__(self): + return self + + async def __aexit__(self, *a): + pass + + +class _NoSpan: + """What ``adk.tracing.span`` yields when the span could not be started.""" + + async def __aenter__(self): + return None + + async def __aexit__(self, *_a): + pass + + +@pytest.fixture +def workflow_module(): + """``project.workflow``; conftest.py sets the env vars it reads at import time.""" + import project.workflow + + return project.workflow + + +@pytest.fixture +def mocks(workflow_module, monkeypatch): + """Patch what the signal handler calls, so it runs without Temporal, a model or a server.""" + m = SimpleNamespace( + wait_condition=AsyncMock(), + create=AsyncMock(), + span=MagicMock(return_value=_FakeSpan()), + runner=SimpleNamespace(run=AsyncMock(return_value=SimpleNamespace(final_output="Hi, I'm Gemini."))), + ) + monkeypatch.setattr(workflow_module.workflow, "wait_condition", m.wait_condition) + monkeypatch.setattr(workflow_module.adk.messages, "create", m.create) + monkeypatch.setattr(workflow_module.adk.tracing, "span", m.span) + monkeypatch.setattr(workflow_module, "Runner", m.runner) + return m + + +def _new_workflow(workflow_module, *, initialised: bool = True): + """A workflow instance with the attributes ``__init__`` sets, built without a Temporal runtime. + + ``initialised`` stands in for ``on_task_create`` having already set up the conversation state. + """ + wf = workflow_module.At100GeminiLitellmWorkflow.__new__(workflow_module.At100GeminiLitellmWorkflow) + wf.display_name = AGENT_NAME + wf._complete_task = False + wf._state = workflow_module.StateModel(input_list=[], turn_number=0) if initialised else None + wf._task_id = None + wf._trace_id = None + wf._parent_span_id = None + return wf + + +class TestSignalHandlerOffline: + """The signal handler, called directly with real event payloads.""" + + @pytest.mark.asyncio + async def test_user_text_event_runs_agent_and_replies(self, workflow_module, mocks): + """A user text event is echoed, added to the history, run through the agent, and answered.""" + wf = _new_workflow(workflow_module) + content = TextContent(author="user", content="Hello") + + await wf.on_task_event_send(_send_event_params(content)) + + assert mocks.create.await_args_list == [ + call(task_id=TASK_ID, content=content), + call(task_id=TASK_ID, content=TextContent(author="agent", content="Hi, I'm Gemini.")), + ] + mocks.runner.run.assert_awaited_once() + assert mocks.runner.run.await_args.args[1] == [{"role": "user", "content": "Hello"}] + assert wf._state.turn_number == 1 + assert wf._task_id == TASK_ID + + @pytest.mark.asyncio + async def test_user_text_event_runs_when_tracing_yields_no_span(self, workflow_module, mocks): + """Tracing is best effort: when the span can't be started the turn still runs and replies.""" + mocks.span.return_value = _NoSpan() + wf = _new_workflow(workflow_module) + + await wf.on_task_event_send(_send_event_params(TextContent(author="user", content="Hello"))) + + mocks.runner.run.assert_awaited_once() + assert mocks.create.await_count == 2 + assert wf._state.turn_number == 1 + + @pytest.mark.asyncio + async def test_event_before_state_is_initialised_waits_for_it(self, workflow_module, mocks, monkeypatch): + """A signal delivered before ``on_task_create`` sets up the state is processed once it exists.""" + wf = _new_workflow(workflow_module, initialised=False) + + async def _wait_condition(predicate): + # Temporal resumes the handler once on_task_create has initialised the state. + assert not predicate() + wf._state = workflow_module.StateModel(input_list=[], turn_number=0) + assert predicate() + + monkeypatch.setattr(workflow_module.workflow, "wait_condition", _wait_condition) + content = TextContent(author="user", content="Hello") + + await wf.on_task_event_send(_send_event_params(content)) + + assert mocks.create.await_args_list[0] == call(task_id=TASK_ID, content=content) + mocks.runner.run.assert_awaited_once() + assert wf._state.turn_number == 1 + assert wf._state.input_list == [{"role": "user", "content": "Hello"}] + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", NON_TEXT_CONTENTS) + async def test_non_text_event_is_ignored(self, workflow_module, mocks, content): + """An event the handler cannot process is ignored: no exception, no side effects. + + An exception raised by a signal handler fails the workflow task, and + Temporal retries it forever by replaying the same signal from history, so + the task's workflow would never process another event. + """ + wf = _new_workflow(workflow_module) + + await wf.on_task_event_send(_send_event_params(content)) + + mocks.wait_condition.assert_not_awaited() + mocks.create.assert_not_awaited() + mocks.span.assert_not_called() + mocks.runner.run.assert_not_awaited() + assert wf._state == workflow_module.StateModel(input_list=[], turn_number=0) + assert wf._task_id is None + + +if __name__ == "__main__": + pytest.main([__file__, "-v"]) diff --git a/examples/tutorials/10_async/10_temporal/110_pydantic_ai/conftest.py b/examples/tutorials/10_async/10_temporal/110_pydantic_ai/conftest.py new file mode 100644 index 000000000..0d0e34b75 --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/110_pydantic_ai/conftest.py @@ -0,0 +1,49 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at110-pydantic-ai", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at110-pydantic-ai", + # project.workflow refuses to import without an OpenAI key. The offline tests never call OpenAI, so a + # placeholder is enough when no real key is set. + "OPENAI_API_KEY": "offline-test-placeholder", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/110_pydantic_ai/project/workflow.py b/examples/tutorials/10_async/10_temporal/110_pydantic_ai/project/workflow.py index 9a01be7de..038498cb0 100644 --- a/examples/tutorials/10_async/10_temporal/110_pydantic_ai/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/110_pydantic_ai/project/workflow.py @@ -81,24 +81,33 @@ def __init__(self): @workflow.signal(name=SignalName.RECEIVE_EVENT) async def on_task_event_send(self, params: SendEventParams) -> None: """Handle a new user message: echo it, then run the agent durably.""" + # Validate before any side effect, and return instead of raising: an + # exception here fails the workflow task, and Temporal retries it forever. + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", params.task.id, getattr(content, "type", None) + ) + return + logger.info(f"Received task event: {params.task.id}") self._turn_number += 1 # Echo the user's message so it shows up in the UI as a chat bubble. - await adk.messages.create(task_id=params.task.id, content=params.event.content) + await adk.messages.create(task_id=params.task.id, content=content) async with adk.tracing.span( trace_id=params.task.id, task_id=params.task.id, name=f"Turn {self._turn_number}", - input={"message": params.event.content.content}, + input={"message": content.content}, ) as span: # temporal_agent.run() schedules a model activity, per-tool # activities, and the event_stream_handler activity (which pushes # deltas through the unified surface). Passing ``message_history`` # makes the run remember prior turns. result = await temporal_agent.run( - params.event.content.content, + content.content, message_history=self._message_history, deps=TaskDeps( task_id=params.task.id, diff --git a/examples/tutorials/10_async/10_temporal/110_pydantic_ai/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/110_pydantic_ai/tests/test_agent.py index 974cddcc0..b4476cbc6 100644 --- a/examples/tutorials/10_async/10_temporal/110_pydantic_ai/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/110_pydantic_ai/tests/test_agent.py @@ -6,6 +6,12 @@ Offline coverage of the same wiring (TestModel + fake streaming/tracing) lives in the SDK repo under ``tests/lib/core/harness/`` (the pydantic-ai temporal suite). +The offline tests at the end of this file (``TestSignalHandlerOffline``) call the +workflow's signal handler directly, with its collaborators patched, and need no +running agent: a user text event runs a turn, and an event the handler cannot +process (no content, or content that is not text) is ignored without raising +and without side effects. + To run these tests: 1. Make sure the agent is running (worker + ACP server) 2. Set AGENTEX_API_BASE_URL if not using the default @@ -14,14 +20,27 @@ import os import uuid +from types import SimpleNamespace +from typing import Any +from datetime import datetime, timezone +from unittest.mock import AsyncMock, MagicMock import pytest import pytest_asyncio from test_utils.async_utils import poll_messages, send_event_and_poll_yielding from agentex import AsyncAgentex +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent from agentex.types.task_message import TaskMessage +from agentex.types.text_content import TextContent from agentex.types.agent_rpc_params import ParamsCreateTaskRequest +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent AGENTEX_API_BASE_URL = os.environ.get("AGENTEX_API_BASE_URL", "http://localhost:5003") AGENT_NAME = os.environ.get("AGENT_NAME", "at110-pydantic-ai") @@ -109,5 +128,125 @@ async def test_send_event_and_poll(self, client: AsyncAgentex, agent_id: str): assert "72" in final_text, "Expected weather response to mention 72°F" +# --------------------------------------------------------------------------- +# Offline signal-handler tests (no running agent, Temporal or API key needed) +# --------------------------------------------------------------------------- + +TASK_ID = "task-offline" + +# Event content a caller can send that the handler cannot process: Event.content +# is optional, and only TextContent carries a ``content: str``. +NON_TEXT_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="get_weather", tool_call_id="call-1", arguments={"city": "Paris"}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id=TASK_ID), + event=Event(id="event-1", agent_id="agent-1", task_id=TASK_ID, sequence_id=1, content=content), + ) + + +class _FakeSpan: + id = "span-1" + output: Any = None + + async def __aenter__(self): + return self + + async def __aexit__(self, *a): + pass + + +@pytest.fixture +def workflow_module(): + """``project.workflow``; conftest.py sets the env vars it reads at import time.""" + import project.workflow + + return project.workflow + + +@pytest.fixture +def mocks(workflow_module, monkeypatch): + """Patch what the signal handler calls, so it runs without Temporal, a model or a server.""" + run_result = SimpleNamespace(output="It is 72°F.", all_messages=lambda: ["model-request", "model-response"]) + m = SimpleNamespace( + create=AsyncMock(), + span=MagicMock(return_value=_FakeSpan()), + agent=SimpleNamespace(run=AsyncMock(return_value=run_result)), + ) + monkeypatch.setattr(workflow_module.adk.messages, "create", m.create) + monkeypatch.setattr(workflow_module.adk.tracing, "span", m.span) + monkeypatch.setattr(workflow_module, "temporal_agent", m.agent) + return m + + +def _new_workflow(workflow_module): + """A workflow instance with the attributes ``__init__`` sets, built without a Temporal runtime.""" + wf = workflow_module.HarnessPydanticAiWorkflow.__new__(workflow_module.HarnessPydanticAiWorkflow) + wf.display_name = AGENT_NAME + wf._complete_task = False + wf._turn_number = 0 + wf._message_history = [] + return wf + + +class TestSignalHandlerOffline: + """The signal handler, called directly with real event payloads.""" + + @pytest.mark.asyncio + async def test_user_text_event_runs_agent(self, workflow_module, mocks): + """A user text event is echoed and run through the agent; the history is carried forward.""" + wf = _new_workflow(workflow_module) + content = TextContent(author="user", content="What is the weather in Paris?") + + await wf.on_task_event_send(_send_event_params(content)) + + mocks.create.assert_awaited_once_with(task_id=TASK_ID, content=content) + mocks.agent.run.assert_awaited_once() + assert mocks.agent.run.await_args.args == ("What is the weather in Paris?",) + deps = mocks.agent.run.await_args.kwargs["deps"] + assert (deps.task_id, deps.parent_span_id) == (TASK_ID, "span-1") + assert wf._turn_number == 1 + assert wf._message_history == ["model-request", "model-response"] + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", NON_TEXT_CONTENTS) + async def test_non_text_event_is_ignored(self, workflow_module, mocks, content): + """An event the handler cannot process is ignored: no exception, no side effects. + + An exception raised by a signal handler fails the workflow task, and + Temporal retries it forever by replaying the same signal from history, so + the task's workflow would never process another event. + """ + wf = _new_workflow(workflow_module) + + await wf.on_task_event_send(_send_event_params(content)) + + mocks.create.assert_not_awaited() + mocks.span.assert_not_called() + mocks.agent.run.assert_not_awaited() + assert wf._turn_number == 0 + assert wf._message_history == [] + + if __name__ == "__main__": pytest.main([__file__, "-v"]) diff --git a/examples/tutorials/10_async/10_temporal/120_openai_agents/conftest.py b/examples/tutorials/10_async/10_temporal/120_openai_agents/conftest.py new file mode 100644 index 000000000..9c9312a50 --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/120_openai_agents/conftest.py @@ -0,0 +1,46 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at120-openai-agents", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at120-openai-agents", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/120_openai_agents/project/workflow.py b/examples/tutorials/10_async/10_temporal/120_openai_agents/project/workflow.py index 5cb8fb38b..2bc5b225c 100644 --- a/examples/tutorials/10_async/10_temporal/120_openai_agents/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/120_openai_agents/project/workflow.py @@ -64,23 +64,32 @@ def __init__(self): @workflow.signal(name=SignalName.RECEIVE_EVENT) async def on_task_event_send(self, params: SendEventParams) -> None: """Handle a user message: echo it, then run the harness activity durably.""" + # Validate before any side effect, and return instead of raising: an + # exception here fails the workflow task, and Temporal retries it forever. + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", params.task.id, getattr(content, "type", None) + ) + return + logger.info(f"Received task event: {params.task.id}") self._turn_number += 1 # Echo the user's message so it shows up in the UI as a chat bubble. - await adk.messages.create(task_id=params.task.id, content=params.event.content) + await adk.messages.create(task_id=params.task.id, content=content) async with adk.tracing.span( trace_id=params.task.id, task_id=params.task.id, name=f"Turn {self._turn_number}", - input={"message": params.event.content.content}, + input={"message": content.content}, ) as span: turn_result = await workflow.execute_activity( RUN_AGENT_ACTIVITY, RunHarnessAgentParams( task_id=params.task.id, - user_message=params.event.content.content, + user_message=content.content, input_list=self._messages, trace_id=params.task.id, parent_span_id=span.id if span else None, diff --git a/examples/tutorials/10_async/10_temporal/120_openai_agents/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/120_openai_agents/tests/test_agent.py index dd043c44c..fd2e2858c 100644 --- a/examples/tutorials/10_async/10_temporal/120_openai_agents/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/120_openai_agents/tests/test_agent.py @@ -1,20 +1,36 @@ -"""Offline test for the Temporal OpenAI Agents harness tutorial. +"""Offline tests for the Temporal OpenAI Agents harness tutorial. -This test does NOT require a running Agentex server, Temporal, Redis, or an -OpenAI API key. It verifies the delivery path the harness activity uses: an +These tests do NOT require a running Agentex server, Temporal, Redis, or an +OpenAI API key. They verify the delivery path the harness activity uses: an ``OpenAITurn`` built from an injected canonical stream, pushed through ``UnifiedEmitter.auto_send_turn`` with an injected fake streaming backend, returns the accumulated final text (which the activity returns to the workflow). +They also call the workflow's signal handler directly (collaborators patched): +a user text event runs a turn through the harness activity, and an event the +handler cannot process (no content, or content that is not text) is ignored +without raising and without side effects. + To run: ``pytest tests/test_agent.py -v`` """ from __future__ import annotations +from types import SimpleNamespace +from typing import Any +from datetime import datetime, timezone +from unittest.mock import AsyncMock, MagicMock + import pytest +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent from agentex.types.task_message import TaskMessage from agentex.types.text_content import TextContent +from agentex.types.reasoning_content import ReasoningContent from agentex.lib.core.harness.emitter import UnifiedEmitter from agentex.types.task_message_delta import TextDelta from agentex.types.task_message_update import ( @@ -22,6 +38,8 @@ StreamTaskMessageDelta, StreamTaskMessageStart, ) +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent from agentex.lib.adk.providers._modules.openai_turn import OpenAITurn @@ -73,5 +91,132 @@ async def test_activity_delivery_returns_final_text(): assert result.final_text == "72F" +# --------------------------------------------------------------------------- +# Signal handler (no Temporal, Redis or API key needed) +# --------------------------------------------------------------------------- + +TASK_ID = "task-1" + +# Event content a caller can send that the handler cannot process: Event.content +# is optional, and only TextContent carries a ``content: str``. +NON_TEXT_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="weather", tool_call_id="call-1", arguments={"city": "Paris"}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="weather", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="weather", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent( + id="agent-1", acp_type="async", name="at120-openai-agents", description="", created_at=now, updated_at=now + ), + task=Task(id=TASK_ID), + event=Event(id="event-1", agent_id="agent-1", task_id=TASK_ID, sequence_id=1, content=content), + ) + + +class _FakeSpan: + id = "span-1" + output: Any = None + + async def __aenter__(self): + return self + + async def __aexit__(self, *a): + pass + + +@pytest.fixture +def workflow_module(): + """``project.workflow``; conftest.py sets the env vars it reads at import time.""" + import project.workflow + + return project.workflow + + +@pytest.fixture +def mocks(workflow_module, monkeypatch): + """Patch what the signal handler calls, so it runs without Temporal, a model or a server.""" + turn_result = workflow_module.RunHarnessAgentResult( + final_text="72F", + input_list=[ + {"role": "user", "content": "What is the weather in Paris?"}, + {"role": "assistant", "content": "72F"}, + ], + ) + m = SimpleNamespace( + create=AsyncMock(), + span=MagicMock(return_value=_FakeSpan()), + execute_activity=AsyncMock(return_value=turn_result), + ) + monkeypatch.setattr(workflow_module.adk.messages, "create", m.create) + monkeypatch.setattr(workflow_module.adk.tracing, "span", m.span) + monkeypatch.setattr(workflow_module.workflow, "execute_activity", m.execute_activity) + monkeypatch.setattr(workflow_module.workflow, "now", lambda: None) + return m + + +def _new_workflow(workflow_module): + """A workflow instance with the attributes ``__init__`` sets, built without a Temporal runtime.""" + wf = workflow_module.At140HarnessOpenaiWorkflow.__new__(workflow_module.At140HarnessOpenaiWorkflow) + wf.display_name = "at120-openai-agents" + wf._complete_task = False + wf._turn_number = 0 + wf._messages = [] + return wf + + +@pytest.mark.asyncio +async def test_user_text_event_runs_harness_activity(workflow_module, mocks): + """A user text event is echoed and run through the harness activity; the history is carried forward.""" + wf = _new_workflow(workflow_module) + content = TextContent(author="user", content="What is the weather in Paris?") + + await wf.on_task_event_send(_send_event_params(content)) + + mocks.create.assert_awaited_once_with(task_id=TASK_ID, content=content) + mocks.execute_activity.assert_awaited_once() + activity_params = mocks.execute_activity.await_args.args[1] + assert activity_params.user_message == "What is the weather in Paris?" + assert activity_params.input_list == [] + assert wf._turn_number == 1 + assert wf._messages == mocks.execute_activity.return_value.input_list + + +@pytest.mark.asyncio +@pytest.mark.parametrize("content", NON_TEXT_CONTENTS) +async def test_non_text_event_is_ignored(workflow_module, mocks, content): + """An event the handler cannot process is ignored: no exception, no side effects. + + An exception raised by a signal handler fails the workflow task, and + Temporal retries it forever by replaying the same signal from history, so + the task's workflow would never process another event. + """ + wf = _new_workflow(workflow_module) + + await wf.on_task_event_send(_send_event_params(content)) + + mocks.create.assert_not_awaited() + mocks.span.assert_not_called() + mocks.execute_activity.assert_not_awaited() + assert wf._turn_number == 0 + assert wf._messages == [] + + if __name__ == "__main__": pytest.main([__file__, "-v"]) diff --git a/examples/tutorials/10_async/10_temporal/130_langgraph/conftest.py b/examples/tutorials/10_async/10_temporal/130_langgraph/conftest.py new file mode 100644 index 000000000..467d5f39f --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/130_langgraph/conftest.py @@ -0,0 +1,46 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at130-langgraph", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at130-langgraph", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/130_langgraph/project/workflow.py b/examples/tutorials/10_async/10_temporal/130_langgraph/project/workflow.py index b9224ca00..e76fc4a65 100644 --- a/examples/tutorials/10_async/10_temporal/130_langgraph/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/130_langgraph/project/workflow.py @@ -49,8 +49,17 @@ def __init__(self) -> None: @workflow.signal(name=SignalName.RECEIVE_EVENT) async def on_task_event_send(self, params: SendEventParams) -> None: """Echo the user's message, run the graph, surface the new messages.""" - await adk.messages.create(task_id=params.task.id, content=params.event.content) - self._messages.append({"role": "user", "content": params.event.content.content}) + # Validate before any side effect, and return instead of raising: an + # exception here fails the workflow task, and Temporal retries it forever. + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", params.task.id, getattr(content, "type", None) + ) + return + + await adk.messages.create(task_id=params.task.id, content=content) + self._messages.append({"role": "user", "content": content.content}) compiled = lg_graph(GRAPH_NAME).compile() result = await compiled.ainvoke({"messages": self._messages}) diff --git a/examples/tutorials/10_async/10_temporal/130_langgraph/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/130_langgraph/tests/test_agent.py index f2292389f..6f85ea57f 100644 --- a/examples/tutorials/10_async/10_temporal/130_langgraph/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/130_langgraph/tests/test_agent.py @@ -6,6 +6,12 @@ (proving the LLM node ran as a Temporal activity and the tool node ran), - the final answer reflects the tool output. +The offline tests at the end of this file (``TestSignalHandlerOffline``) call the +workflow's signal handler directly, with its collaborators patched, and need no +running agent: a user text event runs the graph, and an event the handler cannot +process (no content, or content that is not text) is ignored without raising +and without side effects. + To run: 1. Start the agent (worker + ACP server): ``agentex agents run --manifest manifest.yaml`` 2. Set AGENTEX_API_BASE_URL if not using the default @@ -14,6 +20,10 @@ import os import uuid +from types import SimpleNamespace +from typing import Any +from datetime import datetime, timezone +from unittest.mock import AsyncMock, MagicMock import pytest import pytest_asyncio @@ -23,8 +33,17 @@ ) from agentex import AsyncAgentex +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent from agentex.types.task_message import TaskMessage +from agentex.types.text_content import TextContent from agentex.types.agent_rpc_params import ParamsCreateTaskRequest +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent AGENTEX_API_BASE_URL = os.environ.get("AGENTEX_API_BASE_URL", "http://localhost:5003") AGENT_NAME = os.environ.get("AGENT_NAME", "at130-langgraph") @@ -102,5 +121,116 @@ async def test_send_event_and_poll(self, client: AsyncAgentex, agent_id: str): assert "72" in final_text, "Expected weather response to mention 72°F" +# --------------------------------------------------------------------------- +# Offline signal-handler tests (no running agent, Temporal or API key needed) +# --------------------------------------------------------------------------- + +TASK_ID = "task-offline" + +# Event content a caller can send that the handler cannot process: Event.content +# is optional, and only TextContent carries a ``content: str``. +NON_TEXT_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="get_weather", tool_call_id="call-1", arguments={"city": "Paris"}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name=AGENT_NAME, description="", created_at=now, updated_at=now), + task=Task(id=TASK_ID), + event=Event(id="event-1", agent_id="agent-1", task_id=TASK_ID, sequence_id=1, content=content), + ) + + +@pytest.fixture +def workflow_module(): + """``project.workflow``; conftest.py sets the env vars it reads at import time.""" + import project.workflow + + return project.workflow + + +@pytest.fixture +def mocks(workflow_module, monkeypatch): + """Patch what the signal handler calls, so it runs without Temporal, a model or a server.""" + + async def _ainvoke(state): + return {"messages": [*state["messages"], {"role": "assistant", "content": "It is 72°F."}]} + + graph = MagicMock() + graph.compile.return_value.ainvoke = AsyncMock(side_effect=_ainvoke) + m = SimpleNamespace(create=AsyncMock(), lg_graph=MagicMock(return_value=graph), emit=AsyncMock()) + monkeypatch.setattr(workflow_module.adk.messages, "create", m.create) + monkeypatch.setattr(workflow_module, "lg_graph", m.lg_graph) + monkeypatch.setattr(workflow_module, "emit_langgraph_messages", m.emit) + return m + + +def _new_workflow(workflow_module): + """A workflow instance with the attributes ``__init__`` sets, built without a Temporal runtime.""" + wf = workflow_module.AtHarnessLanggraphWorkflow.__new__(workflow_module.AtHarnessLanggraphWorkflow) + wf.display_name = AGENT_NAME + wf._complete_task = False + wf._messages = [] + wf._emitted = 0 + return wf + + +class TestSignalHandlerOffline: + """The signal handler, called directly with real event payloads.""" + + @pytest.mark.asyncio + async def test_user_text_event_runs_graph(self, workflow_module, mocks): + """A user text event is echoed, run through the graph, and the new messages surfaced.""" + wf = _new_workflow(workflow_module) + content = TextContent(author="user", content="What is the weather in Paris?") + + await wf.on_task_event_send(_send_event_params(content)) + + mocks.create.assert_awaited_once_with(task_id=TASK_ID, content=content) + mocks.lg_graph.assert_called_once_with(workflow_module.GRAPH_NAME) + assert wf._messages == [ + {"role": "user", "content": "What is the weather in Paris?"}, + {"role": "assistant", "content": "It is 72°F."}, + ] + mocks.emit.assert_awaited_once_with(wf._messages, TASK_ID) + assert wf._emitted == 2 + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", NON_TEXT_CONTENTS) + async def test_non_text_event_is_ignored(self, workflow_module, mocks, content): + """An event the handler cannot process is ignored: no exception, no side effects. + + An exception raised by a signal handler fails the workflow task, and + Temporal retries it forever by replaying the same signal from history, so + the task's workflow would never process another event. + """ + wf = _new_workflow(workflow_module) + + await wf.on_task_event_send(_send_event_params(content)) + + mocks.create.assert_not_awaited() + mocks.lg_graph.assert_not_called() + mocks.emit.assert_not_awaited() + assert wf._messages == [] + assert wf._emitted == 0 + + if __name__ == "__main__": pytest.main([__file__, "-v"]) diff --git a/examples/tutorials/10_async/10_temporal/140_claude_code/conftest.py b/examples/tutorials/10_async/10_temporal/140_claude_code/conftest.py new file mode 100644 index 000000000..14b5c3d91 --- /dev/null +++ b/examples/tutorials/10_async/10_temporal/140_claude_code/conftest.py @@ -0,0 +1,46 @@ +"""Pytest setup for this tutorial's tests. + +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. +""" + +from __future__ import annotations + +import os +import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at140-claude-code", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at140-claude-code", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] + + +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/140_claude_code/project/workflow.py b/examples/tutorials/10_async/10_temporal/140_claude_code/project/workflow.py index 7f50ba8d5..9b4240953 100644 --- a/examples/tutorials/10_async/10_temporal/140_claude_code/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/140_claude_code/project/workflow.py @@ -75,12 +75,21 @@ def __init__(self): @workflow.signal(name=SignalName.RECEIVE_EVENT) async def on_task_event_send(self, params: SendEventParams) -> None: """Handle a user message: spawn Claude Code and push events to the task stream.""" + # Validate before any side effect, and return instead of raising: an + # exception here fails the workflow task, and Temporal retries it forever. + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", params.task.id, getattr(content, "type", None) + ) + return + self._turn_number += 1 task_id = params.task.id - prompt = params.event.content.content + prompt = content.content logger.info("Turn %d for task %s", self._turn_number, task_id) - await adk.messages.create(task_id=task_id, content=params.event.content) + await adk.messages.create(task_id=task_id, content=content) async with adk.tracing.span( trace_id=task_id, diff --git a/examples/tutorials/10_async/10_temporal/140_claude_code/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/140_claude_code/tests/test_agent.py index 767c707b9..300c99574 100644 --- a/examples/tutorials/10_async/10_temporal/140_claude_code/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/140_claude_code/tests/test_agent.py @@ -6,11 +6,15 @@ - Run the full agent end-to-end against a live Agentex server. - Skipped automatically when ``CLAUDE_LIVE_TESTS`` is not set to ``1``. -OFFLINE unit tests (``TestClaudeCodeOffline``): +OFFLINE unit tests (``TestClaudeCodeOffline``, ``TestClaudeCodeWorkflowOffline``): - Inject a fake async iterator of pre-recorded stream-json lines. - Assert the ``ClaudeCodeTurn`` + ``UnifiedEmitter`` pipeline drives ``auto_send_turn``, populates usage, and satisfies the ``HarnessTurn`` protocol. + - Call the workflow's signal handler directly (collaborators patched) and + assert it runs a turn for a user text event, and ignores events it cannot + process (no content, or content that is not text) without raising and + without side effects. - Always run -- no CLI or API key needed. """ @@ -18,11 +22,23 @@ import os import json -from typing import AsyncIterator +from types import SimpleNamespace +from typing import Any, AsyncIterator +from datetime import datetime, timezone +from unittest.mock import AsyncMock, MagicMock import pytest +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent from agentex.types.task_message import TaskMessage +from agentex.types.text_content import TextContent +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent # --------------------------------------------------------------------------- # Recorded stream-json fixtures @@ -173,6 +189,128 @@ async def test_session_id_captured_in_result_envelope(self): assert turn._result_envelope.get("session_id") == "sess-temporal-offline-1" +# --------------------------------------------------------------------------- +# Offline signal-handler tests (always run -- no Temporal, CLI or API key needed) +# --------------------------------------------------------------------------- + +TASK_ID = "task-temporal-offline" + +# Event content a caller can send that the handler cannot process: Event.content +# is optional, and only TextContent carries a ``content: str``. +NON_TEXT_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="Bash", tool_call_id="call-1", arguments={"command": "ls"}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="Bash", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="Bash", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent( + id="agent-1", acp_type="async", name="at140-claude-code", description="", created_at=now, updated_at=now + ), + task=Task(id=TASK_ID), + event=Event(id="event-1", agent_id="agent-1", task_id=TASK_ID, sequence_id=1, content=content), + ) + + +class _FakeSpan: + id = "span-temporal-offline" + output: Any = None + + async def __aenter__(self): + return self + + async def __aexit__(self, *a): + pass + + +@pytest.fixture +def workflow_module(): + """``project.workflow``; conftest.py sets the env vars it reads at import time.""" + import project.workflow + + return project.workflow + + +@pytest.fixture +def mocks(workflow_module, monkeypatch): + """Patch what the signal handler calls, so it runs without Temporal, the CLI or a server.""" + m = SimpleNamespace( + create=AsyncMock(), + span=MagicMock(return_value=_FakeSpan()), + execute_activity=AsyncMock(return_value={"final_text": "hello from claude", "session_id": "sess-1"}), + ) + monkeypatch.setattr(workflow_module.adk.messages, "create", m.create) + monkeypatch.setattr(workflow_module.adk.tracing, "span", m.span) + monkeypatch.setattr(workflow_module.workflow, "execute_activity", m.execute_activity) + monkeypatch.setattr(workflow_module.workflow, "now", lambda: None) + return m + + +def _new_workflow(workflow_module): + """A workflow instance with the attributes ``__init__`` sets, built without a Temporal runtime.""" + wf = workflow_module.At140ClaudeCodeWorkflow.__new__(workflow_module.At140ClaudeCodeWorkflow) + wf.display_name = "at140-claude-code" + wf._complete_task = False + wf._turn_number = 0 + wf._session_id = None + return wf + + +class TestClaudeCodeWorkflowOffline: + """The signal handler, called directly with real event payloads.""" + + @pytest.mark.asyncio + async def test_user_text_event_runs_turn(self, workflow_module, mocks): + """A user text event is echoed, run through the activity, and its session_id kept.""" + wf = _new_workflow(workflow_module) + content = TextContent(author="user", content="say hello") + + await wf.on_task_event_send(_send_event_params(content)) + + mocks.create.assert_awaited_once_with(task_id=TASK_ID, content=content) + mocks.execute_activity.assert_awaited_once() + activity_params = mocks.execute_activity.await_args.args[1] + assert activity_params.prompt == "say hello" + assert activity_params.session_id is None + assert wf._turn_number == 1 + assert wf._session_id == "sess-1" + + @pytest.mark.asyncio + @pytest.mark.parametrize("content", NON_TEXT_CONTENTS) + async def test_non_text_event_is_ignored(self, workflow_module, mocks, content): + """An event the handler cannot process is ignored: no exception, no side effects. + + An exception raised by a signal handler fails the workflow task, and + Temporal retries it forever by replaying the same signal from history, so + the task's workflow would never process another event. + """ + wf = _new_workflow(workflow_module) + + await wf.on_task_event_send(_send_event_params(content)) + + mocks.create.assert_not_awaited() + mocks.span.assert_not_called() + mocks.execute_activity.assert_not_awaited() + assert wf._turn_number == 0 + assert wf._session_id is None + + # --------------------------------------------------------------------------- # Live tests (skipped unless CLAUDE_LIVE_TESTS=1) # --------------------------------------------------------------------------- diff --git a/examples/tutorials/10_async/10_temporal/150_codex/conftest.py b/examples/tutorials/10_async/10_temporal/150_codex/conftest.py index 6370f278d..09c62fe5f 100644 --- a/examples/tutorials/10_async/10_temporal/150_codex/conftest.py +++ b/examples/tutorials/10_async/10_temporal/150_codex/conftest.py @@ -1,17 +1,47 @@ -"""Add the agent's project root to sys.path so ``import project`` works. +"""Pytest setup for this tutorial's tests. -Also sets minimal environment variables so FastACP, tracing, and the -Temporal workflow module can be imported without a running server. +``project.workflow`` reads environment variables when it is imported, so the offline tests need them set and +this tutorial's ``project`` package importable. Both are arranged here for this tutorial's tests only. Any +``project`` package already imported (another tutorial's, in a session that collects several) is cleared before +and after them, and so is the SDK's cached ``EnvironmentVariables``, so this tutorial's workflow reads its own +values. """ +from __future__ import annotations + import os import sys +from collections.abc import Iterator + +import pytest + +TUTORIAL_DIR = os.path.dirname(os.path.abspath(__file__)) + +# Values already set in the environment win. +ENV_DEFAULTS = { + "AGENT_NAME": "at150-codex", + "ACP_URL": "http://localhost:8000", + "WORKFLOW_NAME": "at150-codex", + "WORKFLOW_TASK_QUEUE": "at150_codex_queue", +} + + +def _forget_project_modules() -> None: + for name in [name for name in sys.modules if name == "project" or name.startswith("project.")]: + del sys.modules[name] -sys.path.insert(0, os.path.dirname(__file__)) -# AGENT_NAME must match the manifest's agent name: the live test queries the -# server by this name, and project.workflow reads it at import time. -os.environ.setdefault("AGENT_NAME", "at150-codex") -os.environ.setdefault("ACP_URL", "http://localhost:8000") -os.environ.setdefault("WORKFLOW_NAME", "at150-codex") -os.environ.setdefault("WORKFLOW_TASK_QUEUE", "at150_codex_queue") +@pytest.fixture(autouse=True, scope="module") +def _tutorial_environment() -> Iterator[None]: + with pytest.MonkeyPatch.context() as patch: + for name, value in ENV_DEFAULTS.items(): + if not os.environ.get(name): + patch.setenv(name, value) + patch.syspath_prepend(TUTORIAL_DIR) + # EnvironmentVariables.refresh() keeps the first values it reads for the whole process. + patch.setattr("agentex.lib.environment_variables.refreshed_environment_variables", None) + _forget_project_modules() + try: + yield + finally: + _forget_project_modules() diff --git a/examples/tutorials/10_async/10_temporal/150_codex/project/workflow.py b/examples/tutorials/10_async/10_temporal/150_codex/project/workflow.py index 1970b478f..5ac6f6516 100644 --- a/examples/tutorials/10_async/10_temporal/150_codex/project/workflow.py +++ b/examples/tutorials/10_async/10_temporal/150_codex/project/workflow.py @@ -76,12 +76,21 @@ def __init__(self): @workflow.signal(name=SignalName.RECEIVE_EVENT) async def on_task_event_send(self, params: SendEventParams) -> None: """Handle a new user message: spawn codex, stream events via UnifiedEmitter.""" + # Validate before any side effect, and return instead of raising: an + # exception here fails the workflow task, and Temporal retries it forever. + content = params.event.content + if not isinstance(content, TextContent): + logger.warning( + "Ignoring non-text event for task %s (type=%s)", params.task.id, getattr(content, "type", None) + ) + return + logger.info("Received task event: %s", params.task.id) self._turn_number += 1 - await adk.messages.create(task_id=params.task.id, content=params.event.content) + await adk.messages.create(task_id=params.task.id, content=content) - user_message = params.event.content.content + user_message = content.content async with adk.tracing.span( trace_id=params.task.id, diff --git a/examples/tutorials/10_async/10_temporal/150_codex/tests/test_agent.py b/examples/tutorials/10_async/10_temporal/150_codex/tests/test_agent.py index fa6c66083..d4fd3c2c5 100644 --- a/examples/tutorials/10_async/10_temporal/150_codex/tests/test_agent.py +++ b/examples/tutorials/10_async/10_temporal/150_codex/tests/test_agent.py @@ -9,6 +9,8 @@ - Inject a fake async iterator of pre-recorded codex event lines. - Assert the signal handler drives ``UnifiedEmitter.auto_send_turn`` and captures the codex thread ID on the workflow instance. + - Assert the signal handler ignores events it cannot process (no content, or + content that is not text) without raising and without side effects. - Always run. """ @@ -17,14 +19,58 @@ import os import json from typing import Any +from datetime import datetime, timezone from unittest.mock import AsyncMock, MagicMock, patch import pytest +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent +from agentex.types.text_content import TextContent +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent + # --------------------------------------------------------------------------- # Shared helpers # --------------------------------------------------------------------------- +TASK_ID = "task-temporal-offline-1" + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name="at150-codex", description="", created_at=now, updated_at=now), + task=Task(id=TASK_ID), + event=Event(id="event-1", agent_id="agent-1", task_id=TASK_ID, sequence_id=1, content=content), + ) + + +# Event content a caller can send that the handler cannot process: Event.content +# is optional, and only TextContent carries a ``content: str``. +NON_TEXT_CONTENTS = [ + pytest.param(None, id="no-content"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="get_weather", tool_call_id="call-1", arguments={"city": "Paris"}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), +] + SAMPLE_EVENTS: list[dict[str, Any]] = [ {"type": "thread.started", "thread_id": "thread-temporal-1"}, {"type": "turn.started"}, @@ -128,6 +174,7 @@ async def test_signal_handler_delegates_to_activity_and_captures_thread_id(self) """Signal handler runs the turn via execute_activity, increments the turn counter, and captures the codex thread ID returned by the activity.""" captured: dict[str, Any] = {} + create = AsyncMock() async def _fake_execute_activity(_activity, params, **_kw): captured["params"] = params @@ -137,7 +184,7 @@ async def _fake_execute_activity(_activity, params, **_kw): "model": "o4-mini", } - with patch("project.workflow.adk.messages.create", new=AsyncMock()), patch( + with patch("project.workflow.adk.messages.create", new=create), patch( "project.workflow.adk.tracing.span" ) as mock_span, patch( "project.workflow.workflow.execute_activity", new=_fake_execute_activity @@ -152,17 +199,46 @@ async def _fake_execute_activity(_activity, params, **_kw): wf._complete_task = False wf._display_name = "test" - params = MagicMock() - params.task.id = "task-temporal-offline-1" - params.event.content.content = "say hello temporal" - - await wf.on_task_event_send(params) + content = TextContent(author="user", content="say hello temporal") + await wf.on_task_event_send(_send_event_params(content)) + create.assert_awaited_once_with(task_id=TASK_ID, content=content) assert wf._turn_number == 1 assert wf._codex_thread_id == "thread-temporal-1" assert captured["params"].prompt == "say hello temporal" assert captured["params"].thread_id is None + @pytest.mark.asyncio + @pytest.mark.parametrize("content", NON_TEXT_CONTENTS) + async def test_signal_handler_ignores_non_text_event(self, content): + """An event the handler cannot process is ignored: no exception, no side effects. + + An exception raised by a signal handler fails the workflow task, and + Temporal retries it forever by replaying the same signal from history, so + the task's workflow would never process another event. + """ + create = AsyncMock() + execute_activity = AsyncMock() + + with patch("project.workflow.adk.messages.create", new=create), patch( + "project.workflow.adk.tracing.span" + ) as mock_span, patch("project.workflow.workflow.execute_activity", new=execute_activity): + from project.workflow import AtHarnessCodexWorkflow + + wf = AtHarnessCodexWorkflow.__new__(AtHarnessCodexWorkflow) + wf.display_name = "test" + wf._complete_task = False + wf._turn_number = 0 + wf._codex_thread_id = None + + await wf.on_task_event_send(_send_event_params(content)) + + create.assert_not_awaited() + mock_span.assert_not_called() + execute_activity.assert_not_awaited() + assert wf._turn_number == 0 + assert wf._codex_thread_id is None + @pytest.mark.asyncio async def test_run_codex_turn_activity_streams_and_returns_thread_id(self): """The run_codex_turn activity drives the turn and returns the thread id.""" diff --git a/src/agentex/lib/cli/templates/temporal/project/workflow.py.j2 b/src/agentex/lib/cli/templates/temporal/project/workflow.py.j2 index 8c23ecfc1..82f52a55b 100644 --- a/src/agentex/lib/cli/templates/temporal/project/workflow.py.j2 +++ b/src/agentex/lib/cli/templates/temporal/project/workflow.py.j2 @@ -31,10 +31,18 @@ class {{ workflow_class }}(BaseWorkflow): @workflow.signal(name=SignalName.RECEIVE_EVENT) async def on_task_event_send(self, params: SendEventParams) -> None: + # Skip events this agent can't handle instead of raising: an exception here fails + # the workflow task, and Temporal replays the signal forever, wedging the task. + # Any content type can be echoed back, but an event can arrive with no content. + content = params.event.content + if content is None: + logger.warning("Ignoring event with no content for task %s", params.task.id) + return + logger.info(f"Received task message instruction: {params}") # 2. Echo back the client's message to show it in the UI. This is not done by default so the agent developer has full control over what is shown to the user. - await adk.messages.create(task_id=params.task.id, content=params.event.content) + await adk.messages.create(task_id=params.task.id, content=content) # 3. Send a simple response message. # In future tutorials, this is where we'll add more sophisticated response logic. diff --git a/src/agentex/lib/core/temporal/workers/signal_errors.py b/src/agentex/lib/core/temporal/workers/signal_errors.py new file mode 100644 index 000000000..eabe8a16a --- /dev/null +++ b/src/agentex/lib/core/temporal/workers/signal_errors.py @@ -0,0 +1,151 @@ +"""Stop one bad signal from wedging a Temporal workflow. + +When a signal handler raises an exception that Temporal does not treat as a workflow failure, the +*workflow task* fails. The server retries that task forever, every retry replays the same signal from +history and raises again, so the workflow never progresses and every later signal is ignored. +:class:`SignalHandlerErrorInterceptor` logs and drops such a signal instead, as Temporal already does for a +signal whose arguments fail to deserialize, and the workflow carries on. +""" + +from __future__ import annotations + +import sys +import contextlib +from typing import override + +from temporalio import workflow +from temporalio.worker import ( + Interceptor, + HandleSignalInput, + WorkflowInboundInterceptor, + WorkflowInterceptorClassInput, +) +from temporalio.exceptions import TemporalError + +from agentex.lib.core.temporal.logging import make_workflow_logger + +__all__ = ["SignalHandlerErrorInterceptor"] + +logger = make_workflow_logger(__name__) + + +class SignalHandlerErrorInterceptor(Interceptor): + """Worker interceptor that logs and drops a signal whose handler raises an unexpected exception. + + Without it, one malformed event (``content`` that is ``None``, a ``DataContent``, a + ``ToolResponseContent`` holding a dict, ...) sent to a handler that assumes text wedges the task's + workflow forever. With it, the exception is logged replay-safely with the signal name and the workflow + and run IDs, and the handler returns normally. The signal's arguments are not logged, but the + exception's message and traceback are, and they can quote parts of them (a pydantic ``ValidationError`` + shows the rejected input). + + Everything Temporal gives a deliberate meaning to is re-raised unchanged: exceptions that + ``workflow.is_failure_exception`` accepts still fail the workflow (any ``FailureError`` such as + ``ApplicationError``, ``asyncio.TimeoutError``, and types declared with + ``@workflow.defn(failure_exception_types=...)`` or the worker's ``workflow_failure_exception_types``); + the SDK's own errors that are not declared failures (``NondeterminismError``, the sandbox's + ``RestrictedWorkflowAccessError``, ``ReadOnlyContextError``, ...) still fail the task, also inside an + ``ExceptionGroup`` that is not itself a failure exception; and ``BaseException``s such as + ``asyncio.CancelledError`` and continue-as-new are never caught. Any other exception group, such as one from an ``asyncio.TaskGroup`` + whose child raised an ``ApplicationError``, is dropped: Temporal does not look inside groups, so + re-raising it would fail the task on every retry rather than fail the workflow. + + Two consequences to keep in mind: + + - Dropping is not a rollback. Whatever the handler did before it raised is kept: state it changed, + and activities, timers or child workflows it started. Validate a signal's input before acting on it. + - Once a signal has been dropped, the workflow's history depends on the drop. A worker that replays + that history without this interceptor (``drop_signals_on_handler_error=False``, an SDK version from + before it, or a ``temporalio.worker.Replayer`` built without it) raises in the handler again and + fails the workflow task, wedging the workflow until a worker with the interceptor picks it up. Pass + ``interceptors=[SignalHandlerErrorInterceptor()]`` to replay tests, and avoid turning it off or rolling + back past it while such workflows are open. + + ``AgentexWorker`` installs it by default (``drop_signals_on_handler_error=False`` opts out). A worker + built directly with ``temporalio.worker.Worker`` should list it before its own interceptors, so they + still see the exception:: + + Worker(client, ..., interceptors=[SignalHandlerErrorInterceptor(), *my_interceptors]) + """ + + @override + def workflow_interceptor_class(self, input: WorkflowInterceptorClassInput) -> type[WorkflowInboundInterceptor]: + return _SignalHandlerErrorInboundInterceptor + + +class _SignalHandlerErrorInboundInterceptor(WorkflowInboundInterceptor): + @override + async def handle_signal(self, input: HandleSignalInput) -> None: + try: + return await self.next.handle_signal(input) + except Exception as err: # not BaseException: cancellation, continue-as-new and eviction pass through + if _left_to_temporal(err): + raise + _log_dropped_signal(input.signal, err) + + +def _left_to_temporal(err: Exception) -> bool: + """Whether ``err`` must reach Temporal as raised rather than be dropped with its signal. + + Mirrors temporalio's ``_WorkflowInstanceImpl._run_top_level_workflow_function``, which fails the + workflow for an exception ``workflow.is_failure_exception`` accepts (a ``FailureError``, + ``asyncio.TimeoutError``, or a type declared on the workflow definition, a dynamic workflow's config or + the worker) and fails the task for any other ``Exception``. Of the latter, the SDK's own errors + (``NondeterminismError`` and the sandbox's ``RestrictedWorkflowAccessError``, ``ReadOnlyContextError``, + ...) mean the code broke Temporal's rules rather than met bad input, so failing the task until the code + is fixed stays their outcome. + + temporalio applies that test to an exception group (e.g. from ``asyncio.TaskGroup``) as a whole and never + looks inside it, so a group fails the task unless the group itself is a failure exception. A group is + therefore left to Temporal when the group itself is a ``TemporalError`` or a failure exception, or when + it holds, at any depth, a ``TemporalError`` that is not itself a failure exception (one Temporal would + fail the task for if it were raised alone). Any other group + is dropped like any other unexpected exception, because re-raising it would wedge the workflow rather + than fail it. That includes a group holding only failure exceptions, even a ``TemporalError`` declared + as one, such as the ``AgentsWorkflowError`` that the OpenAI Agents plugin declares. + """ + if isinstance(err, TemporalError) or workflow.is_failure_exception(err): + return True + if not isinstance(err, BaseExceptionGroup): + return False + # Walked iteratively rather than with BaseExceptionGroup.subgroup(), which recurses and calls the group's + # derive(): anything raised here would replace the handler's exception and fail the task after all. + pending: list[BaseException] = list(err.exceptions) + while pending: + exc = pending.pop() + if isinstance(exc, TemporalError) and not workflow.is_failure_exception(exc): + return True + if isinstance(exc, BaseExceptionGroup): + pending.extend(exc.exceptions) + return False + + +def _log_dropped_signal(signal: str, err: Exception) -> None: + # The signal's arguments are left out on purpose: the caller controls them and they can carry user content. + info: workflow.Info | None = None + try: + info = workflow.info() + # Handlers may import lazily while emitting (rich's does). Inside temporalio's default sandbox that can + # raise RestrictedWorkflowAccessError and lose the record for every handler, so log with the sandbox's + # restrictions lifted and imports passed through; outside a sandbox both are no-ops. + with workflow.unsafe.sandbox_unrestricted(), workflow.unsafe.imports_passed_through(): + logger.error( + "Dropped signal %r to workflow %s (type %s, run %s): its handler raised %s. Anything the handler " + "did before raising is kept; the workflow keeps running and handles later signals.", + signal, + info.workflow_id, + info.workflow_type, + info.run_id, + type(err).__qualname__, + exc_info=err, + extra={"signal_name": signal}, + ) + except Exception as log_err: + # Failing to log must not fail the workflow task this interceptor exists to keep alive, but the drop must + # not be silent either, so fall back to one bare stderr line (still without the signal's arguments). + with contextlib.suppress(Exception): + where = "" if info is None else f" to workflow {info.workflow_id} (run {info.run_id})" + sys.stderr.write( + f"agentex: dropped signal {signal!r}{where} after its handler raised {type(err).__qualname__}; " + f"logging the drop failed with {type(log_err).__qualname__}\n" + ) diff --git a/src/agentex/lib/core/temporal/workers/worker.py b/src/agentex/lib/core/temporal/workers/worker.py index 8256cba03..e1a486fd0 100644 --- a/src/agentex/lib/core/temporal/workers/worker.py +++ b/src/agentex/lib/core/temporal/workers/worker.py @@ -35,6 +35,7 @@ from agentex.lib.core.compat.version_guard import assert_backend_compatible from agentex.lib.core.clients.temporal.auth import connect_temporal_client from agentex.lib.core.observability.sgp_obs_setup import init_sgp_obs, shutdown_sgp_obs +from agentex.lib.core.temporal.workers.signal_errors import SignalHandlerErrorInterceptor from agentex.lib.core.tracing.tracing_processor_manager import shutdown_sync_tracing_processors logger = make_logger(__name__) @@ -184,6 +185,7 @@ def __init__( metrics_use_http: bool = False, metrics_temporality_delta: bool = False, agent_card: Any | None = None, + drop_signals_on_handler_error: bool = True, ): self.task_queue = task_queue self.activity_handles = [] @@ -203,6 +205,11 @@ def __init__( self.payload_codec = payload_codec self.data_converter = data_converter self.agent_card = agent_card + # True installs SignalHandlerErrorInterceptor: a signal whose handler raises an unexpected exception is + # logged and dropped, instead of failing the workflow task on every retry and wedging the workflow. + # Turning it off (or rolling back to an SDK without it) while workflows that already dropped a signal + # are open makes their replay raise again and wedges them; see SignalHandlerErrorInterceptor. + self.drop_signals_on_handler_error = drop_signals_on_handler_error @overload async def run( @@ -245,6 +252,15 @@ async def run( # Validate interceptors if any are provided if self.interceptors: _validate_interceptors(self.interceptors) + interceptors = list(self.interceptors) + if self.drop_signals_on_handler_error and not any( + isinstance(interceptor, SignalHandlerErrorInterceptor) for interceptor in interceptors + ): + # First of the worker's own interceptors, so it wraps the caller's: they still see a signal handler's + # exception (and can raise an ApplicationError to fail the workflow on purpose) before it is dropped. + # The client's TracingInterceptor is prepended ahead of all of these by Temporal; it records only + # FailureErrors on signal spans, and those are re-raised, so traces are unchanged. + interceptors.insert(0, SignalHandlerErrorInterceptor()) temporal_client = await get_temporal_client( temporal_address=os.environ.get("TEMPORAL_ADDRESS", "localhost:7233"), @@ -276,7 +292,7 @@ async def run( build_id=str(uuid.uuid4()), debug_mode=debug_enabled, # Disable deadlock detection in debug mode # Temporal inherits client tracing before these business interceptors. - interceptors=self.interceptors, + interceptors=interceptors, ) logger.info(f"Starting workers for task queue: {self.task_queue}") diff --git a/tests/lib/cli/test_init_templates.py b/tests/lib/cli/test_init_templates.py index ec809cbbf..066573ec9 100644 --- a/tests/lib/cli/test_init_templates.py +++ b/tests/lib/cli/test_init_templates.py @@ -5,7 +5,8 @@ - every template type's declared project files exist and render, - rendered Python parses (catches `.j2` syntax/templating regressions), - the agent-specific context (names, workflow class) is substituted in, -- the Temporal + LangGraph template is fully wired (enum, file map, root files). +- the Temporal + LangGraph template is fully wired (enum, file map, root files), +- the base Temporal template's signal handler never raises on caller input. The Temporal + LangGraph template is the focus, but the parametrized smoke test covers every template so a broken `.j2` anywhere is caught early. @@ -14,15 +15,29 @@ from __future__ import annotations import ast +import importlib.util +from typing import Any from pathlib import Path +from datetime import datetime, timezone +from unittest.mock import AsyncMock, patch import pytest +from agentex.lib import environment_variables +from agentex.types.task import Task +from agentex.types.agent import Agent +from agentex.types.event import Event +from agentex.protocol.acp import SendEventParams +from agentex.types.data_content import DataContent +from agentex.types.text_content import TextContent from agentex.lib.cli.commands.init import ( TemplateType, get_project_context, create_project_structure, ) +from agentex.types.reasoning_content import ReasoningContent +from agentex.types.tool_request_content import ToolRequestContent +from agentex.types.tool_response_content import ToolResponseContent def _context(template_type: TemplateType, use_uv: bool = True) -> dict: @@ -137,3 +152,83 @@ def test_requirements_include_langgraph_plugin_and_temporal(self, tmp_path: Path requirements = (project_dir / "requirements.txt").read_text() assert "temporalio[langgraph]>=1.27.0" in requirements assert "langchain-openai" in requirements + + +def _send_event_params(content: Any) -> SendEventParams: + """Real ``SendEventParams``, as the ACP delivers an ``event/send`` to the workflow signal.""" + now = datetime.now(timezone.utc) + return SendEventParams( + agent=Agent(id="agent-1", acp_type="async", name="my-agent", description="", created_at=now, updated_at=now), + task=Task(id="task-1"), + event=Event(id="event-1", agent_id="agent-1", task_id="task-1", sequence_id=1, content=content), + ) + + +class TestTemporalTemplateSignalHandler: + """The base Temporal template's signal handler must never raise on caller input. + + An exception raised from a signal handler fails the workflow task, and Temporal + retries it (replaying the same signal) forever. These tests load the rendered + ``workflow.py`` and call the handler directly, with ``adk.messages`` mocked. + """ + + @staticmethod + def _rendered_workflow(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> tuple[Any, Any]: + """Return a workflow instance from the rendered template, and the ``adk.messages`` it uses.""" + project_dir = _render_project(tmp_path, TemplateType.TEMPORAL) + # The rendered module reads these at import time through a process-wide cache, + # reset here; monkeypatch restores the cache and the variables afterwards. + monkeypatch.setenv("AGENT_NAME", "my-agent") + monkeypatch.setenv("ACP_URL", "http://localhost:8000") + monkeypatch.setenv("WORKFLOW_NAME", "my-agent") + monkeypatch.setattr(environment_variables, "refreshed_environment_variables", None) + + spec = importlib.util.spec_from_file_location( + "rendered_temporal_workflow", project_dir / "project" / "workflow.py" + ) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + + # Build the instance without Temporal: skip __init__ and set what it would set. + wf = module.MyAgentWorkflow.__new__(module.MyAgentWorkflow) + wf.display_name = "my-agent" + wf._complete_task = False + return wf, module.adk.messages + + async def test_event_without_content_is_ignored(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch): + wf, messages = self._rendered_workflow(tmp_path, monkeypatch) + with patch.object(messages, "create", new=AsyncMock()) as create: + await wf.on_task_event_send(_send_event_params(None)) + + create.assert_not_awaited() + + @pytest.mark.parametrize( + "content", + [ + pytest.param(TextContent(author="user", content="Hello!"), id="text"), + pytest.param(DataContent(author="user", data={}), id="data"), + pytest.param(ReasoningContent(author="user", summary=["thinking"], type="reasoning"), id="reasoning"), + pytest.param( + ToolRequestContent(author="user", name="get_weather", tool_call_id="call-1", arguments={}), + id="tool-request", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content={"k": "v"}), + id="tool-response-dict", + ), + pytest.param( + ToolResponseContent(author="user", name="get_weather", tool_call_id="call-1", content=[1, 2]), + id="tool-response-list", + ), + ], + ) + async def test_event_is_echoed_then_answered(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, content: Any): + wf, messages = self._rendered_workflow(tmp_path, monkeypatch) + with patch.object(messages, "create", new=AsyncMock()) as create: + await wf.on_task_event_send(_send_event_params(content)) + + assert create.await_count == 2 + echo, reply = create.await_args_list + assert echo.kwargs == {"task_id": "task-1", "content": content} + assert reply.kwargs["content"].author == "agent" diff --git a/tests/lib/core/temporal/workers/test_signal_errors.py b/tests/lib/core/temporal/workers/test_signal_errors.py new file mode 100644 index 000000000..963f6a8e8 --- /dev/null +++ b/tests/lib/core/temporal/workers/test_signal_errors.py @@ -0,0 +1,437 @@ +"""SignalHandlerErrorInterceptor drops a signal whose handler raises unexpectedly, and re-raises the rest. + +The inbound interceptor runs here against a fake ``next`` and a faked workflow context (the same patches as +``tests/lib/core/temporal/test_workflow_logging.py``), so no Temporal server is needed. +``test_signal_errors_replay.py`` checks the same rules inside Temporal's real workflow runtime. +""" + +from __future__ import annotations + +import sys +import asyncio +import inspect +import logging +from types import SimpleNamespace +from typing import Any, override + +import pytest +import pydantic +from temporalio import workflow +from temporalio.worker import ( + HandleQueryInput, + HandleSignalInput, + HandleUpdateInput, + ExecuteWorkflowInput, + WorkflowInboundInterceptor, + WorkflowInterceptorClassInput, +) +from temporalio.exceptions import ( + FailureError, + TimeoutError as TemporalTimeoutError, + ActivityError, + TemporalError, + CancelledError as TemporalCancelledError, + ApplicationError, + ChildWorkflowError, +) +from temporalio.worker.workflow_sandbox import RestrictedWorkflowAccessError + +from agentex.lib.core.temporal.workers import signal_errors +from agentex.lib.core.temporal.workers.signal_errors import SignalHandlerErrorInterceptor + +SIGNAL = "receive_event" + + +class _DeclaredError(Exception): + """Stands in for a type listed in ``@workflow.defn(failure_exception_types=...)``.""" + + +class _DeclaredTemporalError(TemporalError): + """Stands in for a ``TemporalError`` declared a failure type, like the OpenAI Agents plugin's + ``AgentsWorkflowError``.""" + + +class _NondeterministicGroup(ExceptionGroup[Exception], workflow.NondeterminismError): + """An exception group that is itself one of the SDK's own errors.""" + + +class _ContinueAsNew(workflow.ContinueAsNewError): + """What ``workflow.continue_as_new`` raises; ``ContinueAsNewError`` itself cannot be constructed.""" + + +class _Evicted(BaseException): + """Stands in for temporalio's private ``_WorkflowBeingEvictedError``.""" + + +def _is_failure_exception(err: BaseException) -> bool: + # What temporalio's workflow_is_failure_exception answers for a workflow declaring the two _Declared* types. + return isinstance(err, (FailureError, asyncio.TimeoutError, _DeclaredError, _DeclaredTemporalError)) + + +@pytest.fixture(autouse=True) +def workflow_context(monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture): + caplog.set_level(logging.DEBUG, logger=signal_errors.logger.name) + + def enter(*, replaying: bool) -> None: + monkeypatch.setattr(workflow, "in_workflow", lambda: True) + monkeypatch.setattr( + workflow, + "info", + lambda: SimpleNamespace(workflow_id="task-123", run_id="run-456", workflow_type="ChatWorkflow"), + ) + monkeypatch.setattr(workflow.unsafe, "is_replaying_history_events", lambda: replaying) + monkeypatch.setattr(workflow, "is_failure_exception", _is_failure_exception) + + enter(replaying=False) + return enter + + +class _Terminal(WorkflowInboundInterceptor): + """End of the chain: records each call, then raises ``error`` or returns ``result``.""" + + def __init__(self, *, error: BaseException | None = None, result: Any = None) -> None: + # No super().__init__(): there is no next interceptor to delegate to. + self.error = error + self.result = result + self.calls: list[Any] = [] + + def _finish(self, input: Any) -> Any: + self.calls.append(input) + if self.error is not None: + raise self.error + return self.result + + @override + async def handle_signal(self, input: HandleSignalInput) -> None: + return self._finish(input) + + @override + async def execute_workflow(self, input: ExecuteWorkflowInput) -> Any: + return self._finish(input) + + @override + async def handle_query(self, input: HandleQueryInput) -> Any: + return self._finish(input) + + @override + def handle_update_validator(self, input: HandleUpdateInput) -> None: + self._finish(input) + + @override + async def handle_update_handler(self, input: HandleUpdateInput) -> Any: + return self._finish(input) + + +def _inbound(terminal: _Terminal) -> WorkflowInboundInterceptor: + interceptor_class = SignalHandlerErrorInterceptor().workflow_interceptor_class( + WorkflowInterceptorClassInput(unsafe_extern_functions={}) + ) + return interceptor_class(terminal) + + +def _signal(*args: Any) -> HandleSignalInput: + return HandleSignalInput(signal=SIGNAL, args=list(args) or [{"content": None}], headers={}) + + +def _dropped(caplog: pytest.LogCaptureFixture) -> list[logging.LogRecord]: + return [record for record in caplog.records if record.name == signal_errors.logger.name] + + +def _validation_error() -> pydantic.ValidationError: + # What a str-typed activity parameter raises when the event content is a dict rather than text. + try: + pydantic.TypeAdapter(str).validate_python({"type": "data"}) + except pydantic.ValidationError as err: + return err + raise AssertionError("expected a ValidationError") + + +def _activity_error() -> ActivityError: + return ActivityError( + "activity failed", + scheduled_event_id=5, + started_event_id=6, + identity="worker", + activity_type="call_llm", + activity_id="1", + retry_state=None, + ) + + +def _nested_group(depth: int, leaf: Exception) -> ExceptionGroup[Exception]: + group = ExceptionGroup("level 0", [leaf]) + for level in range(1, depth): + group = ExceptionGroup(f"level {level}", [group]) + return group + + +class _GroupThatCannotDerive(ExceptionGroup[Exception]): + """A group subclass whose ``derive()`` fails, as one with extra constructor arguments can.""" + + @override + def derive(self, excs: Any) -> ExceptionGroup[Exception]: + raise TypeError("cannot rebuild this group") + + +async def test_a_handled_signal_passes_through_untouched(caplog: pytest.LogCaptureFixture) -> None: + result = object() + terminal = _Terminal(result=result) + signal = _signal({"content": "hello"}) + + assert await _inbound(terminal).handle_signal(signal) is result + + assert len(terminal.calls) == 1 and terminal.calls[0] is signal + assert not _dropped(caplog) + + +@pytest.mark.parametrize( + "error", + [ + pytest.param(AttributeError("'DataContent' object has no attribute 'content'"), id="AttributeError"), + pytest.param(TypeError('can only concatenate str (not "dict") to str'), id="TypeError"), + pytest.param(ValueError("expected text content"), id="ValueError"), + pytest.param(KeyError("content"), id="KeyError"), + pytest.param(_validation_error(), id="pydantic-ValidationError"), + pytest.param(RuntimeError("any other handler bug"), id="RuntimeError"), + ], +) +async def test_an_unexpected_handler_exception_is_logged_and_the_signal_dropped( + caplog: pytest.LogCaptureFixture, error: Exception +) -> None: + assert await _inbound(_Terminal(error=error)).handle_signal(_signal()) is None + + (record,) = _dropped(caplog) + assert record.levelno == logging.ERROR + assert record.exc_info is not None and record.exc_info[1] is error + assert record.__dict__["signal_name"] == SIGNAL + assert record.__dict__["workflow_id"] == "task-123" + assert record.__dict__["run_id"] == "run-456" + message = record.getMessage() + for expected in (repr(SIGNAL), "task-123", "run-456", "ChatWorkflow", type(error).__qualname__): + assert expected in message + + +async def test_the_signal_arguments_are_never_logged(caplog: pytest.LogCaptureFixture) -> None: + sentinel = "user-content-4321" + event = {"content": {"type": "data", "data": {"note": sentinel}}} + + await _inbound(_Terminal(error=AttributeError("'dict' object has no attribute 'strip'"))).handle_signal( + _signal(event) + ) + + (record,) = _dropped(caplog) + assert sentinel not in caplog.text + assert all(sentinel not in repr(value) for value in record.__dict__.values()) + + +@pytest.mark.parametrize( + "error", + [ + # Temporal fails the workflow for these, deliberately. + pytest.param(ApplicationError("rejected the event", non_retryable=True), id="ApplicationError"), + pytest.param(_activity_error(), id="ActivityError"), + pytest.param( + ChildWorkflowError( + "child failed", + namespace="default", + workflow_id="child", + run_id="child-run", + workflow_type="Child", + initiated_event_id=5, + started_event_id=6, + retry_state=None, + ), + id="ChildWorkflowError", + ), + pytest.param(TemporalCancelledError("cancelled"), id="temporalio-CancelledError"), + pytest.param( + TemporalTimeoutError("timed out", type=None, last_heartbeat_details=[]), id="temporalio-TimeoutError" + ), + pytest.param(asyncio.TimeoutError(), id="asyncio-TimeoutError"), + pytest.param(_DeclaredError("declared in failure_exception_types"), id="declared-failure-exception-type"), + pytest.param(_DeclaredTemporalError("agent run failed"), id="declared-TemporalError"), + # The SDK's own errors: Temporal fails the task until the workflow code is fixed. + pytest.param(workflow.NondeterminismError("nondeterministic"), id="NondeterminismError"), + pytest.param(RestrictedWorkflowAccessError("datetime.datetime.now"), id="RestrictedWorkflowAccessError"), + pytest.param(workflow.ReadOnlyContextError("mutated in a read-only context"), id="ReadOnlyContextError"), + # Control flow, which is never caught at all. + pytest.param(asyncio.CancelledError(), id="asyncio-CancelledError"), + pytest.param(_ContinueAsNew(), id="continue-as-new"), + pytest.param(_Evicted(), id="eviction"), + ], +) +async def test_deliberate_outcomes_and_control_flow_propagate_unchanged( + caplog: pytest.LogCaptureFixture, error: BaseException +) -> None: + with pytest.raises(type(error)) as raised: + await _inbound(_Terminal(error=error)).handle_signal(_signal()) + + assert raised.value is error + assert not _dropped(caplog) + + +async def test_a_replayed_drop_is_not_logged_again(workflow_context, caplog: pytest.LogCaptureFixture) -> None: + workflow_context(replaying=True) + + assert await _inbound(_Terminal(error=AttributeError("no content"))).handle_signal(_signal()) is None + + assert not _dropped(caplog) + + +async def test_a_logging_failure_still_drops_the_signal_and_says_so_on_stderr( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + def broken(*args: Any, **kwargs: Any) -> None: + raise RuntimeError("log pipeline is down") + + monkeypatch.setattr(signal_errors.logger, "error", broken) + sentinel = "user-content-8642" + + assert ( + await _inbound(_Terminal(error=AttributeError("no content"))).handle_signal(_signal({"content": sentinel})) + is None + ) + + err = capsys.readouterr().err + for expected in (repr(SIGNAL), "task-123", "run-456", "AttributeError", "RuntimeError"): + assert expected in err + assert sentinel not in err + + +async def test_the_drop_is_logged_with_the_sandbox_lifted(caplog: pytest.LogCaptureFixture) -> None: + # Handlers that import while emitting (rich's) would otherwise hit RestrictedWorkflowAccessError inside + # temporalio's default sandbox and lose the record. + seen: list[tuple[bool, bool]] = [] + + class _Probe(logging.Handler): + @override + def emit(self, record: logging.LogRecord) -> None: + seen.append((workflow.unsafe.is_sandbox_unrestricted(), workflow.unsafe.is_imports_passed_through())) + + probe = _Probe() + signal_errors.logger.logger.addHandler(probe) + try: + await _inbound(_Terminal(error=AttributeError("no content"))).handle_signal(_signal()) + finally: + signal_errors.logger.logger.removeHandler(probe) + + assert seen == [(True, True)] + assert len(_dropped(caplog)) == 1 + assert not workflow.unsafe.is_sandbox_unrestricted() and not workflow.unsafe.is_imports_passed_through() + + +# temporalio checks an exception group as a whole and fails the task for any group that is not itself a failure +# exception, so a group re-raised for the failures inside it would wedge the workflow instead of failing it. +@pytest.mark.parametrize( + "error", + [ + pytest.param(ExceptionGroup("task group", [AttributeError("no content")]), id="plain-errors"), + pytest.param( + ExceptionGroup("outer", [ValueError("bad"), ExceptionGroup("inner", [KeyError("content")])]), + id="nested-plain-errors", + ), + pytest.param( + ExceptionGroup("unhandled errors in a TaskGroup", [ApplicationError("rejected", non_retryable=True)]), + id="ApplicationError", + ), + pytest.param(ExceptionGroup("unhandled errors in a TaskGroup", [_activity_error()]), id="ActivityError"), + pytest.param(ExceptionGroup("unhandled errors in a TaskGroup", [asyncio.TimeoutError()]), id="timeout"), + pytest.param( + ExceptionGroup("task group", [ValueError("bad"), ApplicationError("rejected", non_retryable=True)]), + id="mixed", + ), + pytest.param( + ExceptionGroup("outer", [ExceptionGroup("inner", [ApplicationError("rejected", non_retryable=True)])]), + id="nested-ApplicationError", + ), + pytest.param(ExceptionGroup("task group", [_DeclaredError("declared")]), id="declared-failure-exception-type"), + pytest.param( + ExceptionGroup("unhandled errors in a TaskGroup", [_DeclaredTemporalError("agent run failed")]), + id="declared-TemporalError", + ), + ], +) +async def test_an_exception_group_without_an_sdk_error_is_dropped( + caplog: pytest.LogCaptureFixture, error: ExceptionGroup[Exception] +) -> None: + assert await _inbound(_Terminal(error=error)).handle_signal(_signal()) is None + + (record,) = _dropped(caplog) + assert record.exc_info is not None and record.exc_info[1] is error + + +@pytest.mark.parametrize( + "error", + [ + pytest.param( + ExceptionGroup("task group", [ValueError("bad"), workflow.NondeterminismError("nondeterministic")]), + id="NondeterminismError", + ), + pytest.param( + ExceptionGroup( + "outer", [ExceptionGroup("inner", [RestrictedWorkflowAccessError("datetime.datetime.now")])] + ), + id="nested-RestrictedWorkflowAccessError", + ), + pytest.param( + ExceptionGroup( + "task group", + [ApplicationError("rejected", non_retryable=True), workflow.ReadOnlyContextError("mutated")], + ), + id="ReadOnlyContextError-beside-ApplicationError", + ), + pytest.param( + _GroupThatCannotDerive("task group", [ValueError("bad"), workflow.NondeterminismError("nondeterministic")]), + id="group-that-cannot-derive", + ), + pytest.param( + ExceptionGroup("outer", [_NondeterministicGroup("inner", [ValueError("bad")])]), + id="nested-group-that-is-an-sdk-error", + ), + ], +) +async def test_an_exception_group_holding_an_sdk_error_propagates_unchanged( + caplog: pytest.LogCaptureFixture, error: ExceptionGroup[Exception] +) -> None: + with pytest.raises(ExceptionGroup) as raised: + await _inbound(_Terminal(error=error)).handle_signal(_signal()) + + assert raised.value is error + assert not _dropped(caplog) + + +async def test_an_exception_group_that_is_itself_a_failure_exception_propagates( + monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture +) -> None: + # What a workflow declaring failure_exception_types=[Exception] gets: Temporal fails the workflow. + monkeypatch.setattr(workflow, "is_failure_exception", lambda err: isinstance(err, Exception)) + error = ExceptionGroup("task group", [AttributeError("no content")]) + + with pytest.raises(ExceptionGroup) as raised: + await _inbound(_Terminal(error=error)).handle_signal(_signal()) + + assert raised.value is error + assert not _dropped(caplog) + + +def test_a_group_nested_past_the_recursion_limit_is_classified_without_recursing() -> None: + depth = sys.getrecursionlimit() + 100 + + assert not signal_errors._left_to_temporal(_nested_group(depth, AttributeError("no content"))) + assert signal_errors._left_to_temporal(_nested_group(depth, workflow.NondeterminismError("nondeterministic"))) + + +@pytest.mark.parametrize( + "method", ["execute_workflow", "handle_query", "handle_update_validator", "handle_update_handler"] +) +async def test_only_signal_handling_is_changed(caplog: pytest.LogCaptureFixture, method: str) -> None: + error = AttributeError("not a signal") + inbound = _inbound(_Terminal(error=error)) + + with pytest.raises(AttributeError) as raised: + outcome = getattr(inbound, method)(object()) + if inspect.isawaitable(outcome): + await outcome + + assert raised.value is error + assert not _dropped(caplog) diff --git a/tests/lib/core/temporal/workers/test_signal_errors_e2e.py b/tests/lib/core/temporal/workers/test_signal_errors_e2e.py new file mode 100644 index 000000000..89e05dce9 --- /dev/null +++ b/tests/lib/core/temporal/workers/test_signal_errors_e2e.py @@ -0,0 +1,235 @@ +"""End to end on a local Temporal dev server: a poison signal no longer wedges its workflow. + +Needs the Temporal CLI (``temporal``) on PATH and is skipped without it; CI has none, and this never +downloads a server. ``test_signal_errors_replay.py`` covers the same behaviour hermetically. +""" + +from __future__ import annotations + +import gc +import uuid +import shutil +import asyncio +import logging +from typing import Any +from datetime import timedelta +from collections.abc import AsyncIterator + +import pytest +from temporalio import workflow +from temporalio.client import Client, WorkflowHandle, WorkflowFailureError, WorkflowExecutionStatus +from temporalio.worker import Worker, UnsandboxedWorkflowRunner +from temporalio.testing import WorkflowEnvironment +from temporalio.exceptions import TemporalError, ApplicationError +from temporalio.api.enums.v1 import EventType + +from agentex.lib.core.temporal.workers import signal_errors +from agentex.lib.core.temporal.workers.signal_errors import SignalHandlerErrorInterceptor + +TEMPORAL_CLI = shutil.which("temporal") + +pytestmark = pytest.mark.skipif(TEMPORAL_CLI is None, reason="needs the Temporal CLI (`temporal`) on PATH") + +SENTINEL = "user-content-8642" +POISON = {"content": {"type": "data", "data": {"note": SENTINEL}}} +VALID = {"content": " hello "} +TASK_FAILED = EventType.EVENT_TYPE_WORKFLOW_TASK_FAILED + + +@workflow.defn +class EventWorkflow: + """Completes with the first event's text. Like the tutorials' handlers, it assumes text content.""" + + def __init__(self) -> None: + self._texts: list[str] = [] + + @workflow.run + async def run(self) -> list[str]: + await workflow.wait_condition(lambda: bool(self._texts)) + return self._texts + + @workflow.signal + def receive_event(self, event: dict[str, Any]) -> None: + self._texts.append(event["content"].strip()) + + @workflow.query + def texts(self) -> list[str]: + return list(self._texts) + + +class DeclaredTemporalError(TemporalError): + """Like the OpenAI Agents plugin's AgentsWorkflowError: a TemporalError declared a failure type.""" + + +class _TaskGroupChecks: + """Checks each event in an ``asyncio.TaskGroup`` whose child rejects non-text content on purpose.""" + + rejection: type[Exception] + + def __init__(self) -> None: + self._texts: list[str] = [] + + @workflow.signal + async def receive_event(self, event: dict[str, Any]) -> None: + async with asyncio.TaskGroup() as group: + group.create_task(self._require_text(event)) + self._texts.append(event["content"].strip()) + + async def _require_text(self, event: dict[str, Any]) -> None: + if not isinstance(event["content"], str): + raise self.rejection("event content is not text") + + async def _first_texts(self) -> list[str]: + await workflow.wait_condition(lambda: bool(self._texts)) + return self._texts + + +@workflow.defn +class TaskGroupWorkflow(_TaskGroupChecks): + rejection = ApplicationError + + @workflow.run + async def run(self) -> list[str]: + return await self._first_texts() + + +@workflow.defn(failure_exception_types=[DeclaredTemporalError]) +class DeclaredErrorTaskGroupWorkflow(_TaskGroupChecks): + rejection = DeclaredTemporalError + + @workflow.run + async def run(self) -> list[str]: + return await self._first_texts() + + +class DeclaredError(Exception): + pass + + +@workflow.defn(failure_exception_types=[DeclaredError]) +class DeclaredFailureWorkflow: + @workflow.run + async def run(self) -> None: + await workflow.wait_condition(lambda: False) + + @workflow.signal + def receive_event(self, event: dict[str, Any]) -> None: + raise DeclaredError("declared to fail the workflow") + + +@pytest.fixture(scope="module") +async def client() -> AsyncIterator[Client]: + assert TEMPORAL_CLI is not None + env = await WorkflowEnvironment.start_local( + dev_server_existing_path=TEMPORAL_CLI, dev_server_startup_timeout=timedelta(seconds=30) + ) + try: + yield env.client + finally: + await env.shutdown() + + +def _worker(client: Client, workflow_class: type, *, with_interceptor: bool) -> Worker: + return Worker( + client, + task_queue=f"signal-errors-e2e-{uuid.uuid4()}", + workflows=[workflow_class], + workflow_runner=UnsandboxedWorkflowRunner(), + interceptors=[SignalHandlerErrorInterceptor()] if with_interceptor else [], + ) + + +async def _event_types(handle: WorkflowHandle[Any, Any]) -> list[int]: + return [event.event_type async for event in handle.fetch_history_events()] + + +async def _wait_for_event(handle: WorkflowHandle[Any, Any], event_type: int) -> None: + async def poll() -> None: + while event_type not in await _event_types(handle): + await asyncio.sleep(0.1) + + await asyncio.wait_for(poll(), timeout=10) + + +async def test_a_poison_signal_is_dropped_and_the_next_signal_is_processed( + client: Client, caplog: pytest.LogCaptureFixture +) -> None: + caplog.set_level(logging.DEBUG, logger=signal_errors.logger.name) + async with _worker(client, EventWorkflow, with_interceptor=True) as worker: + handle = await client.start_workflow( + EventWorkflow.run, id=f"signal-errors-e2e-{uuid.uuid4()}", task_queue=worker.task_queue + ) + await handle.signal(EventWorkflow.receive_event, POISON) + await handle.signal(EventWorkflow.receive_event, VALID) + + assert await asyncio.wait_for(handle.result(), timeout=10) == ["hello"] + assert await handle.query(EventWorkflow.texts) == ["hello"] + + assert TASK_FAILED not in await _event_types(handle) + (record,) = [record for record in caplog.records if record.name == signal_errors.logger.name] + assert record.__dict__["workflow_id"] == handle.id + assert record.exc_info is not None and isinstance(record.exc_info[1], AttributeError) + assert SENTINEL not in caplog.text + + +@pytest.mark.parametrize("workflow_class", [TaskGroupWorkflow, DeclaredErrorTaskGroupWorkflow]) +async def test_a_task_group_rejecting_the_signal_is_dropped_rather_than_wedging_the_workflow( + client: Client, + caplog: pytest.LogCaptureFixture, + workflow_class: type[TaskGroupWorkflow | DeclaredErrorTaskGroupWorkflow], +) -> None: + # Temporal fails the task, not the workflow, for an exception group, even one holding only a failure + # exception: an ApplicationError, or a TemporalError the workflow declares a failure type. + caplog.set_level(logging.DEBUG, logger=signal_errors.logger.name) + async with _worker(client, workflow_class, with_interceptor=True) as worker: + handle = await client.start_workflow( + workflow_class.run, id=f"signal-errors-e2e-{uuid.uuid4()}", task_queue=worker.task_queue + ) + await handle.signal("receive_event", POISON) + await handle.signal("receive_event", VALID) + + assert await asyncio.wait_for(handle.result(), timeout=10) == ["hello"] + + assert TASK_FAILED not in await _event_types(handle) + (record,) = [record for record in caplog.records if record.name == signal_errors.logger.name] + assert record.exc_info is not None and isinstance(record.exc_info[1], ExceptionGroup) + assert type(record.exc_info[1].exceptions[0]) is workflow_class.rejection + + +# Each retry of the failing task hands the valid signal to an activation that aborts before running it; newer +# temporalio versions also leave the workflow's run coroutine unstarted. +@pytest.mark.filterwarnings("ignore:coroutine .*(run_signal|run_workflow).* was never awaited:RuntimeWarning") +async def test_without_the_interceptor_the_poison_signal_wedges_the_workflow( + client: Client, monkeypatch: pytest.MonkeyPatch +) -> None: + # The failed activations' log records hold tracebacks that would keep those coroutines alive in pytest's log + # capture until after the test, where the filter above no longer applies. + monkeypatch.setattr(logging.getLogger("temporalio.worker._workflow_instance"), "disabled", True) + async with _worker(client, EventWorkflow, with_interceptor=False) as worker: + handle = await client.start_workflow( + EventWorkflow.run, id=f"signal-errors-e2e-{uuid.uuid4()}", task_queue=worker.task_queue + ) + await handle.signal(EventWorkflow.receive_event, POISON) + await _wait_for_event(handle, TASK_FAILED) + await handle.signal(EventWorkflow.receive_event, VALID) + + with pytest.raises(TimeoutError): + await asyncio.wait_for(handle.result(), timeout=3) + assert (await handle.describe()).status == WorkflowExecutionStatus.RUNNING + await handle.terminate("test cleanup") + gc.collect() + + +async def test_a_declared_failure_exception_type_still_fails_the_workflow(client: Client) -> None: + async with _worker(client, DeclaredFailureWorkflow, with_interceptor=True) as worker: + handle = await client.start_workflow( + DeclaredFailureWorkflow.run, id=f"signal-errors-e2e-{uuid.uuid4()}", task_queue=worker.task_queue + ) + await handle.signal(DeclaredFailureWorkflow.receive_event, POISON) + + with pytest.raises(WorkflowFailureError) as raised: + await asyncio.wait_for(handle.result(), timeout=10) + + assert isinstance(raised.value.cause, ApplicationError) + assert raised.value.cause.type == "DeclaredError" + assert TASK_FAILED not in await _event_types(handle) diff --git a/tests/lib/core/temporal/workers/test_signal_errors_replay.py b/tests/lib/core/temporal/workers/test_signal_errors_replay.py new file mode 100644 index 000000000..59fb00a40 --- /dev/null +++ b/tests/lib/core/temporal/workers/test_signal_errors_replay.py @@ -0,0 +1,307 @@ +"""SignalHandlerErrorInterceptor in Temporal's real workflow runtime, replayed from hand-built histories. + +``Replayer`` drives the real worker machinery (Core and the Python workflow instance) in-process, so no +Temporal server is needed. Each history records what a worker with the interceptor does, and replay fails +whenever the replaying worker would act differently, e.g. fail a workflow task the history completed. +""" + +from __future__ import annotations + +import gc +import json +import base64 +import asyncio +import logging +from typing import Any +from concurrent.futures import ThreadPoolExecutor + +import pytest +from temporalio import workflow +from temporalio.client import WorkflowHistory +from temporalio.worker import Replayer, UnsandboxedWorkflowRunner +from temporalio.exceptions import TemporalError, ApplicationError + +from agentex.lib.core.temporal.workers import signal_errors +from agentex.lib.core.temporal.workers.signal_errors import SignalHandlerErrorInterceptor + +TASK_QUEUE = "signal-errors-replay" +EVENT_TIME = "2026-11-12T00:00:00Z" + +POISON = {"content": {"type": "data", "data": {"note": "not text"}}} +VALID = {"content": " hello "} + + +class DeclaredError(Exception): + """Listed in the workflow's ``failure_exception_types``, so it is meant to fail the workflow.""" + + +@workflow.defn(name="SignalErrorsReplayWorkflow", failure_exception_types=[DeclaredError]) +class SignalErrorsReplayWorkflow: + def __init__(self) -> None: + self._texts: list[str] = [] + + @workflow.run + async def run(self) -> list[str]: + await workflow.wait_condition(lambda: bool(self._texts)) + return self._texts + + @workflow.signal(name="receive_event") + def receive_event(self, event: dict[str, Any]) -> None: + raise_as = event.get("raise") + if raise_as == "application": + raise ApplicationError("rejected on purpose", non_retryable=True) + if raise_as == "declared": + raise DeclaredError("declared to fail the workflow") + if raise_as == "nondeterminism": + raise workflow.NondeterminismError("broke determinism") + # Like the tutorials' receive_event handlers this assumes text, so POISON raises AttributeError. + self._texts.append(event["content"].strip()) + + +def _payload(value: Any) -> dict[str, Any]: + return { + "metadata": {"encoding": base64.b64encode(b"json/plain").decode()}, + "data": base64.b64encode(json.dumps(value).encode()).decode(), + } + + +def _history(*signal_tasks: list[dict[str, Any]], closed_by: str) -> WorkflowHistory: + """A run that starts, handles each list of signals in one workflow task, then completes or fails.""" + events: list[dict[str, Any]] = [ + { + "eventType": "EVENT_TYPE_WORKFLOW_EXECUTION_STARTED", + "eventTime": EVENT_TIME, + "workflowExecutionStartedEventAttributes": { + "workflowType": {"name": "SignalErrorsReplayWorkflow"}, + "taskQueue": {"name": TASK_QUEUE}, + "workflowTaskTimeout": "10s", + "originalExecutionRunId": "5d1f3c2e-8a4b-4c6d-9e0f-1a2b3c4d5e6f", + }, + } + ] + + def workflow_task() -> int: + scheduled = len(events) + 1 + events.extend( + [ + { + "eventType": "EVENT_TYPE_WORKFLOW_TASK_SCHEDULED", + "workflowTaskScheduledEventAttributes": { + "taskQueue": {"name": TASK_QUEUE}, + "startToCloseTimeout": "10s", + "attempt": 1, + }, + }, + { + "eventType": "EVENT_TYPE_WORKFLOW_TASK_STARTED", + "eventTime": EVENT_TIME, + "workflowTaskStartedEventAttributes": {"scheduledEventId": str(scheduled)}, + }, + { + "eventType": "EVENT_TYPE_WORKFLOW_TASK_COMPLETED", + "workflowTaskCompletedEventAttributes": { + "scheduledEventId": str(scheduled), + "startedEventId": str(scheduled + 1), + }, + }, + ] + ) + return scheduled + 2 + + completed_task = workflow_task() + for signals in signal_tasks: + events.extend( + { + "eventType": "EVENT_TYPE_WORKFLOW_EXECUTION_SIGNALED", + "workflowExecutionSignaledEventAttributes": { + "signalName": "receive_event", + "input": {"payloads": [_payload(signal)]}, + }, + } + for signal in signals + ) + completed_task = workflow_task() + + if closed_by == "completed": + events.append( + { + "eventType": "EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED", + "workflowExecutionCompletedEventAttributes": { + "result": {"payloads": [_payload(["hello"])]}, + "workflowTaskCompletedEventId": str(completed_task), + }, + } + ) + else: + events.append( + { + "eventType": "EVENT_TYPE_WORKFLOW_EXECUTION_FAILED", + "workflowExecutionFailedEventAttributes": { + "failure": {"message": "failed on purpose"}, + "workflowTaskCompletedEventId": str(completed_task), + }, + } + ) + for event_id, event in enumerate(events, start=1): + event["eventId"] = str(event_id) + return WorkflowHistory.from_json("signal-errors-replay", {"events": events}) + + +async def _replay(history: WorkflowHistory, *, with_interceptor: bool) -> Exception | None: + with ThreadPoolExecutor(max_workers=1) as executor: + replayer = Replayer( + workflows=[SignalErrorsReplayWorkflow], + workflow_runner=UnsandboxedWorkflowRunner(), + interceptors=[SignalHandlerErrorInterceptor()] if with_interceptor else [], + workflow_task_executor=executor, + ) + result = await replayer.replay_workflow(history, raise_on_replay_failure=False) + return result.replay_failure + + +POISON_THEN_VALID = [ + pytest.param(([POISON], [VALID]), id="separate-workflow-tasks"), + pytest.param(([POISON, VALID],), id="same-workflow-task"), +] + + +@pytest.mark.parametrize("signal_tasks", POISON_THEN_VALID) +async def test_a_poison_signal_is_dropped_and_the_next_signal_completes_the_workflow( + signal_tasks: tuple[list[dict[str, Any]], ...], caplog: pytest.LogCaptureFixture +) -> None: + caplog.set_level(logging.DEBUG, logger=signal_errors.logger.name) + + failure = await _replay(_history(*signal_tasks, closed_by="completed"), with_interceptor=True) + + assert failure is None + # Every replay re-runs the handler; the drop is logged when it happens, not again on each replay. + assert not [record for record in caplog.records if record.name == signal_errors.logger.name] + + +@pytest.mark.filterwarnings("ignore:coroutine .*run_signal.* was never awaited:RuntimeWarning") +@pytest.mark.parametrize("signal_tasks", POISON_THEN_VALID) +async def test_without_the_interceptor_the_poison_signal_fails_its_workflow_task( + signal_tasks: tuple[list[dict[str, Any]], ...], +) -> None: + failure = await _replay(_history(*signal_tasks, closed_by="completed"), with_interceptor=False) + + assert failure is not None + assert "'dict' object has no attribute 'strip'" in str(failure) + # When both signals share the task, the failed activation never runs the valid signal's handler at all and + # Python finalizes its coroutine unawaited. Collect it now, under the filter above, not in a later test. + gc.collect() + + +@pytest.mark.parametrize("raise_as", ["application", "declared"]) +async def test_a_deliberate_workflow_failure_still_fails_the_workflow(raise_as: str) -> None: + # The history closes with WorkflowExecutionFailed right after the signal's task: dropping the + # exception instead would leave the workflow running, which replay reports as nondeterminism. + history = _history([{"raise": raise_as}], closed_by="failed") + + assert await _replay(history, with_interceptor=True) is None + + +async def test_a_nondeterminism_error_still_fails_the_workflow_task() -> None: + # Were it dropped, the next signal would complete the workflow exactly as this history says. + history = _history([{"raise": "nondeterminism"}], [VALID], closed_by="completed") + + failure = await _replay(history, with_interceptor=True) + + assert failure is not None + assert "broke determinism" in str(failure) + + +class WorkerDeclaredError(TemporalError): + """Declared at worker level, as the OpenAI Agents plugin declares its ``AgentsWorkflowError``.""" + + +class DeclaredGroup(ExceptionGroup[Exception]): + """An exception group class the workflow declares a failure type.""" + + +class NondeterministicGroup(ExceptionGroup[Exception], workflow.NondeterminismError): + """An exception group class that is itself one of the SDK's own errors.""" + + +async def _raise(err: Exception) -> None: + raise err + + +@workflow.defn(name="SignalErrorsReplayWorkflow", failure_exception_types=[DeclaredGroup]) +class GroupReplayWorkflow: + """Raises exception groups from an async signal handler, as an ``asyncio.TaskGroup`` does.""" + + def __init__(self) -> None: + self._texts: list[str] = [] + + @workflow.run + async def run(self) -> list[str]: + await workflow.wait_condition(lambda: bool(self._texts)) + return self._texts + + @workflow.signal(name="receive_event") + async def receive_event(self, event: dict[str, Any]) -> None: + shape = event.get("raise") + if shape == "task-group-application": + async with asyncio.TaskGroup() as group: + group.create_task(_raise(ApplicationError("rejected on purpose", non_retryable=True))) + elif shape == "task-group-worker-declared": + async with asyncio.TaskGroup() as group: + group.create_task(_raise(WorkerDeclaredError("agent run failed"))) + elif shape == "task-group-nondeterminism": + async with asyncio.TaskGroup() as group: + group.create_task(_raise(workflow.NondeterminismError("broke determinism"))) + elif shape == "worker-declared": + raise WorkerDeclaredError("agent run failed") + elif shape == "nested-declared-group": + raise ExceptionGroup("outer", [DeclaredGroup("inner", [ValueError("bad")])]) + elif shape == "declared-group-holding-nondeterminism": + raise DeclaredGroup("group", [workflow.NondeterminismError("broke determinism")]) + elif shape == "application-in-nondeterministic-group": + raise ExceptionGroup("outer", [NondeterministicGroup("inner", [ApplicationError("rejected")])]) + else: + self._texts.append(event["content"].strip()) + + +async def _replay_groups(history: WorkflowHistory, *, with_interceptor: bool) -> Exception | None: + with ThreadPoolExecutor(max_workers=1) as executor: + replayer = Replayer( + workflows=[GroupReplayWorkflow], + workflow_runner=UnsandboxedWorkflowRunner(), + interceptors=[SignalHandlerErrorInterceptor()] if with_interceptor else [], + workflow_task_executor=executor, + workflow_failure_exception_types=[WorkerDeclaredError], + ) + result = await replayer.replay_workflow(history, raise_on_replay_failure=False) + # A failed activation leaves coroutines it never started; finalize them here, under the tests' warning filter. + gc.collect() + return result.replay_failure + + +UNSTARTED_COROUTINES = "ignore:coroutine .*(run_signal|run_workflow).* was never awaited:RuntimeWarning" + + +# Temporal checks only the outermost exception, so it fails the task for any group that is not itself a failure +# exception, whatever the group holds. +@pytest.mark.filterwarnings(UNSTARTED_COROUTINES) +@pytest.mark.parametrize("shape", ["task-group-application", "task-group-worker-declared", "nested-declared-group"]) +async def test_an_exception_group_of_failures_is_dropped_rather_than_wedging_the_workflow(shape: str) -> None: + history = _history([{"raise": shape}], [VALID], closed_by="completed") + + assert await _replay_groups(history, with_interceptor=True) is None + assert await _replay_groups(history, with_interceptor=False) is not None + + +@pytest.mark.parametrize("shape", ["worker-declared", "declared-group-holding-nondeterminism"]) +async def test_a_declared_failure_type_raised_from_the_handler_still_fails_the_workflow(shape: str) -> None: + history = _history([{"raise": shape}], closed_by="failed") + + assert await _replay_groups(history, with_interceptor=True) is None + + +@pytest.mark.filterwarnings(UNSTARTED_COROUTINES) +@pytest.mark.parametrize("shape", ["task-group-nondeterminism", "application-in-nondeterministic-group"]) +async def test_an_exception_group_holding_an_sdk_error_still_fails_the_workflow_task(shape: str) -> None: + history = _history([{"raise": shape}], [VALID], closed_by="completed") + + assert await _replay_groups(history, with_interceptor=True) is not None diff --git a/tests/lib/core/temporal/workers/test_worker_signal_errors.py b/tests/lib/core/temporal/workers/test_worker_signal_errors.py new file mode 100644 index 000000000..6c5755625 --- /dev/null +++ b/tests/lib/core/temporal/workers/test_worker_signal_errors.py @@ -0,0 +1,193 @@ +"""AgentexWorker installs SignalHandlerErrorInterceptor by default, ahead of the caller's interceptors. + +As in test_worker_tracing.py, the Client and Worker configuration stay real and only their network boundary +is replaced; the tests read the workflow inbound interceptor chain the Worker builds for every workflow. +""" + +from __future__ import annotations + +import inspect +from types import SimpleNamespace +from typing import Any, override +from unittest.mock import Mock, AsyncMock +from collections.abc import Callable, Awaitable + +import pytest +from temporalio import workflow +from temporalio.worker import ( + Worker, + Interceptor, + HandleSignalInput, + WorkflowInboundInterceptor, + WorkflowInterceptorClassInput, +) +from temporalio.exceptions import FailureError +from temporalio.bridge.client import Client as BridgeClient +from temporalio.bridge.worker import Worker as BridgeWorker +from temporalio.contrib.opentelemetry import TracingWorkflowInboundInterceptor + +from agentex.lib.core.temporal.workers.worker import AgentexWorker +from agentex.lib.core.temporal.workers.signal_errors import SignalHandlerErrorInterceptor + +TRACE_ENV = "AGENTEX_TEMPORAL_TRACE_INTERCEPTOR_ENABLED" +DROP_SIGNAL_ERRORS = SignalHandlerErrorInterceptor().workflow_interceptor_class( + WorkflowInterceptorClassInput(unsafe_extern_functions={}) +) + +Chain = list[type[WorkflowInboundInterceptor]] + + +@workflow.defn +class _Workflow: + @workflow.run + async def run(self) -> None: + pass + + +class _CallerInterceptor(Interceptor): + """A caller's interceptor that records the outcome of each signal it wraps.""" + + def __init__(self, name: str, seen: list[tuple[str, BaseException | None]]) -> None: + self.name = name + + class Inbound(WorkflowInboundInterceptor): + @override + async def handle_signal(self, input: HandleSignalInput) -> None: + try: + await self.next.handle_signal(input) + except Exception as err: + seen.append((name, err)) + raise + seen.append((name, None)) + + self.inbound = Inbound + + @override + def workflow_interceptor_class(self, input: WorkflowInterceptorClassInput) -> type[WorkflowInboundInterceptor]: + return self.inbound + + +def _names(chain: Chain, *callers: _CallerInterceptor) -> list[str]: + by_class: dict[type[WorkflowInboundInterceptor], str] = {caller.inbound: caller.name for caller in callers} + by_class[DROP_SIGNAL_ERRORS] = "drop-signal-errors" + by_class[TracingWorkflowInboundInterceptor] = "tracing" + return [by_class.get(interceptor_class, interceptor_class.__qualname__) for interceptor_class in chain] + + +@pytest.fixture +def build_chain(monkeypatch: pytest.MonkeyPatch) -> Callable[[AgentexWorker], Awaitable[Chain]]: + monkeypatch.delenv("DD_AGENT_HOST", raising=False) + # Keep Client and Worker configuration real; replace their network boundary. + monkeypatch.setattr(BridgeClient, "connect", AsyncMock(return_value=Mock())) + monkeypatch.setattr(BridgeWorker, "create", Mock(return_value=Mock())) + built: list[Worker] = [] + + async def capture(worker: Worker) -> None: + built.append(worker) + + monkeypatch.setattr(Worker, "run", capture) + + async def run(agentex_worker: AgentexWorker) -> Chain: + monkeypatch.setattr(agentex_worker, "start_health_check_server", AsyncMock()) + monkeypatch.setattr(agentex_worker, "_register_agent", AsyncMock()) + await agentex_worker.run(activities=[], workflows=[_Workflow]) + worker = built.pop() + assert worker._workflow_worker is not None + return list(worker._workflow_worker._interceptor_classes) + + return run + + +@pytest.mark.parametrize("tracing_enabled", [True, False]) +async def test_installed_by_default_ahead_of_the_callers_interceptors( + monkeypatch: pytest.MonkeyPatch, build_chain, tracing_enabled: bool +) -> None: + monkeypatch.setenv(TRACE_ENV, str(tracing_enabled).lower()) + seen: list[tuple[str, BaseException | None]] = [] + first, second = _CallerInterceptor("first", seen), _CallerInterceptor("second", seen) + callers = [first, second] + agentex_worker = AgentexWorker(task_queue="test-signal-errors", health_check_port=8080, interceptors=callers) + + chain = await build_chain(agentex_worker) + + # Temporal prepends the client's interceptors (tracing); the worker's own follow in the order given. + assert _names(chain, first, second) == [ + *(["tracing"] if tracing_enabled else []), + "drop-signal-errors", + "first", + "second", + ] + assert callers == [first, second] + assert agentex_worker.interceptors is callers + + +async def test_opting_out_passes_the_callers_interceptors_unchanged( + monkeypatch: pytest.MonkeyPatch, build_chain +) -> None: + monkeypatch.setenv(TRACE_ENV, "false") + seen: list[tuple[str, BaseException | None]] = [] + first, second = _CallerInterceptor("first", seen), _CallerInterceptor("second", seen) + agentex_worker = AgentexWorker( + task_queue="test-signal-errors", + health_check_port=8080, + interceptors=[first, second], + drop_signals_on_handler_error=False, + ) + + assert _names(await build_chain(agentex_worker), first, second) == ["first", "second"] + + +async def test_a_caller_placed_interceptor_is_not_added_twice(monkeypatch: pytest.MonkeyPatch, build_chain) -> None: + monkeypatch.setenv(TRACE_ENV, "false") + first = _CallerInterceptor("first", []) + agentex_worker = AgentexWorker( + task_queue="test-signal-errors", health_check_port=8080, interceptors=[first, SignalHandlerErrorInterceptor()] + ) + + assert _names(await build_chain(agentex_worker), first) == ["first", "drop-signal-errors"] + + +async def test_the_default_interceptors_list_is_not_mutated(monkeypatch: pytest.MonkeyPatch, build_chain) -> None: + monkeypatch.setenv(TRACE_ENV, "false") + default = inspect.signature(AgentexWorker.__init__).parameters["interceptors"].default + + for _ in range(2): + chain = await build_chain(AgentexWorker(task_queue="test-signal-errors", health_check_port=8080)) + assert _names(chain) == ["drop-signal-errors"] + + assert default == [] + + +async def test_the_callers_interceptors_see_the_exception_before_the_signal_is_dropped( + monkeypatch: pytest.MonkeyPatch, build_chain +) -> None: + monkeypatch.setenv(TRACE_ENV, "false") + seen: list[tuple[str, BaseException | None]] = [] + first, second = _CallerInterceptor("first", seen), _CallerInterceptor("second", seen) + chain = await build_chain( + AgentexWorker(task_queue="test-signal-errors", health_check_port=8080, interceptors=[first, second]) + ) + monkeypatch.setattr(workflow, "in_workflow", lambda: True) + monkeypatch.setattr( + workflow, "info", lambda: SimpleNamespace(workflow_id="task-1", run_id="run-1", workflow_type="W") + ) + monkeypatch.setattr(workflow.unsafe, "is_replaying_history_events", lambda: False) + monkeypatch.setattr(workflow, "is_failure_exception", lambda err: isinstance(err, FailureError)) + error = AttributeError("'DataContent' object has no attribute 'content'") + + class Handler(WorkflowInboundInterceptor): + def __init__(self) -> None: + pass + + @override + async def handle_signal(self, input: HandleSignalInput) -> None: + raise error + + # Assemble the chain the way the workflow instance does: the first class listed is the outermost. + inbound: WorkflowInboundInterceptor = Handler() + for interceptor_class in reversed(chain): + inbound = interceptor_class(inbound) + outcome: Any = await inbound.handle_signal(HandleSignalInput(signal="receive_event", args=[{}], headers={})) + + assert outcome is None + assert seen == [("second", error), ("first", error)]