A programming framework for agentic AI
simplify namespace usage (#116)
Jack Gerrits6189fdb05cf1
diff --git a/python/docs/src/core-concepts/namespace.md b/python/docs/src/core-concepts/namespace.mdindex 235aad7d8..16f83c039 100644--- a/python/docs/src/core-concepts/namespace.md+++ b/python/docs/src/core-concepts/namespace.md@@ -1,7 +1,6 @@# Namespace-A namespace is a logical boundary between agents. By default, agents in one-namespace cannot communicate with agents in another namespace.+Namespace allow for defining logical boundaries between agents.Namespaces are strings, and the default is `default`.@@ -15,4 +14,6 @@ Two possible use cases of agents are:The {py:class}`agnext.core.AgentId` is used to address an agent, it is the combination of the agent's namespace and its name.-When getting an agent reference ({py:meth}`agnext.core.AgentRuntime.get`) or proxy ({py:meth}`agnext.core.AgentRuntime.get_proxy`) from the runtime the namespace can be specified. Agents have an ID property ({py:attr}`agnext.core.Agent.id`) that returns the agent's id. Additionally, the register method takes a factory that can optionally accept the ID as an argument ({py:meth}`agnext.core.AgentRuntime.register`).\ No newline at end of file+When getting an agent reference ({py:meth}`agnext.core.AgentRuntime.get`) or proxy ({py:meth}`agnext.core.AgentRuntime.get_proxy`) from the runtime the namespace can be specified. Agents have an ID property ({py:attr}`agnext.core.Agent.id`) that returns the agent's id. Additionally, the register method takes a factory that can optionally accept the ID as an argument ({py:meth}`agnext.core.AgentRuntime.register`).++By default, there are no restrictions and are left to the application to enforce. The runtime will however automatically create agents in a namespace if it does not exist.diff --git a/python/docs/src/guides/termination-with-intervention.md b/python/docs/src/guides/termination-with-intervention.mdindex 1723df4a4..4e4161439 100644--- a/python/docs/src/guides/termination-with-intervention.md+++ b/python/docs/src/guides/termination-with-intervention.md@@ -68,7 +68,7 @@ Finally, we add this handler to the runtime and use it to detect termination andasync def main() -> None:termination_handler = TerminationHandler()runtime = SingleThreadedAgentRuntime(- before_send=termination_handler+ intervention_handler=termination_handler)# Add Agents and kick off taskdiff --git a/python/examples/coder_reviewer_pub_sub.py b/python/examples/coder_reviewer_pub_sub.pyindex c9815fde9..a20f0a073 100644--- a/python/examples/coder_reviewer_pub_sub.py+++ b/python/examples/coder_reviewer_pub_sub.py@@ -267,7 +267,7 @@ class DisplayAgent(TypeRoutedAgent):async def main() -> None:termination_handler = TerminationHandler()- runtime = SingleThreadedAgentRuntime(before_send=termination_handler)+ runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)runtime.register("ReviewerAgent",lambda: ReviewerAgent(diff --git a/python/examples/mixture_of_agents_pub_sub.py b/python/examples/mixture_of_agents_pub_sub.pyindex 6eff0ec43..b134929b4 100644--- a/python/examples/mixture_of_agents_pub_sub.py+++ b/python/examples/mixture_of_agents_pub_sub.py@@ -133,7 +133,7 @@ class DisplayAgent(TypeRoutedAgent):async def main() -> None:termination_handler = TerminationHandler()- runtime = SingleThreadedAgentRuntime(before_send=termination_handler)+ runtime = SingleThreadedAgentRuntime(intervention_handler=termination_handler)# TODO: use different models for each agent.runtime.register("ReferenceAgent1",diff --git a/python/src/agnext/application/_single_threaded_agent_runtime.py b/python/src/agnext/application/_single_threaded_agent_runtime.pyindex 0db1ae5e3..83f101074 100644--- a/python/src/agnext/application/_single_threaded_agent_runtime.py+++ b/python/src/agnext/application/_single_threaded_agent_runtime.py@@ -6,7 +6,7 @@ from asyncio import Futurefrom collections import defaultdictfrom collections.abc import Sequencefrom dataclasses import dataclass-from typing import Any, Awaitable, Callable, DefaultDict, Dict, List, Mapping, ParamSpec, Set, Type, TypeVar, cast+from typing import Any, Awaitable, Callable, DefaultDict, Dict, List, Mapping, ParamSpec, Set, TypeVar, castfrom ..core import (Agent,@@ -14,7 +14,6 @@ from ..core import (AgentMetadata,AgentProxy,AgentRuntime,- AllNamespaces,CancellationToken,agent_instantiation_context,)@@ -82,15 +81,13 @@ class Counter:class SingleThreadedAgentRuntime(AgentRuntime):- def __init__(self, *, before_send: InterventionHandler | None = None) -> None:+ def __init__(self, *, intervention_handler: InterventionHandler | None = None) -> None:self._message_queue: List[PublishMessageEnvelope | SendMessageEnvelope | ResponseMessageEnvelope] = []# (namespace, type) -> List[AgentId]self._per_type_subscribers: DefaultDict[tuple[str, type], Set[AgentId]] = defaultdict(set)self._agent_factories: Dict[str, Callable[[], Agent] | Callable[[AgentRuntime, AgentId], Agent]] = {}- # If empty, then all namespaces are valid for that agent type- self._valid_namespaces: Dict[str, Sequence[str]] = {}self._instantiated_agents: Dict[AgentId, Agent] = {}- self._before_send = before_send+ self._intervention_handler = intervention_handlerself._known_namespaces: set[str] = set()self._outstanding_tasks = Counter()@@ -322,9 +319,11 @@ class SingleThreadedAgentRuntime(AgentRuntime):match message_envelope:case SendMessageEnvelope(message=message, sender=sender, recipient=recipient, future=future):- if self._before_send is not None:+ if self._intervention_handler is not None:try:- temp_message = await self._before_send.on_send(message, sender=sender, recipient=recipient)+ temp_message = await self._intervention_handler.on_send(+ message, sender=sender, recipient=recipient+ )except BaseException as e:future.set_exception(e)return@@ -339,9 +338,9 @@ class SingleThreadedAgentRuntime(AgentRuntime):message=message,sender=sender,):- if self._before_send is not None:+ if self._intervention_handler is not None:try:- temp_message = await self._before_send.on_publish(message, sender=sender)+ temp_message = await self._intervention_handler.on_publish(message, sender=sender)except BaseException as e:# TODO: we should raise the intervention exception to the publisher.logger.error(f"Exception raised in in intervention handler: {e}", exc_info=True)@@ -354,9 +353,11 @@ class SingleThreadedAgentRuntime(AgentRuntime):self._outstanding_tasks.increment()asyncio.create_task(self._process_publish(message_envelope))case ResponseMessageEnvelope(message=message, sender=sender, recipient=recipient, future=future):- if self._before_send is not None:+ if self._intervention_handler is not None:try:- temp_message = await self._before_send.on_response(message, sender=sender, recipient=recipient)+ temp_message = await self._intervention_handler.on_response(+ message, sender=sender, recipient=recipient+ )except BaseException as e:# TODO: should we raise the exception to sender of the response instead?future.set_exception(e)@@ -385,21 +386,14 @@ class SingleThreadedAgentRuntime(AgentRuntime):self,name: str,agent_factory: Callable[[], T] | Callable[[AgentRuntime, AgentId], T],- *,- valid_namespaces: Sequence[str] | Type[AllNamespaces] = AllNamespaces,) -> None:if name in self._agent_factories:raise ValueError(f"Agent with name {name} already exists.")self._agent_factories[name] = agent_factory- if valid_namespaces is not AllNamespaces:- self._valid_namespaces[name] = cast(Sequence[str], valid_namespaces)- else:- self._valid_namespaces[name] = []# For all already prepared namespaces we need to prepare this agentfor namespace in self._known_namespaces:- if self._type_valid_for_namespace(AgentId(name=name, namespace=namespace)):- self._get_agent(AgentId(name=name, namespace=namespace))+ self._get_agent(AgentId(name=name, namespace=namespace))def _invoke_agent_factory(self, agent_factory: Callable[[], T] | Callable[[AgentRuntime, AgentId], T], agent_id: AgentId@@ -419,24 +413,11 @@ class SingleThreadedAgentRuntime(AgentRuntime):return agent- def _type_valid_for_namespace(self, agent_id: AgentId) -> bool:- if agent_id.name not in self._agent_factories:- raise KeyError(f"Agent with name {agent_id.name} not found.")-- valid_namespaces = self._valid_namespaces[agent_id.name]- if len(valid_namespaces) == 0:- return True-- return agent_id.namespace in valid_namespaces-def _get_agent(self, agent_id: AgentId) -> Agent:self._process_seen_namespace(agent_id.namespace)if agent_id in self._instantiated_agents:return self._instantiated_agents[agent_id]- if not self._type_valid_for_namespace(agent_id):- raise ValueError(f"Agent with name {agent_id.name} not valid for namespace {agent_id.namespace}.")-if agent_id.name not in self._agent_factories:raise ValueError(f"Agent with name {agent_id.name} not found.")@@ -463,5 +444,4 @@ class SingleThreadedAgentRuntime(AgentRuntime):self._known_namespaces.add(namespace)for name in self._known_agent_names:- if self._type_valid_for_namespace(AgentId(name=name, namespace=namespace)):- self._get_agent(AgentId(name=name, namespace=namespace))+ self._get_agent(AgentId(name=name, namespace=namespace))diff --git a/python/src/agnext/core/__init__.py b/python/src/agnext/core/__init__.pyindex 210e87fd3..083456716 100644--- a/python/src/agnext/core/__init__.py+++ b/python/src/agnext/core/__init__.py@@ -7,7 +7,7 @@ from ._agent_id import AgentIdfrom ._agent_metadata import AgentMetadatafrom ._agent_props import AgentChildrenfrom ._agent_proxy import AgentProxy-from ._agent_runtime import AgentRuntime, AllNamespaces, agent_instantiation_context+from ._agent_runtime import AgentRuntime, agent_instantiation_contextfrom ._base_agent import BaseAgentfrom ._cancellation_token import CancellationToken@@ -17,7 +17,6 @@ __all__ = ["AgentProxy","AgentMetadata","AgentRuntime",- "AllNamespaces","BaseAgent","CancellationToken","AgentChildren",diff --git a/python/src/agnext/core/_agent_runtime.py b/python/src/agnext/core/_agent_runtime.pyindex a372eb1fc..0236878ae 100644--- a/python/src/agnext/core/_agent_runtime.py+++ b/python/src/agnext/core/_agent_runtime.py@@ -2,7 +2,7 @@ from __future__ import annotationsfrom asyncio import Futurefrom contextvars import ContextVar-from typing import Any, Callable, Mapping, Protocol, Sequence, Type, TypeVar, overload, runtime_checkable+from typing import Any, Callable, Mapping, Protocol, TypeVar, overload, runtime_checkablefrom ._agent import Agentfrom ._agent_id import AgentId@@ -17,10 +17,6 @@ T = TypeVar("T", bound=Agent)agent_instantiation_context: ContextVar[tuple[AgentRuntime, AgentId]] = ContextVar("agent_instantiation_context")-class AllNamespaces:- pass--@runtime_checkableclass AgentRuntime(Protocol):# Returns the response of the message@@ -45,7 +41,9 @@ class AgentRuntime(Protocol):@overloaddef register(- self, name: str, agent_factory: Callable[[], T], *, valid_namespaces: Sequence[str] | Type[AllNamespaces] = ...+ self,+ name: str,+ agent_factory: Callable[[], T],) -> None: ...@overload@@ -53,23 +51,18 @@ class AgentRuntime(Protocol):self,name: str,agent_factory: Callable[[AgentRuntime, AgentId], T],- *,- valid_namespaces: Sequence[str] | Type[AllNamespaces] = ...,) -> None: ...def register(self,name: str,agent_factory: Callable[[], T] | Callable[[AgentRuntime, AgentId], T],- *,- valid_namespaces: Sequence[str] | Type[AllNamespaces] = AllNamespaces,) -> None:"""Register an agent factory with the runtime associated with a specific name. The name must be unique.Args:name (str): The name of the type agent this factory creates.agent_factory (Callable[[], T] | Callable[[AgentRuntime, AgentId], T]): The factory that creates the agent.- valid_namespaces (Sequence[str] | Type[AllNamespaces], optional): Valid namespaces for this type. Defaults to AllNamespaces.Example:@@ -99,7 +92,6 @@ class AgentRuntime(Protocol):agent_factory: Callable[[], T],*,namespace: str = "default",- valid_namespaces: Sequence[str] | Type[AllNamespaces] = ...,) -> AgentId: ...@overload@@ -109,7 +101,6 @@ class AgentRuntime(Protocol):agent_factory: Callable[[AgentRuntime, AgentId], T],*,namespace: str = "default",- valid_namespaces: Sequence[str] | Type[AllNamespaces] = ...,) -> AgentId: ...def register_and_get(@@ -118,7 +109,6 @@ class AgentRuntime(Protocol):agent_factory: Callable[[], T] | Callable[[AgentRuntime, AgentId], T],*,namespace: str = "default",- valid_namespaces: Sequence[str] | Type[AllNamespaces] = AllNamespaces,) -> AgentId:self.register(name, agent_factory)return self.get(name, namespace=namespace)@@ -130,7 +120,6 @@ class AgentRuntime(Protocol):agent_factory: Callable[[], T],*,namespace: str = "default",- valid_namespaces: Sequence[str] | Type[AllNamespaces] = ...,) -> AgentProxy: ...@overload@@ -140,7 +129,6 @@ class AgentRuntime(Protocol):agent_factory: Callable[[AgentRuntime, AgentId], T],*,namespace: str = "default",- valid_namespaces: Sequence[str] | Type[AllNamespaces] = ...,) -> AgentProxy: ...def register_and_get_proxy(@@ -149,7 +137,6 @@ class AgentRuntime(Protocol):agent_factory: Callable[[], T] | Callable[[AgentRuntime, AgentId], T],*,namespace: str = "default",- valid_namespaces: Sequence[str] | Type[AllNamespaces] = AllNamespaces,) -> AgentProxy:self.register(name, agent_factory)return self.get_proxy(name, namespace=namespace)diff --git a/python/tests/test_intervention.py b/python/tests/test_intervention.pyindex ae3683e8b..88e673528 100644--- a/python/tests/test_intervention.py+++ b/python/tests/test_intervention.py@@ -18,7 +18,7 @@ async def test_intervention_count_messages() -> None:return messagehandler = DebugInterventionHandler()- runtime = SingleThreadedAgentRuntime(before_send=handler)+ runtime = SingleThreadedAgentRuntime(intervention_handler=handler)loopback = runtime.register_and_get("name", LoopbackAgent)response = runtime.send_message(MessageType(), recipient=loopback)@@ -38,7 +38,7 @@ async def test_intervention_drop_send() -> None:return DropMessagehandler = DropSendInterventionHandler()- runtime = SingleThreadedAgentRuntime(before_send=handler)+ runtime = SingleThreadedAgentRuntime(intervention_handler=handler)loopback = runtime.register_and_get("name", LoopbackAgent)response = runtime.send_message(MessageType(), recipient=loopback)@@ -61,7 +61,7 @@ async def test_intervention_drop_response() -> None:return DropMessagehandler = DropResponseInterventionHandler()- runtime = SingleThreadedAgentRuntime(before_send=handler)+ runtime = SingleThreadedAgentRuntime(intervention_handler=handler)loopback = runtime.register_and_get("name", LoopbackAgent)response = runtime.send_message(MessageType(), recipient=loopback)@@ -84,7 +84,7 @@ async def test_intervention_raise_exception_on_send() -> None:raise InterventionExceptionhandler = ExceptionInterventionHandler()- runtime = SingleThreadedAgentRuntime(before_send=handler)+ runtime = SingleThreadedAgentRuntime(intervention_handler=handler)long_running = runtime.register_and_get("name", LoopbackAgent)response = runtime.send_message(MessageType(), recipient=long_running)@@ -109,7 +109,7 @@ async def test_intervention_raise_exception_on_respond() -> None:raise InterventionExceptionhandler = ExceptionInterventionHandler()- runtime = SingleThreadedAgentRuntime(before_send=handler)+ runtime = SingleThreadedAgentRuntime(intervention_handler=handler)long_running = runtime.register_and_get("name", LoopbackAgent)response = runtime.send_message(MessageType(), recipient=long_running)diff --git a/python/tests/test_runtime.py b/python/tests/test_runtime.pyindex c9683f16b..8a663a56e 100644--- a/python/tests/test_runtime.py+++ b/python/tests/test_runtime.py@@ -41,34 +41,3 @@ async def test_register_receives_publish() -> None:other_long_running_agent: LoopbackAgent = runtime._get_agent(runtime.get("name", namespace="other")) # type: ignoreassert other_long_running_agent.num_calls == 0---async def test_try_instantiate_agent_invalid_namespace() -> None:- runtime = SingleThreadedAgentRuntime()-- runtime.register("name", LoopbackAgent, valid_namespaces=["default"])- await runtime.publish_message(MessageType(), namespace="non_default")-- while len(runtime.unprocessed_messages) > 0 or runtime.outstanding_tasks > 0:- await runtime.process_next()-- # Agent in default namespace should have received the message- long_running_agent: LoopbackAgent = runtime._get_agent(runtime.get("name")) # type: ignore- assert long_running_agent.num_calls == 0-- with pytest.raises(ValueError):- _agent = runtime.get("name", namespace="non_default")--async def test_send_crosses_namepace() -> None:- runtime = SingleThreadedAgentRuntime()-- runtime.register("name", LoopbackAgent)-- default_ns_agent = runtime.get("name")- non_default_ns_agent = runtime.get("name", namespace="non_default")-- with pytest.raises(ValueError):- await runtime.send_message(MessageType(), default_ns_agent, sender=non_default_ns_agent)-