A programming framework for agentic AI
Add example for termination using an intervention handler (#109)
Jack Gerritsbb202058ef83
diff --git a/python/docs/src/guides/termination-with-intervention.md b/python/docs/src/guides/termination-with-intervention.mdnew file mode 100644index 000000000..26890d517--- /dev/null+++ b/python/docs/src/guides/termination-with-intervention.md@@ -0,0 +1,87 @@+# Termination using Intervention Handler++```{note}+This method is only really valid for single-tenant applications. If multiple parallel users are using the application via namespaces this approach will not work without modification.+```++There are many different ways to handle termination in `agnext`. Ultimately, the goal is to detect that the runtime no longer needs to be executed and you can proceed to finalization tasks. One way to do this is to use an `InterventionHandler` to detect a termination message and then act on it.++```python+import asyncio+from dataclasses import dataclass+from typing import Any, Generic, Type, TypeVar++from agnext.application import SingleThreadedAgentRuntime+from agnext.components import TypeRoutedAgent, message_handler+from agnext.core import AgentId, CancellationToken+from agnext.core.intervention import DefaultInterventionHandler+```++First, we define a dataclass that will be used to signal termination.++```python+@dataclass+class Termination:+ reason: str+```++We code our agent to publish a termination message when it decides it is time to terminate.++```python+class AnAgent(TypeRoutedAgent):+ def __init__(self) -> None:+ super().__init__("MyAgent")+ self.received = 0++ @message_handler+ async def on_new_message(self, message: str, cancellation_token: CancellationToken) -> None:+ self.received += 1+ if self.received > 3:+ self.publish_message(Termination(reason="Reached maximum number of messages"))+```++Next, we create an InterventionHandler that will detect the termination message and act on it. This one hooks into publishes and when it encounters `Termination` it alters its internal state to indicate that termination has been requested.+```python++T = TypeVar("T")++class TerminationHandler(Generic[T], DefaultInterventionHandler):++ def __init__(self, termination_type: Type[T]):+ self.termination_type = termination_type+ self.termination_value: T | None = None++ async def on_publish(self, message: Any, *, sender: AgentId | None) -> Any:+ if isinstance(message, Termination):+ self.termination_value = self.termination_type(message.reason)+ return message++ @property+ def termination_value(self) -> T | None:+ return self.termination_value++ @property+ def has_terminated(self) -> bool:+ return self.termination_value is not None+```++Finally, we add this handler to the runtime and use it to detect termination and cease running the `process_next` loop once it has encountered termination.++```python+async def main() -> None:+ termination_handler = TerminationHandler(Termination)+ runtime = SingleThreadedAgentRuntime(+ before_send=termination_handler+ )++ # Add Agents and kick off task++ while not termination_handler.has_terminated:+ await runtime.process_next()++ print(termination_handler.termination_value)+++if __name__ == "__main__":+ asyncio.run(main())+```\ No newline at end of filediff --git a/python/docs/src/index.rst b/python/docs/src/index.rstindex 16922a9a6..cc88ef4bf 100644--- a/python/docs/src/index.rst+++ b/python/docs/src/index.rst@@ -47,6 +47,7 @@ AGNext's developer API consists of the following layers:guides/type-routed-agentguides/group-chat-coder-reviewerguides/azure-openai-with-aad-auth+ guides/termination-with-intervention.. toctree::