Skip to content

A programming framework for agentic AI

Implement closure agent (#143)

Jack Gerrits13b0d0deb4ae
diff --git a/python/docs/src/guides/extracting-results-with-an-agent.md b/python/docs/src/guides/extracting-results-with-an-agent.md
new file mode 100644
index 000000000..efd7e7eb9
--- /dev/null
+++ b/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.
diff --git a/python/docs/src/index.rst b/python/docs/src/index.rst
index 87ea28ca9..c2ebbcbde 100644
--- a/python/docs/src/index.rst
+++ b/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::
diff --git a/python/src/agnext/components/__init__.py b/python/src/agnext/components/__init__.py
index e1bdf5cd7..7125cbbe9 100644
--- a/python/src/agnext/components/__init__.py
+++ b/python/src/agnext/components/__init__.py
@@ -2,8 +2,9 @@
The :mod:`agnext.components` module provides building blocks for creating single agents
"""
+from ._closure_agent import ClosureAgent
from ._image import Image
from ._type_routed_agent import TypeRoutedAgent, message_handler
from ._types import FunctionCall
-__all__ = ["Image", "TypeRoutedAgent", "message_handler", "FunctionCall"]
+__all__ = ["Image", "TypeRoutedAgent", "ClosureAgent", "message_handler", "FunctionCall"]
diff --git a/python/src/agnext/components/_closure_agent.py b/python/src/agnext/components/_closure_agent.py
new file mode 100644
index 000000000..ca9f0d6de
--- /dev/null
+++ b/python/src/agnext/components/_closure_agent.py
@@ -0,0 +1,93 @@
+import inspect
+from typing import Any, Awaitable, Callable, Mapping, Sequence, TypeVar, get_type_hints
+
+from ..core._agent import Agent
+from ..core._agent_id import AgentId
+from ..core._agent_metadata import AgentMetadata
+from ..core._agent_runtime import AgentRuntime, agent_instantiation_context
+from ..core._cancellation_token import CancellationToken
+from ..core.exceptions import CantHandleException
+from ._type_helpers import get_types
+
+T = TypeVar("T")
+
+
+def get_subscriptions_from_closure(
+ closure: Callable[[AgentRuntime, AgentId, T, CancellationToken], Awaitable[Any]],
+) -> Sequence[type]:
+ args = inspect.getfullargspec(closure)[0]
+ if len(args) != 4:
+ raise AssertionError("Closure must have 4 arguments")
+
+ message_arg_name = args[2]
+
+ type_hints = get_type_hints(closure)
+
+ if "return" not in type_hints:
+ raise AssertionError("return not found in function signature")
+
+ # Get the type of the message parameter
+ target_types = get_types(type_hints[message_arg_name])
+ if target_types is None:
+ raise AssertionError("Message type not found")
+
+ # print(type_hints)
+ return_types = get_types(type_hints["return"])
+
+ if return_types is None:
+ raise AssertionError("Return type not found")
+
+ return target_types
+
+
+class ClosureAgent(Agent):
+ def __init__(
+ self, description: str, closure: Callable[[AgentRuntime, AgentId, T, CancellationToken], Awaitable[Any]]
+ ) -> None:
+ try:
+ runtime, id = agent_instantiation_context.get()
+ except LookupError as e:
+ raise RuntimeError(
+ "ClosureAgent must be instantiated within the context of an AgentRuntime. It cannot be directly instantiated."
+ ) from e
+
+ self._runtime: AgentRuntime = runtime
+ self._id: AgentId = id
+ self._description = description
+ self._subscriptions = get_subscriptions_from_closure(closure)
+ self._closure = closure
+
+ @property
+ def metadata(self) -> AgentMetadata:
+ assert self._id is not None
+ return AgentMetadata(
+ namespace=self._id.namespace,
+ name=self._id.name,
+ description=self._description,
+ subscriptions=self._subscriptions,
+ )
+
+ @property
+ def name(self) -> str:
+ return self.id.name
+
+ @property
+ def id(self) -> AgentId:
+ return self._id
+
+ @property
+ def runtime(self) -> AgentRuntime:
+ return self._runtime
+
+ async def on_message(self, message: Any, cancellation_token: CancellationToken) -> Any:
+ if type(message) not in self._subscriptions:
+ raise CantHandleException(
+ f"Message type {type(message)} not in target types {self._subscriptions} of {self.id}"
+ )
+ return await self._closure(self._runtime, self._id, message, cancellation_token)
+
+ def save_state(self) -> Mapping[str, Any]:
+ raise ValueError("save_state not implemented for ClosureAgent")
+
+ def load_state(self, state: Mapping[str, Any]) -> None:
+ raise ValueError("load_state not implemented for ClosureAgent")
diff --git a/python/src/agnext/components/_type_helpers.py b/python/src/agnext/components/_type_helpers.py
new file mode 100644
index 000000000..66e52e4b6
--- /dev/null
+++ b/python/src/agnext/components/_type_helpers.py
@@ -0,0 +1,33 @@
+from collections.abc import Sequence
+from types import NoneType, UnionType
+from typing import Any, Optional, Type, Union, get_args, get_origin
+
+
+def is_union(t: object) -> bool:
+ origin = get_origin(t)
+ return origin is Union or origin is UnionType
+
+
+def is_optional(t: object) -> bool:
+ origin = get_origin(t)
+ return origin is Optional
+
+
+# Special type to avoid the 3.10 vs 3.11+ difference of typing._SpecialForm vs typing.Any
+class AnyType:
+ pass
+
+
+def get_types(t: object) -> Sequence[Type[Any]] | None:
+ if is_union(t):
+ return get_args(t)
+ elif is_optional(t):
+ return tuple(list(get_args(t)) + [NoneType])
+ elif t is Any:
+ return (AnyType,)
+ elif isinstance(t, type):
+ return (t,)
+ elif isinstance(t, NoneType):
+ return (NoneType,)
+ else:
+ return None
diff --git a/python/src/agnext/components/_type_routed_agent.py b/python/src/agnext/components/_type_routed_agent.py
index b5c48fa89..8aac424c4 100644
--- a/python/src/agnext/components/_type_routed_agent.py
+++ b/python/src/agnext/components/_type_routed_agent.py
@@ -1,6 +1,5 @@
import logging
from functools import wraps
-from types import NoneType, UnionType
from typing import (
Any,
Callable,
@@ -8,15 +7,11 @@ from typing import (
Dict,
Literal,
NoReturn,
- Optional,
Protocol,
Sequence,
Type,
TypeVar,
- Union,
cast,
- get_args,
- get_origin,
get_type_hints,
overload,
runtime_checkable,
@@ -24,6 +19,7 @@ from typing import (
from ..core import BaseAgent, CancellationToken
from ..core.exceptions import CantHandleException
+from ._type_helpers import AnyType, get_types
logger = logging.getLogger("agnext")
@@ -34,36 +30,6 @@ ProducesT = TypeVar("ProducesT", covariant=True)
# Can't do because python doesnt support it
-def is_union(t: object) -> bool:
- origin = get_origin(t)
- return origin is Union or origin is UnionType
-
-
-def is_optional(t: object) -> bool:
- origin = get_origin(t)
- return origin is Optional
-
-
-# Special type to avoid the 3.10 vs 3.11+ difference of typing._SpecialForm vs typing.Any
-class AnyType:
- pass
-
-
-def get_types(t: object) -> Sequence[Type[Any]] | None:
- if is_union(t):
- return get_args(t)
- elif is_optional(t):
- return tuple(list(get_args(t)) + [NoneType])
- elif t is Any:
- return (AnyType,)
- elif isinstance(t, type):
- return (t,)
- elif isinstance(t, NoneType):
- return (NoneType,)
- else:
- return None
-
-
@runtime_checkable
class MessageHandler(Protocol[ReceivesT, ProducesT]):
target_types: Sequence[type]
diff --git a/python/teams/team-one/src/team_one/agents/coder.py b/python/teams/team-one/src/team_one/agents/coder.py
index 010b87c03..a9d846b23 100644
--- a/python/teams/team-one/src/team_one/agents/coder.py
+++ b/python/teams/team-one/src/team_one/agents/coder.py
@@ -16,7 +16,7 @@ from agnext.components.models import (
from agnext.components.tools import PythonCodeExecutionTool
from agnext.core import CancellationToken
-from ..messages import TaskMessage, LLMResponseMessage, ToolMessage, ToolResultMessage
+from ..messages import LLMResponseMessage, TaskMessage, ToolMessage, ToolResultMessage
class Coder(TypeRoutedAgent):
diff --git a/python/teams/team-one/src/team_one/agents/file_surfer.py b/python/teams/team-one/src/team_one/agents/file_surfer.py
index 9bcec897b..331747a16 100644
--- a/python/teams/team-one/src/team_one/agents/file_surfer.py
+++ b/python/teams/team-one/src/team_one/agents/file_surfer.py
@@ -17,7 +17,7 @@ from agnext.components.models import (
from agnext.components.tools import FunctionTool
from agnext.core import CancellationToken
-from ..messages import TaskMessage, LLMResponseMessage, ToolMessage, ToolResultMessage
+from ..messages import LLMResponseMessage, TaskMessage, ToolMessage, ToolResultMessage
async def read_local_file(file_path: str) -> str:
diff --git a/python/teams/team-one/src/team_one/agents/orchestrator.py b/python/teams/team-one/src/team_one/agents/orchestrator.py
index af6402715..654ea6118 100644
--- a/python/teams/team-one/src/team_one/agents/orchestrator.py
+++ b/python/teams/team-one/src/team_one/agents/orchestrator.py
@@ -1,7 +1,7 @@
from typing import List
from agnext.components import TypeRoutedAgent, message_handler
-from agnext.core import CancellationToken, AgentProxy
+from agnext.core import AgentProxy, CancellationToken
from ..messages import BroadcastMessage, RequestReplyMessage
diff --git a/python/teams/team-one/src/team_one/messages.py b/python/teams/team-one/src/team_one/messages.py
index 423c020f0..4f82f9cb1 100644
--- a/python/teams/team-one/src/team_one/messages.py
+++ b/python/teams/team-one/src/team_one/messages.py
@@ -1,6 +1,7 @@
from dataclasses import dataclass
-from agnext.components.models import FunctionExecutionResult
+
from agnext.components import FunctionCall
+from agnext.components.models import FunctionExecutionResult
@dataclass
diff --git a/python/tests/test_closure_agent.py b/python/tests/test_closure_agent.py
new file mode 100644
index 000000000..c9180694b
--- /dev/null
+++ b/python/tests/test_closure_agent.py
@@ -0,0 +1,42 @@
+
+
+from dataclasses import dataclass
+
+import pytest
+from agnext.application import SingleThreadedAgentRuntime
+
+from agnext.core import AgentRuntime, AgentId, CancellationToken
+
+from agnext.components import ClosureAgent
+
+
+import asyncio
+
+@dataclass
+class Message:
+ content: str
+
+
+
+async def test_register_receives_publish() -> None:
+ runtime = SingleThreadedAgentRuntime()
+
+ queue = asyncio.Queue[tuple[str, str]]()
+
+ async def log_message(_runtime: AgentRuntime, id: AgentId, message: Message, cancellation_token: CancellationToken) -> None:
+ namespace = id.namespace
+ await queue.put((namespace, message.content))
+
+ runtime.register("name", lambda: ClosureAgent("My agent", log_message))
+ await runtime.publish_message(Message("first message"), namespace="default")
+ await runtime.publish_message(Message("second message"), namespace="default")
+ await runtime.publish_message(Message("third message"), namespace="default")
+
+ await runtime.process_until_idle()
+
+ assert queue.qsize() == 3
+ assert queue.get_nowait() == ("default", "first message")
+ assert queue.get_nowait() == ("default", "second message")
+ assert queue.get_nowait() == ("default", "third message")
+ assert queue.empty()
diff --git a/python/tests/test_types.py b/python/tests/test_types.py
index 0cbbcd6ad..4a883ee2c 100644
--- a/python/tests/test_types.py
+++ b/python/tests/test_types.py
@@ -1,7 +1,8 @@
from types import NoneType
from typing import Any, Optional, Union
-from agnext.components._type_routed_agent import AnyType, get_types, message_handler
+from agnext.components._type_routed_agent import message_handler
+from agnext.components._type_helpers import AnyType, get_types
from agnext.core import CancellationToken