Skip to content

A programming framework for agentic AI

Use notebook for extract result cookbook, use updated API. (#487)

Eric Zhu76067a62c056
diff --git a/python/packages/autogen-core/docs/src/cookbook/extracting-results-with-an-agent.ipynb b/python/packages/autogen-core/docs/src/cookbook/extracting-results-with-an-agent.ipynb
new file mode 100644
index 000000000..3094db49e
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/cookbook/extracting-results-with-an-agent.ipynb
@@ -0,0 +1,185 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Extracting Results with an Agent\n",
+ "\n",
+ "When running a multi-agent system to solve some task, you may want to extract the result of the system once it has reached termination. This guide showcases one way to achieve this. Given that agent instances are not directly accessible from the outside, we will use an agent to publish the final result to an accessible location.\n",
+ "\n",
+ "If you model your system to publish some `FinalResult` type then you can create an agent whose sole job is to subscribe to this and make it available externally. For simple agents like this the {py:class}`~autogen_core.components.ClosureAgent` is an option to reduce the amount of boilerplate code. This allows you to define a function that will be associated as the agent's message handler. In this example, we're going to use a queue shared between the agent and the external code to pass the result.\n",
+ "\n",
+ "```{note}\n",
+ "When considering how to extract results from a multi-agent system, you must always consider the subscriptions of the agent and the topics they publish to.\n",
+ "This is because the agent will only receive messages from topics it is subscribed to.\n",
+ "```"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 36,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import asyncio\n",
+ "from dataclasses import dataclass\n",
+ "\n",
+ "from autogen_core.application import SingleThreadedAgentRuntime\n",
+ "from autogen_core.base import AgentRuntime, AgentId, MessageContext\n",
+ "from autogen_core.components import ClosureAgent, DefaultSubscription, DefaultTopicId"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Define a dataclass for the final result."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 37,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "@dataclass\n",
+ "class FinalResult:\n",
+ " value: str"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Create a queue to pass the result from the agent to the external code."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 38,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "queue = asyncio.Queue[FinalResult]()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Create a function closure for outputting the final result to the queue.\n",
+ "The function must follow the signature\n",
+ "`Callable[[AgentRuntime, AgentId, T, MessageContext], Awaitable[Any]]`\n",
+ "where `T` is the type of the message the agent will receive.\n",
+ "You can use union types to handle multiple message types."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 39,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "async def output_result(_runtime: AgentRuntime, id: AgentId, message: FinalResult, ctx: MessageContext) -> None:\n",
+ " await queue.put(message)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Let's create a runtime and register a {py:class}`~autogen_core.components.ClosureAgent` that will publish the final result to the queue."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 40,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "AgentType(type='output_result')"
+ ]
+ },
+ "execution_count": 40,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "runtime = SingleThreadedAgentRuntime()\n",
+ "await runtime.register(\n",
+ " \"output_result\", lambda: ClosureAgent(\"An output agent\", output_result), lambda: [DefaultSubscription()]\n",
+ ")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We can simulate the collection of final results by publishing them directly to the runtime."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 41,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "runtime.start()\n",
+ "await runtime.publish_message(FinalResult(\"Result 1\"), DefaultTopicId())\n",
+ "await runtime.publish_message(FinalResult(\"Result 2\"), DefaultTopicId())\n",
+ "await runtime.stop_when_idle()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We can take a look at the queue to see the final result."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 42,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Result 1\n",
+ "Result 2\n"
+ ]
+ }
+ ],
+ "source": [
+ "while not queue.empty():\n",
+ " print((result := await queue.get()).value)"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": ".venv",
+ "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
+}
diff --git a/python/packages/autogen-core/docs/src/cookbook/extracting-results-with-an-agent.md b/python/packages/autogen-core/docs/src/cookbook/extracting-results-with-an-agent.md
deleted file mode 100644
index 4a12b7123..000000000
--- a/python/packages/autogen-core/docs/src/cookbook/extracting-results-with-an-agent.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Extracting Results with an Agent
-
-When running a multi-agent system to solve some task, you may want to extract the result of the system once it has reached termination. This guide showcases one way to achieve this. Given that agent instances are not directly accessible from the outside, we will use an agent to publish the final result to an accessible location.
-
-If you model your system to publish some `FinalResult` type then you can create an agent whose sole job is to subscribe to this and make it available externally. For simple agents like this the {py:class}`~autogen_core.components.ClosureAgent` is an option to reduce the amount of boilerplate code. This allows you to define a function that will be associated as the agent's message handler. In this example, we're going to use a queue shared between the agent and the external code to pass the result.
-
-```{note}
-When considering how to extract results from a multi-agent system, you must always consider the namespace of the agent and by extension the message.
-```
-
-```python
-from autogen_core.application import SingleThreadedAgentRuntime
-from autogen_core.base import AgentRuntime, AgentId, CancellationToken
-from autogen_core.components import ClosureAgent
-
-import asyncio
-
-@dataclass
-class FinalResult:
- result: str
-
-# ...
-
-queue = asyncio.Queue[tuple[str, FinalResult]]()
-
-async def output_result(_runtime: AgentRuntime, id: AgentId, message: FinalResult, cancellation_token: CancellationToken) -> None:
- namespace = id.namespace
- await queue.put((namespace, FinalResult))
-
-runtime.register("OutputResult", lambda: ClosureAgent("Outputs messages", output_result))
-
-# ...
-```
-
-When using a `ClosureAgent` the third parameter, named `message` in this example determines what messages are subscribed to. In this case, the agent will only receive messages of type `FinalResult`. This can also be a union of types if you want to subscribe to multiple types of messages.