A programming framework for agentic AI
Core concept doc refactor and add documentation for topic and subscription (#414)
Eric Zhu87c00a554d31
diff --git a/python/docs/src/core-concepts/agent-and-multi-agent-application.md b/python/docs/src/core-concepts/agent-and-multi-agent-application.mdnew file mode 100644index 000000000..36a994593--- /dev/null+++ b/python/docs/src/core-concepts/agent-and-multi-agent-application.md@@ -0,0 +1,32 @@+# Agent and Multi-Agent Application++An agent is a software entity that+communicates via messages, maintains a state,+and performs actions in response to messages or a change in its state.+Actions can result in changes to the agent's state and external effects,+for example, updating message history, sending a message, executing code,+or making external API calls.++A wide variety of software applications can be modeled as a collection of independent+agents that communicate with each other:+sensors on a factory floor,+distributed services powering web applications,+business workflows involving multiple stakeholders,+and more recently, artificial intelligence (AI) agents powered by language models+(e.g., GPT-4) that can write code and interact with+other software systems.+We refer to them as multi-agent applications.++```{note}+AI agents make use of language models as part of+their software stacks to perform actions.+```++In a multi-agent application, agents can live in the same process, on the same machine,+or on different machines and across organizational boundaries.+They can be implemented using different AI models, instructions, and programming languages.+They can collaborate and work toward a common goal.++Each agent is a self-contained unit:+developers can build, test and deploy it independently, and reuse it for different scenarios.+Agents are composable: simple agents can form complex applications.diff --git a/python/docs/src/core-concepts/agent-identity-and-lifecycle.md b/python/docs/src/core-concepts/agent-identity-and-lifecycle.mdnew file mode 100644index 000000000..4e550e91e--- /dev/null+++ b/python/docs/src/core-concepts/agent-identity-and-lifecycle.md@@ -0,0 +1,54 @@+# Agent Identity and Lifecycle++In AGNext, the agent runtime manages agents' identities+and lifecycles.+Application does not create agents directly, rather,+it registers an agent type with a factory function for+agent instances.+In this section, we explain how agents are identified+and created by the runtime.++## Agent ID++Agent ID uniquely identifies an agent instance within+an agent runtime -- including distributed runtime.+It is the "address" of the agent instance for receiving messages.+It has two components: agent type and agent key.++```{note}+Agent ID = (Agent Type, Agent Key)+```++The agent type is not an agent class.+It associate an agent with a specific+factory function, which produces instances of agents+of the same agent type.+For example, different factory functions can produce the same+agent class but with different constructor perameters.+The agent key is an instance identifier+for the given agent type.++In a multi-agent application, agent types are+typically defined directly by the application, i.e., they+are defined in the application code.+On the other hand, agent keys are typically generated given+messages delivered to the agents, i.e., they are defined+by the application data.++For example, a runtime has registered the agent type `"code_reviewer"`+with a factory function producing agent instances that perform+code reviews. Each code review request has a unique ID `review_request_id`+to mark a dedicated+session.+In this case, each request can be handled by a new instance+with an agent ID, `("code_reviewer", review_request_id)`.++## Agent Lifecycle++When a runtime delivers a message to an agent instance given its ID,+it either fetches the instance,+or creates it if it does not exist.++The runtime is also responsible for "paging in" or "out" agent instances+to conserve resources and balance load across multiple machines.+This is not implemented yet.diff --git a/python/docs/src/core-concepts/application-stack.md b/python/docs/src/core-concepts/application-stack.mdnew file mode 100644index 000000000..9228e0a3e--- /dev/null+++ b/python/docs/src/core-concepts/application-stack.md@@ -0,0 +1,51 @@+# AGNext Application Stack++AGNext is designed to be an unopinionated framework that can be used to build+a wide variety of multi-agent applications. It is not tied to any specific+agent abstraction or multi-agent pattern.++The following diagram shows the AGNext application stack.++++At the bottom of the stack is the base messaging and routing facilities that+enable agents to communicate with each other. These are managed by the+agent runtime, and for most applications, developers only need to interact+with the high-level APIs provided by the runtime (see [Agent and Agent Runtime](../getting-started/agent-and-agent-runtime.ipynb)).++On top of the communication stack, developers need to define the+types of the messages that agents exchange. A set of message types+forms a behavior contract that agents must adhere to, and the+implementation of the contracts determines how agents handle messages.+The behavior contract is sometimes referred to as the message protocol.+It is the developer's responsibility to implement the behavior contract.+Multi-agent patterns are design patterns that emerge from behavior contracts+(see [Multi-Agent Design Patterns](../getting-started/multi-agent-design-patterns.md)).++## An Example Application++Consider a concrete example of a multi-agent application for+code generation. The application consists of three agents:+Coder Agent, Executor Agent, and Reviewer Agent.+The following diagram shows the data flow between the agents,+and the message types exchanged between them.++++In this example, the behavior contract consists of the following:++- `CodingTaskMsg` message from application to the Coder Agent+- `CodeGenMsg` from Coder Agent to Executor Agent+- `ExecutionResultMsg` from Executor Agent to Reviewer Agent+- `ReviewMsg` from Reviewer Agent to Coder Agent+- `CodingResultMsg` from the Reviewer Agent to the application++The behavior contract is implemented by the agents' handling of these messages. For example, the Reviewer Agent listens for `ExecutionResultMsg`+and evaluates the code execution result to decide whether to approve or reject,+if approved, it sends a `CodingResultMsg` to the application,+otherwise, it sends a `ReviewMsg` to the Coder Agent for another round of+code generation.++This behavior contract is a case of a multi-agent pattern called Reflection,+where a generation result is reviewed by another round of generation,+to improve the overall quality.diff --git a/python/docs/src/core-concepts/architecture.md b/python/docs/src/core-concepts/architecture.mdnew file mode 100644index 000000000..5de22b85d--- /dev/null+++ b/python/docs/src/core-concepts/architecture.md@@ -0,0 +1,56 @@+# AGNext Architecture++AGNext is a framework for building multi-agent applications with AI agents.+At the foundation level, it provides a runtime envionment to facilitate+communication between agents, manage their identities and lifecycles,+and enforce security and privacy boundaries.++## Runtime Architecture++The following diagram shows the runtime architecture of AGNext.++++Agent communicate via messages through the runtime.+A runtime, as shown in the diagram,+can consist of a hosted runtime and multiple worker runtimes.+Agents in worker runtimes communicate with other agents via the hosted runtime+through gateways, while agents in the hosted runtime communicate+directly with each other.+Most single-process applications need only an embedded hosted runtime.++AGNext also offers a set of unopinionated and extensible components for building AI agents.+It does not prescribe an abstraction for AI agents, rather, it provides+a minimal base layer that can be extended to suit the application's needs.+Developers can build agents quickly by using the provided components including+routed agent, AI model clients, tools for AI models, code execution sandboxes,+memory stores, and more.++## API Layers++The API consists of the following layers:++- {py:mod}`agnext.core`+- {py:mod}`agnext.application`+- {py:mod}`agnext.components`++The following diagram shows the relationship between the layers.++++The {py:mod}`agnext.core` layer defines the+core interfaces and base classes for agents, messages, and runtime.+This layer is the foundation of the framework and is used by the other layers.++The {py:mod}`agnext.application` layer provides concrete implementations of+runtime and utilities like logging for building multi-agent applications.++The {py:mod}`agnext.components` layer provides reusable components for building+AI agents, including type-routed agents, AI model clients, tools for AI models,+code execution sandboxes, and memory stores.++The layers are loosely coupled and can be used independently. For example,+you can swap out the runtime in the {py:mod}`agnext.application` layer with your own+runtime implementation.+You can also skip the components in the {py:mod}`agnext.components` layer and+build your own components.diff --git a/python/docs/src/core-concepts/overview.md b/python/docs/src/core-concepts/overview.mddeleted file mode 100644index 408207417..000000000--- a/python/docs/src/core-concepts/overview.md+++ /dev/null@@ -1,147 +0,0 @@-# Overview--This section provides the background and overview of AGNext.--## Agent and Multi-Agent Application--An agent is a software entity that-communicates via messages, maintains a state,-and performs actions in response to messages or a change in its state.-Actions can result in changes to the agent's state and external effects,-for example, updating message history, sending a message, executing code,-or making external API calls.--A wide variety of software applications can be modeled as a collection of independent-agents that communicate with each other:-sensors on a factory floor,-distributed services powering web applications,-business workflows involving multiple stakeholders,-and more recently, artificial intelligence (AI) agents powered by language models-(e.g., GPT-4) that can write code and interact with-other software systems.-We refer to them as multi-agent applications.--```{note}-AI agents make use of language models as part of-their software stacks to perform actions.-```--In a multi-agent application, agents can live in the same process, on the same machine,-or on different machines and across organizational boundaries.-They can be implemented using different AI models, instructions, and programming languages.-They can collaborate and work toward a common goal.--Each agent is a self-contained unit:-developers can build, test and deploy it independently, and reuse it for different scenarios.-Agents are composable: simple agents can form complex applications.--## AGNext Architecture--AGNext is a framework for building multi-agent applications with AI agents.-At the foundation level, it provides a runtime envionment to facilitate-communication between agents, manage their identities and lifecycles,-and enforce security and privacy boundaries.--### Runtime Architecture--The following diagram shows the runtime architecture of AGNext.----Agent communicate via messages through the runtime.-A runtime, as shown in the diagram,-can consist of a hosted runtime and multiple worker runtimes.-Agents in worker runtimes communicate with other agents via the hosted runtime-through gateways, while agents in the hosted runtime communicate-directly with each other.-Most single-process applications need only an embedded hosted runtime.--AGNext also offers a set of unopinionated and extensible components for building AI agents.-It does not prescribe an abstraction for AI agents, rather, it provides-a minimal base layer that can be extended to suit the application's needs.-Developers can build agents quickly by using the provided components including-type-routed agent, AI model clients, tools for AI models, code execution sandboxes,-memory stores, and more.-Developers can also make use of the provided multi-agent patterns to build-orchestrated workflows, group chat systems, and more.--### API Layers--The API consists of the following layers:--- {py:mod}`agnext.core`-- {py:mod}`agnext.application`-- {py:mod}`agnext.components`--The following diagram shows the relationship between the layers.----The {py:mod}`agnext.core` layer defines the-core interfaces and base classes for agents, messages, and runtime.-This layer is the foundation of the framework and is used by the other layers.--The {py:mod}`agnext.application` layer provides concrete implementations of-runtime and utilities like logging for building multi-agent applications.--The {py:mod}`agnext.components` layer provides reusable components for building-AI agents, including type-routed agents, AI model clients, tools for AI models,-code execution sandboxes, and memory stores.--The layers are loosely coupled and can be used independently. For example,-you can swap out the runtime in the {py:mod}`agnext.application` layer with your own-runtime implementation.-You can also skip the components in the {py:mod}`agnext.components` layer and-build your own components.--## AGNext Application Stack--AGNext is designed to be an unopinionated framework that can be used to build-a wide variety of multi-agent applications. It is not tied to any specific-agent abstraction or multi-agent pattern.--The following diagram shows the AGNext application stack.----At the bottom of the stack is the base messaging and routing facilities that-enable agents to communicate with each other. These are managed by the-agent runtime, and for most applications, developers only need to interact-with the high-level APIs provided by the runtime (see [Agent and Agent Runtime](../getting-started/agent-and-agent-runtime.ipynb)).--On top of the communication stack, developers need to define the-types of the messages that agents exchange. A set of message types-forms a behavior contract that agents must adhere to, and the-implementation of the contracts determines how agents handle messages.-The behavior contract is sometimes referred to as the message protocol.-It is the developer's responsibility to implement the behavior contract.-Multi-agent patterns are design patterns that emerge from behavior contracts-(see [Multi-Agent Design Patterns](../getting-started/multi-agent-design-patterns.md)).--### An Example Application--Consider a concrete example of a multi-agent application for-code generation. The application consists of three agents:-Coder Agent, Executor Agent, and Reviewer Agent.-The following diagram shows the data flow between the agents,-and the message types exchanged between them.----In this example, the behavior contract consists of the following:--- `CodingTaskMsg` message from application to the Coder Agent-- `CodeGenMsg` from Coder Agent to Executor Agent-- `ExecutionResultMsg` from Executor Agent to Reviewer Agent-- `ReviewMsg` from Reviewer Agent to Coder Agent-- `CodingResultMsg` from the Reviewer Agent to the application--The behavior contract is implemented by the agents' handling of these messages. For example, the Reviewer Agent listens for `ExecutionResultMsg`-and evaluates the code execution result to decide whether to approve or reject,-if approved, it sends a `CodingResultMsg` to the application,-otherwise, it sends a `ReviewMsg` to the Coder Agent for another round of-code generation.--This behavior contract is a case of a multi-agent pattern called Reflection,-where a generation result is reviewed by another round of generation,-to improve the overall quality.diff --git a/python/docs/src/core-concepts/topic-and-subscription.md b/python/docs/src/core-concepts/topic-and-subscription.mdnew file mode 100644index 000000000..3bb735c9f--- /dev/null+++ b/python/docs/src/core-concepts/topic-and-subscription.md@@ -0,0 +1,76 @@+# Topic and Subscription in Broadcast++In AGNext, there are two ways for runtime to deliver messages,+direct messaging or broadcast. Direct messaging is one to one: the sender+must provide the recipient's agent ID. On the other hand,+broadcast is one to many and the sender does not provide recpients'+agent IDs.++Many scenarios are suitable for broadcast.+For example, in event-driven workflows, agents do not always know who+will handle their messages, and a workflow can be composed of agents+with no inter-dependencies.+This section focuses on the core concepts in broadcast: topic and subscription.++## Topic++A topic defines the scope of a broadcast message.+In essence, AGNext agent runtime implements a publish-subscribe model through+its broadcast API: when publishing a message, the topic mus be specified.+It is an indirection over agent IDs.++A topic consists of two components: topic type and topic source.++```{note}+Topic = (Topic Type, Topic Source)+```++Similar to [agent ID](./agent-identity-and-lifecycle.md#agent-id),+which also has two components, topic type is usually defined by+application code to mark the type of messages the topic is for.+For example, a GitHub agent may use `"GitHub_Issues"` as the topic type+when publishing messages about new issues.++Topic source is the unique identifier for a topic within a topic type.+It is typically defined by application data.+For example, the GitHub agent may use `"github.com/{repo_name}/issues/{issue_number}"`+as the topic source to uniquely identifies the topic.+Topic source allows the publisher to limit the scope of messages and create+silos.++## Subscription++A subscription maps topic to agent IDs.++If a topic has no subscription, messages published to this topic will+not be delivered to any agent.+If a topic has many subscriptions, messages will be delivered+following all the subscriptions to every recipient agent only once.+Applications can add or remove subscriptions using agent runtime's API.++### Type-based Subscription++A type-based subscription maps a topic type to an agent type+(see [agent ID](./agent-identity-and-lifecycle.md#agent-id)).+It declares a mapping from topics to agent IDs without knowing the+exact topic sources and agent keys.+The mechanism is simple: any topic matching the type-based subscription's+topic type will be mapped to an agent ID with the subscription's agent type+and the agent key assigned to the value of the topic source.++```{note}+Type-Based Subscription = Topic Type --> Agent Type+```++For example, a type-based subscription maps topic type `"GitHub_Issues"`+to agent type `"Triage_Agent"`.+When a broadcast message is published to the topic+`("GitHub_Issues", "github.com/microsoft/autogen/issues/99"),+the subscription maps the topic to an agent instance with ID+`("Triage_Agent", "github.com/microsoft/autogen/issues/99")`,+and the runtime will deliver the message to that agent, creating it+if not exist.++Generally speaking, type-based subscription is the preferred way to delcare+subscriptions. It is portable and data-independent:+developers do not need to write application code that depends on specific agent IDs.diff --git a/python/docs/src/getting-started/agent-and-agent-runtime.ipynb b/python/docs/src/getting-started/agent-and-agent-runtime.ipynbindex a0d77ef84..662635d0b 100644--- a/python/docs/src/getting-started/agent-and-agent-runtime.ipynb+++ b/python/docs/src/getting-started/agent-and-agent-runtime.ipynb@@ -6,8 +6,7 @@"source": ["# Agent and Agent Runtime\n","\n",- "In this and the following section, we focus on the \n",- "[core concepts](../core-concepts/overview.md) of AGNext:\n",+ "In this and the following section, we focus on the core concepts of AGNext:\n","agents, agent runtime, messages, and communication.\n","You will not find any AI models or tools here, just the foundational\n","building blocks for building multi-agent applications."@@ -77,7 +76,7 @@"cell_type": "markdown","metadata": {},"source": [- "For convenience, developers can subclass the {py:class}`~agnext.components.TypeRoutedAgent` class\n",+ "For convenience, developers can subclass the {py:class}`~agnext.components.RoutedAgent` class\n","which provides an easy-to use API to implement different message handlers for different message types.\n","See the section on message handlers below."]@@ -86,15 +85,19 @@"cell_type": "markdown","metadata": {},"source": [- "## Registering Agents\n",+ "## Registering Agent Type\n","\n",- "To make an agent available to the runtime, developers can use the\n",+ "To make agents available to the runtime, developers can use the\n","{py:meth}`~agnext.core.AgentRuntime.register` method.\n",- "The process of registration associates a name and a factory function\n",- "that creates an instance of the agent in a given namespace.\n",- "The factory function is used to allow automatic creation of agents when they are needed.\n",+ "The process of registration associates an agent type and a factory function\n",+ "that creates an instance of the agent type.\n",+ "The factory function is used to allow automatic creation of agent instances \n",+ "when they are needed.\n",+ "Read [Agent Identity and Lifecycles](../core-concepts/agent-identity-and-lifecycle.md)\n",+ "about agent type an identity.\n","\n",- "For example, to register an agent with the {py:class}`~agnext.application.SingleThreadedAgentRuntime`,\n",+ "For example, to register an agent type with the \n",+ "{py:class}`~agnext.application.SingleThreadedAgentRuntime`,\n","the following code can be used:"]},@@ -125,9 +128,10 @@"cell_type": "markdown","metadata": {},"source": [- "Once an agent is registered, the agent's unique ID of the type {py:class}`~agnext.core.AgentId` \n",- "can be retrieved by calling {py:meth}`~agnext.core.AgentRuntime.get`.\n",- "Using the agent ID, we can send messages to the agent:"+ "Once an agent type is registered, we can send a direct message to an agent instance\n",+ "using an {py:class}`~agnext.core.AgentId`.\n",+ "The runtime will create the instance the first time it delivers a\n",+ "message to this instance."]},{@@ -154,13 +158,8 @@"cell_type": "markdown","metadata": {},"source": [- "There is a convenience method\n",- "{py:meth}`~agnext.core.AgentRuntime.register_and_get` that both registers an agent\n",- "and gets its ID.\n",- "\n","```{note}\n",- "Because the runtime manages the lifecycle of agents, a reference to an agent,\n",- "whether it is {py:class}`~agnext.core.AgentId` or {py:class}`~agnext.core.AgentProxy`,\n",+ "Because the runtime manages the lifecycle of agents, an {py:class}`~agnext.core.AgentId`\n","is only used to communicate with the agent or retrieve its metadata (e.g., description).\n","```"]diff --git a/python/docs/src/getting-started/message-and-communication.ipynb b/python/docs/src/getting-started/message-and-communication.ipynbindex a38204f1f..ae673173e 100644--- a/python/docs/src/getting-started/message-and-communication.ipynb+++ b/python/docs/src/getting-started/message-and-communication.ipynb@@ -27,7 +27,7 @@},{"cell_type": "code",- "execution_count": 2,+ "execution_count": 1,"metadata": {},"outputs": [],"source": [@@ -77,7 +77,7 @@},{"cell_type": "code",- "execution_count": 4,+ "execution_count": 2,"metadata": {},"outputs": [],"source": [@@ -100,18 +100,28 @@"cell_type": "markdown","metadata": {},"source": [- "Create the agent runtime and register the agent (see [Agent and Agent Runtime](agent-and-agent-runtime.ipynb)):"+ "Create the agent runtime and register the agent type (see [Agent and Agent Runtime](agent-and-agent-runtime.ipynb)):"]},{"cell_type": "code",- "execution_count": 6,+ "execution_count": 3,"metadata": {},- "outputs": [],+ "outputs": [+ {+ "data": {+ "text/plain": [+ "AgentType(type='my_agent')"+ ]+ },+ "execution_count": 3,+ "metadata": {},+ "output_type": "execute_result"+ }+ ],"source": ["runtime = SingleThreadedAgentRuntime()\n",- "await runtime.register(\"my_agent\", lambda: MyAgent(\"My Agent\"))\n",- "agent = AgentId(\"my_agent\", \"default\")"+ "await runtime.register(\"my_agent\", lambda: MyAgent(\"My Agent\"))"]},{@@ -123,7 +133,7 @@},{"cell_type": "code",- "execution_count": 7,+ "execution_count": 4,"metadata": {},"outputs": [{@@ -137,8 +147,9 @@],"source": ["runtime.start()\n",- "await runtime.send_message(TextMessage(content=\"Hello, World!\", source=\"User\"), agent)\n",- "await runtime.send_message(ImageMessage(url=\"https://example.com/image.jpg\", source=\"User\"), agent)\n",+ "agent_id = AgentId(\"my_agent\", \"default\")\n",+ "await runtime.send_message(TextMessage(content=\"Hello, World!\", source=\"User\"), agent_id)\n",+ "await runtime.send_message(ImageMessage(url=\"https://example.com/image.jpg\", source=\"User\"), agent_id)\n","await runtime.stop_when_idle()"]},@@ -146,39 +157,39 @@"cell_type": "markdown","metadata": {},"source": [- "## Communication\n",+ "## Direct Messaging\n","\n","There are two types of communication in AGNext:\n","\n",- "- **Direct communication**: An agent sends a direct message to another agent.\n",- "- **Broadcast communication**: An agent publishes a message to all agents in the same namespace.\n",- "\n",- "### Direct Communication\n",+ "- **Direct Messaging**: sends a direct message to another agent.\n",+ "- **Broadcast**: publishes a message to a topic.\n","\n",+ "Let's first look at direct messaging.\n","To send a direct message to another agent, within a message handler use\n","the {py:meth}`agnext.core.BaseAgent.send_message` method,\n","from the runtime use the {py:meth}`agnext.core.AgentRuntime.send_message` method.\n","Awaiting calls to these methods will return the return value of the\n","receiving agent's message handler.\n",+ "When the receiving agent's handler returns `None`, `None` will be returned.\n","\n","```{note}\n","If the invoked agent raises an exception while the sender is awaiting,\n","the exception will be propagated back to the sender.\n","```\n","\n",- "#### Request/Response\n",+ "### Request/Response\n","\n",- "Direct communication can be used for request/response scenarios,\n",+ "Direct messaging can be used for request/response scenarios,\n","where the sender expects a response from the receiver.\n","The receiver can respond to the message by returning a value from its message handler.\n","You can think of this as a function call between agents.\n","\n",- "For example, consider the following type-routed agent:"+ "For example, consider the following agents:"]},{"cell_type": "code",- "execution_count": 17,+ "execution_count": 5,"metadata": {},"outputs": [],"source": [@@ -225,7 +236,7 @@},{"cell_type": "code",- "execution_count": 18,+ "execution_count": 6,"metadata": {},"outputs": [{@@ -240,7 +251,7 @@"source": ["runtime = SingleThreadedAgentRuntime()\n","await runtime.register(\"inner_agent\", lambda: InnerAgent(\"InnerAgent\"))\n",- "await runtime.register(\"outer_agent\", lambda: OuterAgent(\"OuterAgent\", \"InnerAgent\"))\n",+ "await runtime.register(\"outer_agent\", lambda: OuterAgent(\"OuterAgent\", \"inner_agent\"))\n","runtime.start()\n","outer = AgentId(\"outer_agent\", \"default\")\n","await runtime.send_message(Message(content=\"Hello, World!\"), outer)\n",@@ -251,59 +262,75 @@"cell_type": "markdown","metadata": {},"source": [- "Both outputs are produced by the `OuterAgent`'s message handler, however the second output is based on the response from the `InnerAgent`."+ "Both outputs are produced by the `OuterAgent`'s message handler, however the second output is based on the response from the `InnerAgent`.\n",+ "\n",+ "Generally speaking, direct messaging is appropriate for scenarios when the sender and\n",+ "recipient are tightly coupled -- they are created together and the sender\n",+ "is linked to a specific instance of the recipient.\n",+ "For example, an agent executes tool calls by sending direct messages to\n",+ "an instance of {py:class}`~agnext.components.tool_agent.ToolAgent`,\n",+ "and uses the responses to form an action-observation loop."]},{"cell_type": "markdown","metadata": {},"source": [- "### Broadcast Communication\n",+ "## Broadcast\n","\n",- "Broadcast communication is effectively the publish/subscribe model.\n",- "As part of the base agent ({py:class}`~agnext.core.BaseAgent`) implementation,\n",- "it must advertise the message types that\n",- "it would like to receive when published ({py:attr}`~agnext.core.AgentMetadata.subscriptions`).\n",- "If one of these messages is published, the agent's message handler will be invoked.\n",+ "Broadcast is effectively the publish/subscribe model with topic and subscription.\n",+ "Read [Topic and Subscription](../core-concepts/topic-and-subscription.md)\n",+ "to learn the core concepts.\n","\n",- "The key difference between direct and broadcast communication is that broadcast\n",- "communication cannot be used for request/response scenarios.\n",+ "The key difference between direct messaging and broadcast is that broadcast\n",+ "cannot be used for request/response scenarios.\n","When an agent publishes a message it is one way only, it cannot receive a response\n",- "from any other agent, even if a receiving agent sends a response.\n",+ "from any other agent, even if a receiving agent's handler returns a value.\n","\n","```{note}\n",- "An agent receiving a message does not know if it is handling a published or direct message.\n",- "So, if a response is given to a published message, it will be thrown away.\n",+ "If a response is given to a published message, it will be thrown away.\n",+ "```\n",+ "\n",+ "```{note}\n",+ "If an agent publishes a message type for which it is subscribed it will not\n",+ "receive the message it published. This is to prevent infinite loops.\n","```\n","\n",- "To publish a message to all agents in the same namespace,\n",- "use the {py:meth}`agnext.core.BaseAgent.publish_message` method.\n",- "This call must still be awaited to allow the runtime to deliver the message to all agents,\n",+ "### Publishing to Topics\n",+ "\n",+ "To publish a message from an agent's handler,\n",+ "use the {py:meth}`agnext.core.BaseAgent.publish_message` method and specify\n",+ "a {py:class}`agnext.core.TopicId`.\n",+ "This call must still be awaited to allow the runtime to schedule delivery of \n",+ "the message to all subscribers,\n","but it will always return `None`.\n","If an agent raises an exception while handling a published message,\n","this will be logged but will not be propagated back to the publishing agent.\n","\n","The following example shows a `BroadcastingAgent` that publishes a message\n",- "upong receiving a message. A `ReceivingAgent` that prints the message\n",- "it receives."+ "to a topic upon receiving a message. A `ReceivingAgent` subscribes to the topic\n",+ "and prints the message it receives."]},{"cell_type": "code",- "execution_count": 20,+ "execution_count": 7,"metadata": {},"outputs": [],"source": ["from agnext.application import SingleThreadedAgentRuntime\n",- "from agnext.components import DefaultSubscription, DefaultTopicId, RoutedAgent, message_handler\n",- "from agnext.core import MessageContext\n",+ "from agnext.components import RoutedAgent, message_handler\n",+ "from agnext.core import MessageContext, TopicId\n","\n","\n","class BroadcastingAgent(RoutedAgent):\n"," @message_handler\n"," async def on_my_message(self, message: Message, ctx: MessageContext) -> None:\n"," # Publish a message to all agents in the same namespace.\n",- " await self.publish_message(Message(f\"Publishing a message: {message.content}!\"), topic_id=DefaultTopicId())\n",+ " await self.publish_message(\n",+ " Message(f\"Publishing a message: {message.content}!\"),\n",+ " topic_id=TopicId(type=\"default\", source=self.id.key),\n",+ " )\n","\n","\n","class ReceivingAgent(RoutedAgent):\n",@@ -316,67 +343,154 @@"cell_type": "markdown","metadata": {},"source": [- "Sending a direct message to the `BroadcastingAgent` will result in a message being published by\n",- "the `BroadcastingAgent` and received by the `ReceivingAgent`."+ "`BroadcastingAgent` publishes message to a topic with type `\"default\"`\n",+ "and source assigned to the agent instance's agent key.\n",+ "\n",+ "Next, we specify the a subscription for this topic so the receiving agent\n",+ "can get message from the broadcasting agent."+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "### Registering Subscriptions\n",+ "\n",+ "Subscriptions are registered with the agent runtime, either as part of\n",+ "agent type's registeration or through a separate API method.\n",+ "\n",+ "Here is how we can register {py:class}`~agnext.components.TypeSubscription`\n",+ "for the broadcasting agent and receiving agent."]},{"cell_type": "code",- "execution_count": 21,+ "execution_count": 8,"metadata": {},"outputs": [{"name": "stdout","output_type": "stream","text": [- "Received a message: Publishing a message: Hello, World!!\n"+ "Received a message: Publishing a message: Hello, World! From the runtime!!\n"]}],"source": [+ "from agnext.components import TypeSubscription\n",+ "\n","runtime = SingleThreadedAgentRuntime()\n",+ "\n",+ "# Registering subscription as part of the `register` method, by providing\n",+ "# a factory function that produces a list of subscriptions.\n","await runtime.register(\n",- " \"broadcasting_agent\", lambda: BroadcastingAgent(\"Broadcasting Agent\"), lambda: [DefaultSubscription()]\n",+ " \"broadcasting_agent\",\n",+ " lambda: BroadcastingAgent(\"Broadcasting Agent\"),\n",+ " subscriptions=lambda: [TypeSubscription(topic_type=\"default\", agent_type=\"broadcasting_agent\")],\n",")\n",- "await runtime.register(\"receiving_agent\", lambda: ReceivingAgent(\"Receiving Agent\"), lambda: [DefaultSubscription()])\n",+ "\n",+ "await runtime.register(\"receiving_agent\", lambda: ReceivingAgent(\"Receiving Agent\"))\n",+ "\n",+ "# Registering subscription directly with the runtime.\n",+ "await runtime.add_subscription(TypeSubscription(topic_type=\"default\", agent_type=\"receiving_agent\"))\n",+ "\n",+ "# Start the runtime and send a message to a broadcasting agent.\n","runtime.start()\n",- "await runtime.send_message(Message(\"Hello, World!\"), AgentId(\"broadcasting_agent\", \"default\"))\n",- "await runtime.stop()"+ "await runtime.send_message(\n",+ " Message(\"Hello, World! From the runtime!\"), recipient=AgentId(\"broadcasting_agent\", \"default\")\n",+ ")\n",+ "await runtime.stop_when_idle()"+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "From the output, you can see the broadcasting agent published\n",+ "a message, and the message was received by the receiving agent."+ ]+ },+ {+ "cell_type": "markdown",+ "metadata": {},+ "source": [+ "### Default Topic and Subscriptions\n",+ "\n",+ "In the above example, we used\n",+ "{py:class}`~agnext.core.TopicId` and {py:class}`~agnext.components.TypeSubscription`\n",+ "to specify the topic and subscriptions respectively.\n",+ "This is the appropriate way for many scenarios.\n",+ "However, when there is a single scope of publishing, that is, \n",+ "all agents publish and subscribe to all broadcasted messages,\n",+ "we can use the convenience classes {py:class}`~agnext.components.DefaultTopicId`\n",+ "and {py:class}`~agnext.components.DefaultSubscription` to simply our code.\n",+ "\n",+ "{py:class}`~agnext.components.DefaultTopicId` is\n",+ "for creating a topic that uses `\"default\"` as the default value for the topic type\n",+ "and the publishing agent's key as the default value for the topic source.\n",+ "We can simplify `BroadcastingAgent` by using \n",+ "{py:class}`~agnext.components.DefaultTopicId`."+ ]+ },+ {+ "cell_type": "code",+ "execution_count": 9,+ "metadata": {},+ "outputs": [],+ "source": [+ "from agnext.components import DefaultSubscription, DefaultTopicId\n",+ "\n",+ "\n",+ "class BroadcastingAgentDefaultTopic(RoutedAgent):\n",+ " @message_handler\n",+ " async def on_my_message(self, message: Message, ctx: MessageContext) -> None:\n",+ " # Publish a message to all agents in the same namespace.\n",+ " await self.publish_message(\n",+ " Message(f\"Publishing a message: {message.content}!\"),\n",+ " topic_id=DefaultTopicId(),\n",+ " )"]},{"cell_type": "markdown","metadata": {},"source": [- "To publish a message to all agents outside of an agent handling a message,\n",- "the message should be published via the runtime with the\n",- "{py:meth}`agnext.core.AgentRuntime.publish_message` method."+ "We can also simplify subscription using\n",+ "{py:class}`~agnext.components.DefaultSubscription`\n",+ "when registering it as part of agent type registration.\n",+ "\n",+ "When the runtime calls {py:class}`~agnext.components.DefaultSubscription` in\n",+ "the context of the factory function, \n",+ "it creates a {py:class}`~agnext.components.TypeSubscription`\n",+ "whose topic type uses `\"default\"` as the default value and \n",+ "agent type uses the same agent type that is being registered in the same context."]},{"cell_type": "code",- "execution_count": 22,+ "execution_count": 10,"metadata": {},"outputs": [{"name": "stdout","output_type": "stream","text": [- "Received a message: Hello, World! From the runtime!\n","Received a message: Publishing a message: Hello, World! From the runtime!!\n"]}],"source": [- "# Replace send_message with publish_message in the above example.\n",- "\n","runtime = SingleThreadedAgentRuntime()\n","await runtime.register(\n",- " \"broadcasting_agent\", lambda: BroadcastingAgent(\"Broadcasting Agent\"), lambda: [DefaultSubscription()]\n",+ " \"broadcasting_agent\",\n",+ " lambda: BroadcastingAgentDefaultTopic(\"Broadcasting Agent\"),\n",+ " subscriptions=lambda: [DefaultSubscription()],\n",")\n","await runtime.register(\"receiving_agent\", lambda: ReceivingAgent(\"Receiving Agent\"), lambda: [DefaultSubscription()])\n","runtime.start()\n",- "await runtime.publish_message(Message(\"Hello, World! From the runtime!\"), topic_id=DefaultTopicId())\n",+ "await runtime.send_message(\n",+ " Message(\"Hello, World! From the runtime!\"), recipient=AgentId(\"broadcasting_agent\", \"default\")\n",+ ")\n","await runtime.stop_when_idle()"]},@@ -384,13 +498,11 @@"cell_type": "markdown","metadata": {},"source": [- "The first output is from the `ReceivingAgent` that received a message published\n",- "by the runtime. The second output is from the `ReceivingAgent` that received\n",- "a message published by the `BroadcastingAgent`.\n",- "\n","```{note}\n",- "If an agent publishes a message type for which it is subscribed it will not\n",- "receive the message it published. This is to prevent infinite loops.\n",+ "If your scenario allows all agents to publish and subscribe to\n",+ "all broadcasted messages, use {py:class}`~agnext.components.DefaultTopicId`\n",+ "and {py:class}`~agnext.components.DefaultSubscription` without setting its\n",+ "parameters.\n","```"]}diff --git a/python/docs/src/getting-started/reflection.ipynb b/python/docs/src/getting-started/reflection.ipynbindex a427a8421..3a783fac0 100644--- a/python/docs/src/getting-started/reflection.ipynb+++ b/python/docs/src/getting-started/reflection.ipynb@@ -115,7 +115,7 @@"cell_type": "markdown","metadata": {},"source": [- "We use the [Broadcast Communication](./message-and-communication.ipynb#broadcast-communication) API\n",+ "We use the [Broadcast](./message-and-communication.ipynb#broadcast) API\n","to implement the design pattern. The agents implements the pub/sub model.\n","The coder agent subscribes to the `CodeWritingTask` and `CodeReviewResult` messages,\n","and publishes the `CodeReviewTask` and `CodeWritingResult` messages."diff --git a/python/docs/src/index.rst b/python/docs/src/index.rstindex f25bd3cb8..41ffecd87 100644--- a/python/docs/src/index.rst+++ b/python/docs/src/index.rst@@ -9,15 +9,21 @@ You can implement agents indifferent programming languages and deploy them on different machines across organizational boundaries.You can also implement agents using other agent frameworks and run them in AGNext.-To start quickly, read the `quick start <getting-started/quickstart.html>`_.+To start quickly, read the `Quick Start <getting-started/quickstart.html>`_ and+follow the tutorial sections.-To learn about the core concepts of AGNext, read the `overview <core-concepts/overview.html>`_.+To learn about the core concepts of AGNext, read the sections starting+from `Agent and Multi-Agent Application <core-concepts/agent-and-multi-agent-application.html>`_... toctree:::caption: Core Concepts:hidden:- core-concepts/overview+ core-concepts/agent-and-multi-agent-application+ core-concepts/architecture+ core-concepts/application-stack+ core-concepts/agent-identity-and-lifecycle+ core-concepts/topic-and-subscription.. toctree:::caption: Getting started