Skip to content

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.md
new file mode 100644
index 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 file
diff --git a/python/docs/src/index.rst b/python/docs/src/index.rst
index 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-agent
guides/group-chat-coder-reviewer
guides/azure-openai-with-aad-auth
+ guides/termination-with-intervention
.. toctree::