mirror of
https://github.com/microsoft/autogen.git
synced 2025-12-27 15:09:41 +00:00
Fix documentation bug (#438)
This commit is contained in:
Eric Zhu
GitHub
parent
a51b793667
commit
479d5fa9d1
@ -1,262 +1,262 @@
|
||||
{
|
||||
"cells": [
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"# Agent and Agent Runtime\n",
|
||||
"\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."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"An agent in AGNext is an entity defined by the base class {py:class}`autogen_core.base.BaseAgent`.\n",
|
||||
"It has a unique identifier of the type {py:class}`autogen_core.base.AgentId`,\n",
|
||||
"a metadata dictionary of the type {py:class}`autogen_core.base.AgentMetadata`,\n",
|
||||
"and method for handling messages {py:meth}`autogen_core.base.BaseAgent.on_message`.\n",
|
||||
"\n",
|
||||
"An agent runtime is the execution environment for agents in AGNext.\n",
|
||||
"Similar to the runtime environment of a programming language,\n",
|
||||
"an agent runtime provides the necessary infrastructure to facilitate communication\n",
|
||||
"between agents, manage agent lifecycles, enforce security boundaries, and support monitoring and\n",
|
||||
"debugging.\n",
|
||||
"For local development, developers can use {py:class}`~autogen_core.application.SingleThreadedAgentRuntime`,\n",
|
||||
"which can be embedded in a Python application.\n",
|
||||
"\n",
|
||||
"```{note}\n",
|
||||
"Agents are not directly instantiated and managed by application code.\n",
|
||||
"Instead, they are created by the runtime when needed and managed by the runtime.\n",
|
||||
"```"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Implementing an Agent\n",
|
||||
"\n",
|
||||
"To implement an agent, developer must subclass the {py:class}`~autogen_core.base.BaseAgent` class,\n",
|
||||
"declare the message types it can handle in the {py:attr}`~autogen_core.base.AgentMetadata.subscriptions` metadata,\n",
|
||||
"and implement the {py:meth}`~autogen_core.base.BaseAgent.on_message` method.\n",
|
||||
"This method is invoked when the agent receives a message. For example,\n",
|
||||
"the following agent handles a simple message type and simply prints message it receives:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 1,
|
||||
"metadata": {},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"from dataclasses import dataclass\n",
|
||||
"\n",
|
||||
"from autogen_core.base import AgentId, BaseAgent, MessageContext\n",
|
||||
"\n",
|
||||
"\n",
|
||||
"@dataclass\n",
|
||||
"class MyMessage:\n",
|
||||
" content: str\n",
|
||||
"\n",
|
||||
"\n",
|
||||
"class MyAgent(BaseAgent):\n",
|
||||
" def __init__(self) -> None:\n",
|
||||
" super().__init__(\"MyAgent\")\n",
|
||||
"\n",
|
||||
" async def on_message(self, message: MyMessage, ctx: MessageContext) -> None:\n",
|
||||
" print(f\"Received message: {message.content}\")"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"For convenience, developers can subclass the {py:class}`~autogen_core.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."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Registering Agent Type\n",
|
||||
"\n",
|
||||
"To make agents available to the runtime, developers can use the\n",
|
||||
"{py:meth}`~autogen_core.base.AgentRuntime.register` method.\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 type with the \n",
|
||||
"{py:class}`~autogen_core.application.SingleThreadedAgentRuntime`,\n",
|
||||
"the following code can be used:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 2,
|
||||
"metadata": {},
|
||||
"outputs": [
|
||||
{
|
||||
"data": {
|
||||
"text/plain": [
|
||||
"AgentType(type='my_agent')"
|
||||
]
|
||||
},
|
||||
"execution_count": 2,
|
||||
"metadata": {},
|
||||
"output_type": "execute_result"
|
||||
}
|
||||
],
|
||||
"source": [
|
||||
"from autogen_core.application import SingleThreadedAgentRuntime\n",
|
||||
"\n",
|
||||
"runtime = SingleThreadedAgentRuntime()\n",
|
||||
"await runtime.register(\"my_agent\", lambda: MyAgent())"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Once an agent type is registered, we can send a direct message to an agent instance\n",
|
||||
"using an {py:class}`~autogen_core.base.AgentId`.\n",
|
||||
"The runtime will create the instance the first time it delivers a\n",
|
||||
"message to this instance."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 3,
|
||||
"metadata": {},
|
||||
"outputs": [
|
||||
{
|
||||
"name": "stdout",
|
||||
"output_type": "stream",
|
||||
"text": [
|
||||
"Received message: Hello, World!\n"
|
||||
]
|
||||
}
|
||||
],
|
||||
"source": [
|
||||
"agent_id = AgentId(\"my_agent\", \"default\")\n",
|
||||
"runtime.start() # Start processing messages in the background.\n",
|
||||
"await runtime.send_message(MyMessage(content=\"Hello, World!\"), agent_id)\n",
|
||||
"await runtime.stop() # Stop processing messages in the background."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"```{note}\n",
|
||||
"Because the runtime manages the lifecycle of agents, an {py:class}`~autogen_core.base.AgentId`\n",
|
||||
"is only used to communicate with the agent or retrieve its metadata (e.g., description).\n",
|
||||
"```"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Running the Single-Threaded Agent Runtime\n",
|
||||
"\n",
|
||||
"The above code snippet uses `runtime.start()` to start a background task\n",
|
||||
"to process and deliver messages to recepients' message handlers.\n",
|
||||
"This is a feature of the\n",
|
||||
"local embedded runtime {py:class}`~autogen_core.application.SingleThreadedAgentRuntime`.\n",
|
||||
"\n",
|
||||
"To stop the background task immediately, use the `stop()` method:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 4,
|
||||
"metadata": {},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"runtime.start()\n",
|
||||
"# ... Send messages, publish messages, etc.\n",
|
||||
"await runtime.stop() # This will return immediately but will not cancel\n",
|
||||
"# any in-progress message handling."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"You can resume the background task by calling `start()` again.\n",
|
||||
"\n",
|
||||
"For batch scenarios such as running benchmarks for evaluating agents,\n",
|
||||
"you may want to wait for the background task to stop automatically when\n",
|
||||
"there are no unprocessed messages and no agent is handling messages --\n",
|
||||
"the batch may considered complete.\n",
|
||||
"You can achieve this by using the `stop_when_idle()` method:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 5,
|
||||
"metadata": {},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"runtime.start()\n",
|
||||
"# ... Send messages, publish messages, etc.\n",
|
||||
"await runtime.stop_when_idle() # This will block until the runtime is idle."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"You can also directly process messages one-by-one without a background task using:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 6,
|
||||
"metadata": {},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"await runtime.process_next()"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Other runtime implementations will have their own ways of running the runtime."
|
||||
]
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"kernelspec": {
|
||||
"display_name": "autogen_core",
|
||||
"language": "python",
|
||||
"name": "python3"
|
||||
},
|
||||
"language_info": {
|
||||
"codemirror_mode": {
|
||||
"name": "ipython",
|
||||
"version": 3
|
||||
},
|
||||
"file_extension": ".py",
|
||||
"mimetype": "text/x-python",
|
||||
"name": "python",
|
||||
"nbconvert_exporter": "python",
|
||||
"pygments_lexer": "ipython3",
|
||||
"version": "3.11.9"
|
||||
}
|
||||
},
|
||||
"nbformat": 4,
|
||||
"nbformat_minor": 2
|
||||
"cells": [
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"# Agent and Agent Runtime\n",
|
||||
"\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."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"An agent in AGNext is an entity defined by the base class {py:class}`autogen_core.base.BaseAgent`.\n",
|
||||
"It has a unique identifier of the type {py:class}`autogen_core.base.AgentId`,\n",
|
||||
"a metadata dictionary of the type {py:class}`autogen_core.base.AgentMetadata`,\n",
|
||||
"and method for handling messages {py:meth}`autogen_core.base.BaseAgent.on_message`.\n",
|
||||
"\n",
|
||||
"An agent runtime is the execution environment for agents in AGNext.\n",
|
||||
"Similar to the runtime environment of a programming language,\n",
|
||||
"an agent runtime provides the necessary infrastructure to facilitate communication\n",
|
||||
"between agents, manage agent lifecycles, enforce security boundaries, and support monitoring and\n",
|
||||
"debugging.\n",
|
||||
"For local development, developers can use {py:class}`~autogen_core.application.SingleThreadedAgentRuntime`,\n",
|
||||
"which can be embedded in a Python application.\n",
|
||||
"\n",
|
||||
"```{note}\n",
|
||||
"Agents are not directly instantiated and managed by application code.\n",
|
||||
"Instead, they are created by the runtime when needed and managed by the runtime.\n",
|
||||
"```"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Implementing an Agent\n",
|
||||
"\n",
|
||||
"To implement an agent, developer must subclass the {py:class}`~autogen_core.base.BaseAgent` class\n",
|
||||
"and implement the {py:meth}`~autogen_core.base.BaseAgent.on_message` method.\n",
|
||||
"This method is invoked when the agent receives a message. For example,\n",
|
||||
"the following agent handles a simple message type and simply prints message it receives:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 1,
|
||||
"metadata": {},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"from dataclasses import dataclass\n",
|
||||
"\n",
|
||||
"from autogen_core.base import AgentId, BaseAgent, MessageContext\n",
|
||||
"\n",
|
||||
"\n",
|
||||
"@dataclass\n",
|
||||
"class MyMessageType:\n",
|
||||
" content: str\n",
|
||||
"\n",
|
||||
"\n",
|
||||
"class MyAgent(BaseAgent):\n",
|
||||
" def __init__(self) -> None:\n",
|
||||
" super().__init__(\"MyAgent\")\n",
|
||||
"\n",
|
||||
" async def on_message(self, message: MyMessageType, ctx: MessageContext) -> None:\n",
|
||||
" print(f\"Received message: {message.content}\") # type: ignore"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"This agent only handles `MyMessageType` messages. \n",
|
||||
"To handle multiple message types, developers can subclass the {py:class}`~autogen_core.components.RoutedAgent` class\n",
|
||||
"which provides an easy-to use API to implement different message handlers for different message types.\n",
|
||||
"See the next section on [message and communication](./message-and-communication.ipynb)."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Registering Agent Type\n",
|
||||
"\n",
|
||||
"To make agents available to the runtime, developers can use the\n",
|
||||
"{py:meth}`~autogen_core.base.AgentRuntime.register` method.\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 type with the \n",
|
||||
"{py:class}`~autogen_core.application.SingleThreadedAgentRuntime`,\n",
|
||||
"the following code can be used:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 2,
|
||||
"metadata": {},
|
||||
"outputs": [
|
||||
{
|
||||
"data": {
|
||||
"text/plain": [
|
||||
"AgentType(type='my_agent')"
|
||||
]
|
||||
},
|
||||
"execution_count": 2,
|
||||
"metadata": {},
|
||||
"output_type": "execute_result"
|
||||
}
|
||||
],
|
||||
"source": [
|
||||
"from autogen_core.application import SingleThreadedAgentRuntime\n",
|
||||
"\n",
|
||||
"runtime = SingleThreadedAgentRuntime()\n",
|
||||
"await runtime.register(\"my_agent\", lambda: MyAgent())"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Once an agent type is registered, we can send a direct message to an agent instance\n",
|
||||
"using an {py:class}`~autogen_core.base.AgentId`.\n",
|
||||
"The runtime will create the instance the first time it delivers a\n",
|
||||
"message to this instance."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 3,
|
||||
"metadata": {},
|
||||
"outputs": [
|
||||
{
|
||||
"name": "stdout",
|
||||
"output_type": "stream",
|
||||
"text": [
|
||||
"Received message: Hello, World!\n"
|
||||
]
|
||||
}
|
||||
],
|
||||
"source": [
|
||||
"agent_id = AgentId(\"my_agent\", \"default\")\n",
|
||||
"runtime.start() # Start processing messages in the background.\n",
|
||||
"await runtime.send_message(MyMessageType(\"Hello, World!\"), agent_id)\n",
|
||||
"await runtime.stop() # Stop processing messages in the background."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"```{note}\n",
|
||||
"Because the runtime manages the lifecycle of agents, an {py:class}`~autogen_core.base.AgentId`\n",
|
||||
"is only used to communicate with the agent or retrieve its metadata (e.g., description).\n",
|
||||
"```"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Running the Single-Threaded Agent Runtime\n",
|
||||
"\n",
|
||||
"The above code snippet uses `runtime.start()` to start a background task\n",
|
||||
"to process and deliver messages to recepients' message handlers.\n",
|
||||
"This is a feature of the\n",
|
||||
"local embedded runtime {py:class}`~autogen_core.application.SingleThreadedAgentRuntime`.\n",
|
||||
"\n",
|
||||
"To stop the background task immediately, use the `stop()` method:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 4,
|
||||
"metadata": {},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"runtime.start()\n",
|
||||
"# ... Send messages, publish messages, etc.\n",
|
||||
"await runtime.stop() # This will return immediately but will not cancel\n",
|
||||
"# any in-progress message handling."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"You can resume the background task by calling `start()` again.\n",
|
||||
"\n",
|
||||
"For batch scenarios such as running benchmarks for evaluating agents,\n",
|
||||
"you may want to wait for the background task to stop automatically when\n",
|
||||
"there are no unprocessed messages and no agent is handling messages --\n",
|
||||
"the batch may considered complete.\n",
|
||||
"You can achieve this by using the `stop_when_idle()` method:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 5,
|
||||
"metadata": {},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"runtime.start()\n",
|
||||
"# ... Send messages, publish messages, etc.\n",
|
||||
"await runtime.stop_when_idle() # This will block until the runtime is idle."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"You can also directly process messages one-by-one without a background task using:"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 6,
|
||||
"metadata": {},
|
||||
"outputs": [],
|
||||
"source": [
|
||||
"await runtime.process_next()"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"Other runtime implementations will have their own ways of running the runtime."
|
||||
]
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"kernelspec": {
|
||||
"display_name": "autogen_core",
|
||||
"language": "python",
|
||||
"name": "python3"
|
||||
},
|
||||
"language_info": {
|
||||
"codemirror_mode": {
|
||||
"name": "ipython",
|
||||
"version": 3
|
||||
},
|
||||
"file_extension": ".py",
|
||||
"mimetype": "text/x-python",
|
||||
"name": "python",
|
||||
"nbconvert_exporter": "python",
|
||||
"pygments_lexer": "ipython3",
|
||||
"version": "3.11.9"
|
||||
}
|
||||
},
|
||||
"nbformat": 4,
|
||||
"nbformat_minor": 2
|
||||
}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user