Skip to content

Building AI agents, atomically

Fix broken Colab link in quickstart notebook Add orchestrator tutorial

KennyVaneetveldef13d5025a611
diff --git a/examples/notebooks/orchestrator.ipynb b/examples/notebooks/orchestrator.ipynb
new file mode 100644
index 0000000..a47dd7f
--- /dev/null
+++ b/examples/notebooks/orchestrator.ipynb
@@ -0,0 +1,264 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Orchestrator Agent Tutorial\n",
+ "\n",
+ "This tutorial demonstrates how to create an orchestrator agent using the Atomic Agents library. The orchestrator agent will manage tasks and respond to user inputs in rhyming verse.\n",
+ "\n",
+ "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KennyVaneetvelde/atomic_agents/blob/main/examples/notebooks/orchestrator.ipynb#)\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Prerequisites\n",
+ "\n",
+ "Before proceeding with this notebook, it is highly recommended to read up on the basics of the following libraries:\n",
+ "\n",
+ "- **Pydantic**: A data validation and settings management library using Python type annotations. You can find more information and documentation at [Pydantic GitHub](https://github.com/pydantic/pydantic).\n",
+ "- **Instructor**: A Python library that simplifies working with structured outputs from large language models (LLMs). It provides a user-friendly API to manage validation, retries, and streaming responses. More details can be found at [Instructor GitHub](https://github.com/jxnl/instructor).\n",
+ "\n",
+ "Understanding these libraries will help you make the most of this library.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Step 1: Install Necessary Packages\n",
+ "\n",
+ "First, we need to install the required packages. Run the following command to install `atomic-agents`, `openai`, and `instructor` libraries."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# Install necessary packages\n",
+ "%pip install atomic-agents openai instructor"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Step 2: Import Libraries\n",
+ "\n",
+ "We will import the necessary libraries for creating the orchestrator agent. Each library serves a specific purpose:\n",
+ "- `ChatMemory`: Manages the chat history.\n",
+ "- `BaseChatAgent`: The base class to create a custom chatbot. Can be extended for additional functionality if needed.\n",
+ "- `SystemPromptGenerator` and `SystemPromptInfo`: To define and generate system prompts.\n",
+ "- `BaseTool`, `CalculatorTool`, `SearxNGSearchTool`: Tools that the orchestrator agent can use to perform tasks."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "from typing import List, Type, Union\n",
+ "from pydantic import BaseModel, Field\n",
+ "from rich.console import Console\n",
+ "from atomic_agents.lib.components.chat_memory import ChatMemory\n",
+ "from atomic_agents.agents.base_chat_agent import BaseChatAgent, BaseChatAgentResponse\n",
+ "from atomic_agents.lib.components.system_prompt_generator import SystemPromptContextProviderBase, SystemPromptGenerator, SystemPromptInfo\n",
+ "import instructor\n",
+ "import openai\n",
+ "from atomic_agents.lib.tools.base import BaseTool\n",
+ "from atomic_agents.lib.tools.calculator_tool import CalculatorTool, CalculatorToolSchema\n",
+ "from atomic_agents.lib.tools.search.searx_tool import SearxNGSearchTool, SearxNGSearchToolConfig, SearxNGSearchToolSchema"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Step 3: Define System Prompt Information\n",
+ "\n",
+ "We will define the system prompt information including background, steps, and output instructions. This helps the orchestrator agent understand how to respond to user inputs and manage tasks.\n",
+ "In this example, we will define a system prompt that asks the orchestrator agent to respond to user inputs in rhyming verse and manage tasks efficiently."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "search_tool = SearxNGSearchTool(SearxNGSearchToolConfig(base_url=os.getenv('SEARXNG_BASE_URL'), max_results=10))\n",
+ "calculator_tool = CalculatorTool()\n",
+ "\n",
+ "class ToolInfoProvider(SystemPromptContextProviderBase): \n",
+ " def get_info(self) -> str:\n",
+ " response = 'The available tools are:\\n'\n",
+ " for tool in [search_tool, calculator_tool]:\n",
+ " response += f'- {tool.tool_name}: {tool.tool_description}\\n'\n",
+ " return response\n",
+ "\n",
+ "# Define system prompt information including background, steps, and output instructions\n",
+ "system_prompt = SystemPromptInfo(\n",
+ " background=[\n",
+ " 'This assistant is an orchestrator of tasks designed to be helpful and efficient.',\n",
+ " ],\n",
+ " steps=[\n",
+ " 'Understand the user\\'s input and the current context.',\n",
+ " 'Look at the tools available and determine which to use next based on the current context, user input, and history.',\n",
+ " 'Execute the chosen tool and provide a relevant response to the user.'\n",
+ " ],\n",
+ " output_instructions=[\n",
+ " 'Provide helpful and relevant information to assist the user.',\n",
+ " 'Be efficient and effective in task orchestration.',\n",
+ " 'Always answer in rhyming verse.'\n",
+ " ],\n",
+ " context_providers={\n",
+ " 'tools': ToolInfoProvider(title='Available tools')\n",
+ " }\n",
+ ")\n",
+ "\n",
+ "# Initialize the system prompt generator with the defined system prompt and dynamic info providers\n",
+ "system_prompt_generator = SystemPromptGenerator(system_prompt)\n",
+ "\n",
+ "# Test out the system prompt generator\n",
+ "from rich.markdown import Markdown\n",
+ "from rich.console import Console\n",
+ "Console().print('='*50)\n",
+ "Console().print(Markdown(system_prompt_generator.generate_prompt()))\n",
+ "Console().print('='*50)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Step 4: Initialize Chat Memory\n",
+ "\n",
+ "We will initialize the chat memory to store conversation history and load an initial greeting message."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "memory = ChatMemory()\n",
+ "initial_memory = [\n",
+ " {'role': 'assistant', 'content': 'How do you do? What can I do for you? Tell me, pray, what is your need today?'}\n",
+ "]\n",
+ "memory.load(initial_memory)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Step 5: Set Up API Key and Create Orchestrator Agent\n",
+ "\n",
+ "To use the **OpenAI** API, you need to set up your API key. You can either enter it directly in the code or set it as an environment variable. Additionally, you can choose other clients such as **Anthropic**, **Mistral**, etc. For a full list, check out the [Instructor library docs](https://github.com/jxnl/instructor)."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "##################################################################\n",
+ "# ENTER YOUR API KEY BELOW, OR SET IT AS AN ENVIRONMENT VARIABLE #\n",
+ "##################################################################\n",
+ "API_KEY = ''\n",
+ "if not API_KEY:\n",
+ " # Get the environment variable\n",
+ " API_KEY = os.getenv('OPENAI_API_KEY')\n",
+ "\n",
+ "if not API_KEY:\n",
+ " raise ValueError('API key is not set. Please set the API key as a static variable or in the environment variable OPENAI_API_KEY.')\n",
+ "\n",
+ "client = instructor.from_openai(openai.OpenAI(api_key=API_KEY))\n",
+ "\n",
+ "class ResponseSchema(BaseModel):\n",
+ " chosen_schema: Union[BaseChatAgentResponse, SearxNGSearchToolSchema, CalculatorToolSchema] = Field(..., description='The response from the chat agent.')\n",
+ " \n",
+ " class Config:\n",
+ " title = 'ResponseSchema'\n",
+ " description = 'The response schema for the chat agent.'\n",
+ " json_schema_extra = {\n",
+ " 'title': title,\n",
+ " 'description': description,\n",
+ " }\n",
+ "\n",
+ "# Create a chat agent with the specified model, system prompt generator, and memory\n",
+ "# For all supported clients such as Anthropic & Gemini, have a look at the `instructor` library documentation.\n",
+ "agent = BaseChatAgent(\n",
+ " client=client, \n",
+ " system_prompt_generator=system_prompt_generator,\n",
+ " model='gpt-3.5-turbo',\n",
+ " memory=memory,\n",
+ " output_schema=ResponseSchema\n",
+ ")\n",
+ "\n",
+ "# Print the response schema\n",
+ "Console().print(ResponseSchema.model_json_schema())\n",
+ "Console().print('='*50)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Step 6: Main Chat Loop\n",
+ "\n",
+ "We will create a main chat loop for testing the orchestrator agent. This loop will allow you to interact with the chatbot in real-time.\n",
+ "To exit the loop, type `/exit` or `/quit`."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "console = Console()\n",
+ "console.print(f'Agent: {initial_memory[0][\"content\"]}')\n",
+ "\n",
+ "while True:\n",
+ " user_input = input('You: ')\n",
+ " if user_input.lower() in ['/exit', '/quit']:\n",
+ " print('Exiting chat...')\n",
+ " break\n",
+ "\n",
+ " response = agent.run(user_input)\n",
+ " console.print(f'Agent: {response}')"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3",
+ "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.12.3"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}
diff --git a/examples/notebooks/quickstart.ipynb b/examples/notebooks/quickstart.ipynb
index ccf6ef2..94c6c70 100644
--- a/examples/notebooks/quickstart.ipynb
+++ b/examples/notebooks/quickstart.ipynb
@@ -8,7 +8,7 @@
"\n",
"This quickstart tutorial demonstrates how to create a custom chatbot with a unique personality using the Atomic Agents library. The chatbot will respond to user inputs in rhyming verse.\n",
"\n",
- "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KennyVaneetvelde/atomic_agents/blob/main/examples/notebooks/quickstart/quickstart.ipynb#)\n"
+ "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/KennyVaneetvelde/atomic_agents/blob/main/examples/notebooks/quickstart.ipynb#)\n"
]
},
{
diff --git a/examples/orchestrator_agent.py b/examples/orchestrator_agent.py
new file mode 100644
index 0000000..227434a
--- /dev/null
+++ b/examples/orchestrator_agent.py
@@ -0,0 +1,100 @@
+import os
+from typing import List, Type, Union
+from pydantic import BaseModel, Field
+from rich.console import Console
+from atomic_agents.lib.components.chat_memory import ChatMemory
+from atomic_agents.agents.base_chat_agent import BaseChatAgent, BaseChatAgentResponse
+from atomic_agents.lib.components.system_prompt_generator import SystemPromptContextProviderBase, SystemPromptGenerator, SystemPromptInfo
+import instructor
+import openai
+
+from atomic_agents.lib.tools.base import BaseTool
+from atomic_agents.lib.tools.calculator_tool import CalculatorTool, CalculatorToolSchema
+from atomic_agents.lib.tools.search.searx_tool import SearxNGSearchTool, SearxNGSearchToolConfig, SearxNGSearchToolSchema
+
+search_tool = SearxNGSearchTool(SearxNGSearchToolConfig(base_url=os.getenv('SEARXNG_BASE_URL'), max_results=10))
+calculator_tool = CalculatorTool()
+
+class ToolInfoProvider(SystemPromptContextProviderBase):
+ def get_info(self) -> str:
+ response = 'The available tools are:\n'
+ for tool in [search_tool, calculator_tool]:
+ response += f'- {tool.tool_name}: {tool.tool_description}\n'
+ return response
+
+# Define system prompt information including background, steps, and output instructions
+system_prompt = SystemPromptInfo(
+ background=[
+ 'This assistant is an orchestrator of tasks designed to be helpful and efficient.',
+ ],
+ steps=[
+ 'Understand the user\'s input and the current context.',
+ 'Look at the tools available and determine which to use next based on the current context, user input, and history.',
+ 'Execute the chosen tool and provide a relevant response to the user.'
+ ],
+ output_instructions=[
+ 'Provide helpful and relevant information to assist the user.',
+ 'Be efficient and effective in task orchestration.',
+ 'Always answer in rhyming verse.'
+ ],
+ context_providers={
+ 'tools': ToolInfoProvider(title='Available tools')
+ }
+)
+
+class ResponseSchema(BaseModel):
+ chosen_schema: Union[BaseChatAgentResponse, SearxNGSearchToolSchema, CalculatorToolSchema] = Field(..., description='The response from the chat agent.')
+
+ class Config:
+ title = 'ResponseSchema'
+ description = 'The response schema for the chat agent.'
+ json_schema_extra = {
+ 'title': title,
+ 'description': description,
+ }
+
+# Initialize the system prompt generator with the defined system prompt and dynamic info providers
+system_prompt_generator = SystemPromptGenerator(system_prompt)
+
+# Test out the system prompt generator
+from rich.markdown import Markdown
+from rich.console import Console
+Console().print('='*50)
+Console().print(Markdown(system_prompt_generator.generate_prompt()))
+Console().print('='*50)
+
+# Print the response schema
+Console().print(ResponseSchema.model_json_schema())
+Console().print('='*50)
+
+# Initialize chat memory to store conversation history
+memory = ChatMemory()
+# Define initial memory with a greeting message from the assistant
+initial_memory = [
+ {'role': 'assistant', 'content': 'How do you do? What can I do for you? Tell me, pray, what is your need today?'}
+]
+# Load the initial memory into the chat memory
+memory.load(initial_memory)
+
+# Create a chat agent with the specified model, system prompt generator, and memory
+# For all supported clients such as Anthropic & Gemini, have a look at the `instructor` library documentation.
+agent = BaseChatAgent(
+ client=instructor.from_openai(openai.OpenAI()),
+ system_prompt_generator=system_prompt_generator,
+ model='gpt-3.5-turbo',
+ memory=memory,
+ output_schema=ResponseSchema
+)
+
+# Main chat loop for testing the chat agent
+console = Console()
+console.print(f'Agent: {initial_memory[0]["content"]}')
+
+while True:
+ user_input = input('You: ')
+ if user_input.lower() in ['/exit', '/quit']:
+ print('Exiting chat...')
+ break
+
+ response = agent.run(user_input)
+ console.print(f'Agent: {response}')
\ No newline at end of file