A programming framework for agentic AI
remove _ from send/pub, add docs, (#91)
Jack Gerrits4cebf7257b6d
diff --git a/docs/src/conf.py b/docs/src/conf.pyindex abdf42268..edc48138c 100644--- a/docs/src/conf.py+++ b/docs/src/conf.py@@ -54,5 +54,4 @@ html_theme_options = {autodoc_default_options = {"members": True,"undoc-members": True,- "private-members": True}\ No newline at end of filediff --git a/docs/src/core-concepts/agent.md b/docs/src/core-concepts/agent.mdindex fabd441e4..77ec45e86 100644--- a/docs/src/core-concepts/agent.md+++ b/docs/src/core-concepts/agent.md@@ -49,7 +49,7 @@ When an agent receives a message the runtime will invoke the agent's message han### Direct Communication-Direct communication is effectively an RPC call directly to another agent. When sending a direct message to another agent, the receiving agent can respond to the message with another message, or simply return `None`. To send a message to another agent, within a message handler use the {py:meth}`agnext.core.BaseAgent._send_message` method. Awaiting this call will return the response of the invoked agent. If the receiving agent raises an exception, this will be propagated back to the sending agent.+Direct communication is effectively an RPC call directly to another agent. When sending a direct message to another agent, the receiving agent can respond to the message with another message, or simply return `None`. To send a message to another agent, within a message handler use the {py:meth}`agnext.core.BaseAgent.send_message` method. Awaiting this call will return the response of the invoked agent. If the receiving agent raises an exception, this will be propagated back to the sending agent.To send a message to an agent outside of agent handling a message the message should be sent via the runtime with the {py:meth}`agnext.core.AgentRuntime.send_message` method. This is often how an application might "start" a workflow or conversation.@@ -57,7 +57,7 @@ To send a message to an agent outside of agent handling a message the message shAs part of the agent's implementation it must advertise the message types that it would like to receive when published ({py:attr}`agnext.core.Agent.subscriptions`). If one of these messages is published, the agent's message handler will be invoked. The key difference between direct and broadcast communication is that broadcast communication is not a request/response pattern. When an agent publishes a message it is one way, it is not expecting a response from any other agent. In fact, they cannot respond to the message.-To publish a message to all agents, use the {py:meth}`agnext.core.BaseAgent._publish_message` method. This call must still be awaited to allow the runtime to deliver the message to all agents, but it will always return `None`. If an agent raises an exception while handling a published message, this will be logged but will not be propagated back to the publishing agent.+To publish a message to all agents, use the {py:meth}`agnext.core.BaseAgent.publish_message` method. This call must still be awaited to allow the runtime to deliver the message to all agents, but it will always return `None`. If an agent raises an exception while handling a published message, this will be logged but will not be propagated back to the publishing agent.To publish a message to all agents outside of an agent handling a message, the message should be published via the runtime with the {py:meth}`agnext.core.AgentRuntime.publish_message` method.diff --git a/docs/src/core-concepts/namespace.md b/docs/src/core-concepts/namespace.mdnew file mode 100644index 000000000..235aad7d8--- /dev/null+++ b/docs/src/core-concepts/namespace.md@@ -0,0 +1,18 @@+# Namespace++A namespace is a logical boundary between agents. By default, agents in one+namespace cannot communicate with agents in another namespace.++Namespaces are strings, and the default is `default`.++Two possible use cases of agents are:++- Creating a multi-tenant system where each tenant has its own namespace. For+ example, a chat system where each tenant has its own set of agents.+- Security boundaries between agent groups. For example, a chat system where+ agents in the `admin` namespace can communicate with agents in the `user`+ namespace, but not the other way around.++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 filediff --git a/docs/src/core-concepts/runtime.md b/docs/src/core-concepts/runtime.mdindex b4ea1d7d2..becfdb24e 100644--- a/docs/src/core-concepts/runtime.md+++ b/docs/src/core-concepts/runtime.md@@ -10,3 +10,27 @@ Further readings:1. {py:class}`agnext.core.AgentRuntime`2. {py:class}`agnext.application.SingleThreadedAgentRuntime`++## Agent Registration++Agents are registered with the runtime using the+{py:meth}`agnext.core.AgentRuntime.register` method. The process of registration+associates some name, which is the `type` of the agent with a factory function+that is able to create an instance of the agent in a given namespace. The reason+for the factory function is to allow automatic creation of agents when they are+needed, including automatic creation of agents for not yet existing namespaces.++Once an agent is registered, a reference to the agent can be retrieved by+calling {py:meth}`agnext.core.AgentRuntime.get` or+{py:meth}`agnext.core.AgentRuntime.get_proxy`. There is a convenience method+{py:meth}`agnext.core.AgentRuntime.register_and_get` that both registers a type+and gets a reference.++A byproduct of this process of `register` + `get` is that+{py:class}`agnext.core.Agent` interface is a purely implementation contract. All+agents must be communicated with via the runtime. This is a key design decision+that allows the runtime to manage the lifecycle of agents, and to provide a+consistent API for interacting with agents. Therefore, to communicate with+another agent the {py:class}`agnext.core.AgentId` must be used. There is a+convenience class {py:meth}`agnext.core.AgentProxy` that bundles an ID and a+runtime together.\ No newline at end of filediff --git a/docs/src/guides/type-routed-agent.md b/docs/src/guides/type-routed-agent.mdindex ed6dc1648..433971704 100644--- a/docs/src/guides/type-routed-agent.md+++ b/docs/src/guides/type-routed-agent.md@@ -38,7 +38,7 @@ class MyAgent(TypeRoutedAgent):self, message: TextMessage | MultiModalMessage, cancellation_token: CancellationToken) -> None:self._received_count += 1- await self._publish_message(+ await self.publish_message(TextMessage(content=f"I received a message from {message.source}. Message received #{self._received_count}",source=self.metadata["name"],diff --git a/docs/src/index.rst b/docs/src/index.rstindex c729f2e14..0b5115f8d 100644--- a/docs/src/index.rst+++ b/docs/src/index.rst@@ -29,6 +29,7 @@ common uses, such as chat completion agents, but also allows for fully custom agcore-concepts/toolscore-concepts/cancellationcore-concepts/logging+ core-concepts/namespace.. toctree:::caption: Guidesdiff --git a/examples/assistant.py b/examples/assistant.pyindex 989a57a92..5a1eda194 100644--- a/examples/assistant.py+++ b/examples/assistant.py@@ -104,7 +104,7 @@ class UserProxyAgent(TypeRoutedAgent): # type: ignorereturnelse:# Publish user input and exit handler.- await self._publish_message(TextMessage(content=user_input, source=self.metadata["name"]))+ await self.publish_message(TextMessage(content=user_input, source=self.metadata["name"]))returndiff --git a/examples/chat_room.py b/examples/chat_room.pyindex e3cd584a2..32e1df0a1 100644--- a/examples/chat_room.py+++ b/examples/chat_room.py@@ -72,7 +72,7 @@ Use the following JSON format to provide your thought on the latest message and# Publish the response if needed.if respond is True or str(respond).lower().strip() == "true":- await self._publish_message(TextMessage(source=self.metadata["name"], content=str(response)))+ await self.publish_message(TextMessage(source=self.metadata["name"], content=str(response)))class ChatRoomUserAgent(TextualUserAgent): # type: ignorediff --git a/examples/inner_outer.py b/examples/inner_outer.pyindex 4bc133237..503af6890 100644--- a/examples/inner_outer.py+++ b/examples/inner_outer.py@@ -30,7 +30,7 @@ class Outer(TypeRoutedAgent): # type: ignore@message_handler() # type: ignoreasync def on_new_message(self, message: MessageType, cancellation_token: CancellationToken) -> MessageType: # type: ignore- inner_response = self._send_message(message, self._inner)+ inner_response = self.send_message(message, self._inner)inner_message = await inner_responseassert isinstance(inner_message, MessageType)return MessageType(body=f"Outer: {inner_message.body}", sender=self.metadata["name"])diff --git a/src/agnext/chat/agents/chat_completion_agent.py b/src/agnext/chat/agents/chat_completion_agent.pyindex 1600fa688..86ac1a6f8 100644--- a/src/agnext/chat/agents/chat_completion_agent.py+++ b/src/agnext/chat/agents/chat_completion_agent.py@@ -114,7 +114,7 @@ class ChatCompletionAgent(TypeRoutedAgent):response = await self._generate_response(message.response_format, cancellation_token)# Publish the response.- await self._publish_message(response)+ await self.publish_message(response)@message_handler()async def on_tool_call_message(@@ -190,7 +190,7 @@ class ChatCompletionAgent(TypeRoutedAgent):and all(isinstance(x, FunctionCall) for x in response.content)):# Send a function call message to itself.- response = await self._send_message(+ response = await self.send_message(message=FunctionCallMessage(content=response.content, source=self.metadata["name"]),recipient=self.id,cancellation_token=cancellation_token,@@ -236,7 +236,7 @@ class ChatCompletionAgent(TypeRoutedAgent):approval_request = ToolApprovalRequest(tool_call=FunctionCall(id=call_id, arguments=json.dumps(args), name=name))- approval_response = await self._send_message(+ approval_response = await self.send_message(message=approval_request,recipient=self._tool_approver,cancellation_token=cancellation_token,diff --git a/src/agnext/chat/agents/image_generation_agent.py b/src/agnext/chat/agents/image_generation_agent.pyindex cf1ffb7bc..08c6ea183 100644--- a/src/agnext/chat/agents/image_generation_agent.py+++ b/src/agnext/chat/agents/image_generation_agent.py@@ -41,7 +41,7 @@ class ImageGenerationAgent(TypeRoutedAgent):@message_handlerasync def on_publish_now(self, message: PublishNow, cancellation_token: CancellationToken) -> None:response = await self._generate_response(cancellation_token)- self._publish_message(response)+ self.publish_message(response)async def _generate_response(self, cancellation_token: CancellationToken) -> MultiModalMessage:messages = await self._memory.get_messages()diff --git a/src/agnext/chat/agents/oai_assistant.py b/src/agnext/chat/agents/oai_assistant.pyindex 070657e23..dd82ead18 100644--- a/src/agnext/chat/agents/oai_assistant.py+++ b/src/agnext/chat/agents/oai_assistant.py@@ -79,7 +79,7 @@ class OpenAIAssistantAgent(TypeRoutedAgent):async def on_publish_now(self, message: PublishNow, cancellation_token: CancellationToken) -> None:"""Handle a publish now message. This method generates a response and publishes it."""response = await self._generate_response(message.response_format, cancellation_token)- await self._publish_message(response)+ await self.publish_message(response)async def _generate_response(self, requested_response_format: ResponseFormat, cancellation_token: CancellationTokendiff --git a/src/agnext/chat/agents/user_proxy.py b/src/agnext/chat/agents/user_proxy.pyindex 9aeb21340..4f6024d25 100644--- a/src/agnext/chat/agents/user_proxy.py+++ b/src/agnext/chat/agents/user_proxy.py@@ -24,7 +24,7 @@ class UserProxyAgent(TypeRoutedAgent):async def on_publish_now(self, message: PublishNow, cancellation_token: CancellationToken) -> None:"""Handle a publish now message. This method prompts the user for input, then publishes it."""user_input = await self.get_user_input(self._user_input_prompt)- await self._publish_message(TextMessage(content=user_input, source=self.metadata["name"]))+ await self.publish_message(TextMessage(content=user_input, source=self.metadata["name"]))async def get_user_input(self, prompt: str) -> str:"""Get user input from the console. Override this method to customize how user input is retrieved."""diff --git a/src/agnext/chat/patterns/group_chat_manager.py b/src/agnext/chat/patterns/group_chat_manager.pyindex 50886de7d..6ce821b39 100644--- a/src/agnext/chat/patterns/group_chat_manager.py+++ b/src/agnext/chat/patterns/group_chat_manager.py@@ -141,7 +141,7 @@ class GroupChatManager(TypeRoutedAgent):if speaker is not None:# Send the message to the selected speaker to ask it to publish a response.- await self._send_message(PublishNow(), speaker)+ await self.send_message(PublishNow(), speaker)def save_state(self) -> Mapping[str, Any]:return {diff --git a/src/agnext/chat/patterns/orchestrator_chat.py b/src/agnext/chat/patterns/orchestrator_chat.pyindex 7bb5c664d..f8e781362 100644--- a/src/agnext/chat/patterns/orchestrator_chat.py+++ b/src/agnext/chat/patterns/orchestrator_chat.py@@ -50,7 +50,7 @@ class OrchestratorChat(TypeRoutedAgent):while total_turns < self._max_turns:# Reset all agents.for agent in [*self._specialists, self._orchestrator]:- await self._send_message(Reset(), agent)+ await self.send_message(Reset(), agent)# Create the task specs.task_specs = f"""@@ -72,7 +72,7 @@ Some additional points to consider:# Send the task specs to the orchestrator and specialists.for agent in [*self._specialists, self._orchestrator]:- await self._send_message(TextMessage(content=task_specs, source=self.metadata["name"]), agent)+ await self.send_message(TextMessage(content=task_specs, source=self.metadata["name"]), agent)# Inner loop.stalled_turns = 0@@ -126,7 +126,7 @@ Some additional points to consider:# Update agents.for agent in [*self._specialists, self._orchestrator]:- _ = await self._send_message(+ _ = await self.send_message(TextMessage(content=subtask, source=self.metadata["name"]),agent,)@@ -138,12 +138,12 @@ Some additional points to consider:raise ValueError(f"Invalid next speaker: {data['next_speaker']['answer']}") from e# Ask speaker to speak.- speaker_response = await self._send_message(RespondNow(), speaker)+ speaker_response = await self.send_message(RespondNow(), speaker)assert speaker_response is not None# Update all other agents with the speaker's response.for agent in [agent for agent in self._specialists if agent != speaker] + [self._orchestrator]:- await self._send_message(+ await self.send_message(TextMessage(content=speaker_response.content,source=speaker_response.source,@@ -161,7 +161,7 @@ Some additional points to consider:async def _prepare_task(self, task: str, sender: str) -> Tuple[str, str, str, str]:# Reset planner.- await self._send_message(Reset(), self._planner)+ await self.send_message(Reset(), self._planner)# A reusable description of the team.team = "\n".join(@@ -198,8 +198,8 @@ When answering this survey, keep in mind that "facts" will typically be specific""".strip()# Ask the planner to obtain prior knowledge about facts.- await self._send_message(TextMessage(content=closed_book_prompt, source=sender), self._planner)- facts_response = await self._send_message(RespondNow(), self._planner)+ await self.send_message(TextMessage(content=closed_book_prompt, source=sender), self._planner)+ facts_response = await self.send_message(RespondNow(), self._planner)facts = str(facts_response.content)@@ -211,8 +211,8 @@ When answering this survey, keep in mind that "facts" will typically be specificBased on the team composition, and known and unknown facts, please devise a short bullet-point plan for addressing the original request. Remember, there is no requirement to involve all team members -- a team member's particular expertise may not be needed for this task.""".strip()# Send second messag eto the planner.- await self._send_message(TextMessage(content=plan_prompt, source=sender), self._planner)- plan_response = await self._send_message(RespondNow(), self._planner)+ await self.send_message(TextMessage(content=plan_prompt, source=sender), self._planner)+ plan_response = await self.send_message(RespondNow(), self._planner)plan = str(plan_response.content)return team, names, facts, plan@@ -264,9 +264,9 @@ Please output an answer in pure JSON format according to the following schema. Trequest = step_promptwhile True:# Send a message to the orchestrator.- await self._send_message(TextMessage(content=request, source=sender), self._orchestrator)+ await self.send_message(TextMessage(content=request, source=sender), self._orchestrator)# Request a response.- step_response = await self._send_message(+ step_response = await self.send_message(RespondNow(response_format=ResponseFormat.json_object),self._orchestrator,)@@ -327,9 +327,9 @@ Please output an answer in pure JSON format according to the following schema. T{facts}""".strip()# Send a message to the orchestrator.- await self._send_message(TextMessage(content=new_facts_prompt, source=sender), self._orchestrator)+ await self.send_message(TextMessage(content=new_facts_prompt, source=sender), self._orchestrator)# Request a response.- new_facts_response = await self._send_message(RespondNow(), self._orchestrator)+ new_facts_response = await self.send_message(RespondNow(), self._orchestrator)return str(new_facts_response.content)async def _educated_guess(self, facts: str, sender: str) -> Any:@@ -352,12 +352,12 @@ Please output an answer in pure JSON format according to the following schema. Trequest = educated_guess_promtwhile True:# Send a message to the orchestrator.- await self._send_message(+ await self.send_message(TextMessage(content=request, source=sender),self._orchestrator,)# Request a response.- response = await self._send_message(+ response = await self.send_message(RespondNow(response_format=ResponseFormat.json_object),self._orchestrator,)@@ -386,7 +386,7 @@ Team membership:{team}""".strip()# Send a message to the orchestrator.- await self._send_message(TextMessage(content=new_plan_prompt, source=sender), self._orchestrator)+ await self.send_message(TextMessage(content=new_plan_prompt, source=sender), self._orchestrator)# Request a response.- new_plan_response = await self._send_message(RespondNow(), self._orchestrator)+ new_plan_response = await self.send_message(RespondNow(), self._orchestrator)return str(new_plan_response.content)diff --git a/src/agnext/components/models/_model_info.py b/src/agnext/components/models/_model_info.pyindex 7cbf9ebc3..9c919c0f7 100644--- a/src/agnext/components/models/_model_info.py+++ b/src/agnext/components/models/_model_info.py@@ -5,6 +5,7 @@ from ._model_client import ModelCapabilities# Based on: https://platform.openai.com/docs/models/continuous-model-upgrades# This is a moving target, so correctness is checked by the model value returned by openai against expected values at runtime``_MODEL_POINTERS = {+ "gpt-4o": "gpt-4o-2024-05-13","gpt-4-turbo": "gpt-4-turbo-2024-04-09","gpt-4-turbo-preview": "gpt-4-0125-preview","gpt-4": "gpt-4-0613",@@ -14,6 +15,11 @@ _MODEL_POINTERS = {}_MODEL_CAPABILITIES: Dict[str, ModelCapabilities] = {+ "gpt-4o-2024-05-13": {+ "vision": True,+ "function_calling": True,+ "json_output": True,+ },"gpt-4-turbo-2024-04-09": {"vision": True,"function_calling": True,diff --git a/src/agnext/core/_agent_runtime.py b/src/agnext/core/_agent_runtime.pyindex c1b60bc86..12b2f97c5 100644--- a/src/agnext/core/_agent_runtime.py+++ b/src/agnext/core/_agent_runtime.py@@ -60,7 +60,31 @@ class AgentRuntime(Protocol):agent_factory: Callable[[], T] | Callable[[AgentRuntime, AgentId], T],*,valid_namespaces: Sequence[str] | Type[AllNamespaces] = AllNamespaces,- ) -> None: ...+ ) -> 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:+ .. code-block:: python++ runtime.register(+ "chat_agent",+ lambda: ChatCompletionAgent(+ description="A generic chat agent.",+ system_messages=[SystemMessage("You are a helpful assistant")],+ model_client=OpenAI(model="gpt-4o"),+ memory=BufferedChatMemory(buffer_size=10),+ ),+ )++ """++ ...def get(self, name: str, *, namespace: str = "default") -> AgentId: ...def get_proxy(self, name: str, *, namespace: str = "default") -> AgentProxy: ...diff --git a/src/agnext/core/_base_agent.py b/src/agnext/core/_base_agent.pyindex 7bbb63a4e..239bc7a1c 100644--- a/src/agnext/core/_base_agent.py+++ b/src/agnext/core/_base_agent.py@@ -60,7 +60,7 @@ class BaseAgent(ABC, Agent):async def on_message(self, message: Any, cancellation_token: CancellationToken) -> Any: ...# Returns the response of the message- def _send_message(+ def send_message(self,message: Any,recipient: AgentId,@@ -82,7 +82,7 @@ class BaseAgent(ABC, Agent):cancellation_token.link_future(future)return future- def _publish_message(+ def publish_message(self,message: Any,*,diff --git a/tests/test_cancellation.py b/tests/test_cancellation.pyindex 0f43dc3f8..b17f35d04 100644--- a/tests/test_cancellation.py+++ b/tests/test_cancellation.py@@ -43,7 +43,7 @@ class NestingLongRunningAgent(TypeRoutedAgent):@message_handlerasync def on_new_message(self, message: MessageType, cancellation_token: CancellationToken) -> MessageType:self.called = True- response = self._send_message(message, self._nested_agent, cancellation_token=cancellation_token)+ response = self.send_message(message, self._nested_agent, cancellation_token=cancellation_token)try:val = await responseassert isinstance(val, MessageType)