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.mdnew file mode 100644index 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.rstindex 87ea28ca9..c2ebbcbde 100644--- a/python/docs/src/index.rst+++ b/python/docs/src/index.rst@@ -3,9 +3,9 @@ AGNextAGNext 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 indifferent 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-agentguides/azure-openai-with-aad-authguides/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__.pyindex 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 ClosureAgentfrom ._image import Imagefrom ._type_routed_agent import TypeRoutedAgent, message_handlerfrom ._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.pynew file mode 100644index 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.pynew file mode 100644index 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 Nonediff --git a/python/src/agnext/components/_type_routed_agent.py b/python/src/agnext/components/_type_routed_agent.pyindex 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 loggingfrom functools import wraps-from types import NoneType, UnionTypefrom 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, CancellationTokenfrom ..core.exceptions import CantHandleException+from ._type_helpers import AnyType, get_typeslogger = 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_checkableclass 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.pyindex 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 PythonCodeExecutionToolfrom agnext.core import CancellationToken-from ..messages import TaskMessage, LLMResponseMessage, ToolMessage, ToolResultMessage+from ..messages import LLMResponseMessage, TaskMessage, ToolMessage, ToolResultMessageclass 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.pyindex 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 FunctionToolfrom agnext.core import CancellationToken-from ..messages import TaskMessage, LLMResponseMessage, ToolMessage, ToolResultMessage+from ..messages import LLMResponseMessage, TaskMessage, ToolMessage, ToolResultMessageasync 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.pyindex 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 Listfrom agnext.components import TypeRoutedAgent, message_handler-from agnext.core import CancellationToken, AgentProxy+from agnext.core import AgentProxy, CancellationTokenfrom ..messages import BroadcastMessage, RequestReplyMessagediff --git a/python/teams/team-one/src/team_one/messages.py b/python/teams/team-one/src/team_one/messages.pyindex 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@dataclassdiff --git a/python/tests/test_closure_agent.py b/python/tests/test_closure_agent.pynew file mode 100644index 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.pyindex 0cbbcd6ad..4a883ee2c 100644--- a/python/tests/test_types.py+++ b/python/tests/test_types.py@@ -1,7 +1,8 @@from types import NoneTypefrom 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_typesfrom agnext.core import CancellationToken