Implement closure agent (#143)

python/docs/src/guides/extracting-results-with-an-agent.md

@@ -0,0 +1,35 @@
+# Extracting Results with an Agent
+
+When running a multi-agent system to solve some task, you may want to extract the result of the system once it has reached termination. This guide showcases one way to achieve this. Given that agent instances are not directly accessible from the outside, we will use an agent to publish the final result to an accessible location.
+
+If you model your system to publish some `FinalResult` type then you can create an agent whose sole job is to subscribe to this and make it available externally. For simple agents like this the {py:class}`~agnext.components.ClosureAgent` is an option to reduce the amount of boilerplate code. This allows you to define a function that will be associated as the agent's message handler. In this example, we're going to use a queue shared between the agent and the external code to pass the result.
+
+```{note}
+When considering how to extract results from a multi-agent system, you must always consider the namespace of the agent and by extension the message.
+```
+
+```python
+from agnext.application import SingleThreadedAgentRuntime
+from agnext.core import AgentRuntime, AgentId, CancellationToken
+from agnext.components import ClosureAgent
+
+import asyncio
+
+@dataclass
+class FinalResult:
+    result: str
+
+# ...
+
+queue = asyncio.Queue[tuple[str, FinalResult]]()
+
+async def output_result(_runtime: AgentRuntime, id: AgentId, message: FinalResult, cancellation_token: CancellationToken) -> None:
+    namespace = id.namespace
+    await queue.put((namespace, FinalResult))
+
+runtime.register("OutputResult", lambda: ClosureAgent("Outputs messages", output_result))
+
+# ...
+```
+
+When using a `ClosureAgent` the third parameter, named `message` in this example determines what messages are subscribed to. In this case, the agent will only receive messages of type `FinalResult`. This can also be a union of types if you want to subscribe to multiple types of messages.

python/docs/src/index.rst

@@ -3,9 +3,9 @@ AGNext
 
 AGNext is a framework for building multi-agent applications.
 
-At a high level, it provides a framework for inter-agent communication and a 
-suite of independent components for building and managing agents. It models agents as 
-independent actors communicating via messages. You can implement agents in 
+At a high level, it provides a framework for inter-agent communication and a
+suite of independent components for building and managing agents. It models agents as
+independent actors communicating via messages. You can implement agents in
 different languages and run them on different machines across organizational boundaries.
 You can also implement agents using other agent frameworks and run them in AGNext.
 
@@ -20,7 +20,7 @@ AGNext's developer API consists of the following layers:
 - :doc:`application <reference/agnext.application>` - Implementations of the runtime and other modules (e.g., logging) for building applications.
 - :doc:`components <reference/agnext.components>` - Independent agent-building components: agents, models, memory, and tools.
 
-To get you started quickly, we also offers 
+To get you started quickly, we also offers
 `a suite of examples <https://github.com/microsoft/agnext/tree/main/python/examples>`_
 that demonstrate how to use AGNext.
 
@@ -51,6 +51,7 @@ that demonstrate how to use AGNext.
     guides/type-routed-agent
     guides/azure-openai-with-aad-auth
     guides/termination-with-intervention
+    guides/extracting-results-with-an-agent
 
 
 .. toctree::