A programming framework for agentic AI
Implement try_get_underlying_agent_instance (#249)
Jack Gerrits3ba7a48b13f5
diff --git a/python/src/agnext/application/_single_threaded_agent_runtime.py b/python/src/agnext/application/_single_threaded_agent_runtime.pyindex 585a2b1ce..c4ed72a2b 100644--- a/python/src/agnext/application/_single_threaded_agent_runtime.py+++ b/python/src/agnext/application/_single_threaded_agent_runtime.py@@ -9,7 +9,7 @@ from collections import defaultdictfrom collections.abc import Sequencefrom dataclasses import dataclassfrom enum import Enum-from typing import Any, Awaitable, Callable, DefaultDict, Dict, List, Mapping, ParamSpec, Set, TypeVar, cast+from typing import Any, Awaitable, Callable, DefaultDict, Dict, List, Mapping, ParamSpec, Set, Type, TypeVar, castfrom ..core import (MESSAGE_TYPE_REGISTRY,@@ -482,7 +482,7 @@ class SingleThreadedAgentRuntime(AgentRuntime):return self._instantiated_agents[agent_id]if agent_id.name not in self._agent_factories:- raise ValueError(f"Agent with name {agent_id.name} not found.")+ raise LookupError(f"Agent with name {agent_id.name} not found.")agent_factory = self._agent_factories[agent_id.name]@@ -499,6 +499,19 @@ class SingleThreadedAgentRuntime(AgentRuntime):id = await self.get(name, namespace=namespace)return AgentProxy(id, self)+ # TODO: uncomment out the following type ignore when this is fixed in mypy: https://github.com/python/mypy/issues/3737+ async def try_get_underlying_agent_instance(self, id: AgentId, type: Type[T] = Agent) -> T: # type: ignore[assignment]+ if id.name not in self._agent_factories:+ raise LookupError(f"Agent with name {id.name} not found.")++ # TODO: check if remote+ agent_instance = await self._get_agent(id)++ if not isinstance(agent_instance, type):+ raise TypeError(f"Agent with name {id.name} is not of type {type.__name__}")++ return agent_instance+# Hydrate the agent instances in a namespace. The primary reason for this is# to ensure message type subscriptions are set up.async def _process_seen_namespace(self, namespace: str) -> None:diff --git a/python/src/agnext/core/_agent_runtime.py b/python/src/agnext/core/_agent_runtime.pyindex 1d423180e..a37772138 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 contextlib import contextmanagerfrom contextvars import ContextVar-from typing import Any, Awaitable, Callable, Generator, Mapping, Protocol, TypeVar, overload, runtime_checkable+from typing import Any, Awaitable, Callable, Generator, Mapping, Protocol, Type, TypeVar, overload, runtime_checkablefrom ._agent import Agentfrom ._agent_id import AgentId@@ -146,6 +146,26 @@ class AgentRuntime(Protocol):"""...+ # TODO: uncomment out the following type ignore when this is fixed in mypy: https://github.com/python/mypy/issues/3737+ async def try_get_underlying_agent_instance(self, id: AgentId, type: Type[T] = Agent) -> T: # type: ignore[assignment]+ """Try to get the underlying agent instance by name and namespace. This is generally discouraged (hence the long name), but can be useful in some cases.++ If the underlying agent is not accessible, this will raise an exception.++ Args:+ id (AgentId): The agent id.+ type (Type[T], optional): The expected type of the agent. Defaults to Agent.++ Returns:+ T: The concrete agent instance.++ Raises:+ LookupError: If the agent is not found.+ NotAccessibleError: If the agent is not accessible, for example if it is located remotely.+ TypeError: If the agent is not of the expected type.+ """+ ...+@overloadasync def register_and_get(self,diff --git a/python/src/agnext/core/exceptions.py b/python/src/agnext/core/exceptions.pyindex 4c4a70ded..f35c3fbfe 100644--- a/python/src/agnext/core/exceptions.py+++ b/python/src/agnext/core/exceptions.py@@ -15,3 +15,7 @@ class UndeliverableException(Exception):class MessageDroppedException(Exception):"""Raised when a message is dropped."""+++class NotAccessibleError(Exception):+ """Tried to access a value that is not accessible. For example if it is remote cannot be accessed locally."""diff --git a/python/src/agnext/worker/worker_runtime.py b/python/src/agnext/worker/worker_runtime.pyindex e80102ce4..8d5f6810f 100644--- a/python/src/agnext/worker/worker_runtime.py+++ b/python/src/agnext/worker/worker_runtime.py@@ -21,6 +21,7 @@ from typing import (Mapping,ParamSpec,Set,+ Type,TypeVar,cast,)@@ -410,6 +411,10 @@ class WorkerAgentRuntime(AgentRuntime):id = await self.get(name, namespace=namespace)return AgentProxy(id, self)+ # TODO: uncomment out the following type ignore when this is fixed in mypy: https://github.com/python/mypy/issues/3737+ async def try_get_underlying_agent_instance(self, id: AgentId, type: Type[T] = Agent) -> T: # type: ignore[assignment]+ raise NotImplementedError("try_get_underlying_agent_instance is not yet implemented.")+# Hydrate the agent instances in a namespace. The primary reason for this is# to ensure message type subscriptions are set up.async def _process_seen_namespace(self, namespace: str) -> None:diff --git a/python/tests/test_cancellation.py b/python/tests/test_cancellation.pyindex f383d8de7..a077a2c9b 100644--- a/python/tests/test_cancellation.py+++ b/python/tests/test_cancellation.py@@ -73,7 +73,7 @@ async def test_cancellation_with_token() -> None:await responseassert response.done()- long_running_agent: LongRunningAgent = await runtime._get_agent(long_running) # type: ignore+ long_running_agent = await runtime.try_get_underlying_agent_instance(long_running, type=LongRunningAgent)assert long_running_agent.calledassert long_running_agent.cancelled@@ -100,10 +100,10 @@ async def test_nested_cancellation_only_outer_called() -> None:await responseassert response.done()- nested_agent: NestingLongRunningAgent = await runtime._get_agent(nested) # type: ignore+ nested_agent = await runtime.try_get_underlying_agent_instance(nested, type=NestingLongRunningAgent)assert nested_agent.calledassert nested_agent.cancelled- long_running_agent: LongRunningAgent = await runtime._get_agent(long_running) # type: ignore+ long_running_agent = await runtime.try_get_underlying_agent_instance(long_running, type=LongRunningAgent)assert long_running_agent.called is Falseassert long_running_agent.cancelled is False@@ -130,9 +130,9 @@ async def test_nested_cancellation_inner_called() -> None:await responseassert response.done()- nested_agent: NestingLongRunningAgent = await runtime._get_agent(nested) # type: ignore+ nested_agent = await runtime.try_get_underlying_agent_instance(nested, type=NestingLongRunningAgent)assert nested_agent.calledassert nested_agent.cancelled- long_running_agent: LongRunningAgent = await runtime._get_agent(long_running) # type: ignore+ long_running_agent = await runtime.try_get_underlying_agent_instance(long_running, type=LongRunningAgent)assert long_running_agent.calledassert long_running_agent.cancelleddiff --git a/python/tests/test_intervention.py b/python/tests/test_intervention.pyindex 395305b22..62942bbb1 100644--- a/python/tests/test_intervention.py+++ b/python/tests/test_intervention.py@@ -27,7 +27,7 @@ async def test_intervention_count_messages() -> None:await run_context.stop()assert handler.num_messages == 1- loopback_agent: LoopbackAgent = await runtime._get_agent(loopback) # type: ignore+ loopback_agent = await runtime.try_get_underlying_agent_instance(loopback, type=LoopbackAgent)assert loopback_agent.num_calls == 1@pytest.mark.asyncio@@ -48,7 +48,7 @@ async def test_intervention_drop_send() -> None:await run_context.stop()- loopback_agent: LoopbackAgent = await runtime._get_agent(loopback) # type: ignore+ loopback_agent = await runtime.try_get_underlying_agent_instance(loopback, type=LoopbackAgent)assert loopback_agent.num_calls == 0@@ -92,7 +92,7 @@ async def test_intervention_raise_exception_on_send() -> None:await run_context.stop()- long_running_agent: LoopbackAgent = await runtime._get_agent(long_running) # type: ignore+ long_running_agent = await runtime.try_get_underlying_agent_instance(long_running, type=LoopbackAgent)assert long_running_agent.num_calls == 0@pytest.mark.asyncio@@ -115,5 +115,5 @@ async def test_intervention_raise_exception_on_respond() -> None:await run_context.stop()- long_running_agent: LoopbackAgent = await runtime._get_agent(long_running) # type: ignore+ long_running_agent = await runtime.try_get_underlying_agent_instance(long_running, type=LoopbackAgent)assert long_running_agent.num_calls == 1diff --git a/python/tests/test_runtime.py b/python/tests/test_runtime.pyindex 8cef7b16c..d7e4f1a91 100644--- a/python/tests/test_runtime.py+++ b/python/tests/test_runtime.py@@ -34,11 +34,11 @@ async def test_register_receives_publish() -> None:await run_context.stop_when_idle()# Agent in default namespace should have received the message- long_running_agent: LoopbackAgent = await runtime._get_agent(await runtime.get("name")) # type: ignore+ long_running_agent = await runtime.try_get_underlying_agent_instance(await runtime.get("name"), type=LoopbackAgent)assert long_running_agent.num_calls == 1# Agent in other namespace should not have received the message- other_long_running_agent: LoopbackAgent = await runtime._get_agent(await runtime.get("name", namespace="other")) # type: ignore+ other_long_running_agent: LoopbackAgent = await runtime.try_get_underlying_agent_instance(await runtime.get("name", namespace="other"), type=LoopbackAgent)assert other_long_running_agent.num_calls == 0@@ -67,5 +67,5 @@ async def test_register_receives_publish_cascade() -> None:# Check that each agent received the correct number of messages.for i in range(num_agents):- agent: CascadingAgent = await runtime._get_agent(await runtime.get(f"name{i}")) # type: ignore+ agent = await runtime.try_get_underlying_agent_instance(await runtime.get(f"name{i}"), CascadingAgent)assert agent.num_calls == total_num_calls_expecteddiff --git a/python/tests/test_state.py b/python/tests/test_state.pyindex b73e244bc..b88f79b20 100644--- a/python/tests/test_state.py+++ b/python/tests/test_state.py@@ -29,7 +29,7 @@ async def test_agent_can_save_state() -> None:runtime = SingleThreadedAgentRuntime()agent1_id = await runtime.register_and_get("name1", StatefulAgent)- agent1: StatefulAgent = await runtime._get_agent(agent1_id) # type: ignore+ agent1: StatefulAgent = await runtime.try_get_underlying_agent_instance(agent1_id, type=StatefulAgent)assert agent1.state == 0agent1.state = 1assert agent1.state == 1@@ -47,7 +47,7 @@ async def test_runtime_can_save_state() -> None:runtime = SingleThreadedAgentRuntime()agent1_id = await runtime.register_and_get("name1", StatefulAgent)- agent1: StatefulAgent = await runtime._get_agent(agent1_id) # type: ignore+ agent1: StatefulAgent = await runtime.try_get_underlying_agent_instance(agent1_id, type=StatefulAgent)assert agent1.state == 0agent1.state = 1assert agent1.state == 1@@ -56,7 +56,7 @@ async def test_runtime_can_save_state() -> None:runtime2 = SingleThreadedAgentRuntime()agent2_id = await runtime2.register_and_get("name1", StatefulAgent)- agent2: StatefulAgent = await runtime2._get_agent(agent2_id) # type: ignore+ agent2: StatefulAgent = await runtime2.try_get_underlying_agent_instance(agent2_id, type=StatefulAgent)await runtime2.load_state(runtime_state)assert agent2.state == 1