Skip to content

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.
+
+![AGNext Application Stack](agnext-application-stack.svg)
+
+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.
+
+![Code Generation Example](agnext-code-gen-example.svg)
+
+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.md
new file mode 100644
index 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.
+
+![AGNext Runtime](agnext-architecture.svg)
+
+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.
+
+![AGNext Layers](agnext-layers.svg)
+
+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.md
deleted file mode 100644
index 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.
-
-![AGNext Runtime](agnext-architecture.svg)
-
-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.
-
-![AGNext Layers](agnext-layers.svg)
-
-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.
-
-![AGNext Application Stack](agnext-application-stack.svg)
-
-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.
-
-![Code Generation Example](agnext-code-gen-example.svg)
-
-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.md
new file mode 100644
index 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.ipynb
index 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.ipynb
index 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.ipynb
index 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.rst
index f25bd3cb8..41ffecd87 100644
--- a/python/docs/src/index.rst
+++ b/python/docs/src/index.rst
@@ -9,15 +9,21 @@ You can implement agents in
different 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