Skip to content

Building AI agents, atomically

Documentation improvements

KennyVaneetvelde671e9b35504f
diff --git a/docs/api/components.md b/docs/api/components.md
index a3a8c60..df0cd18 100644
--- a/docs/api/components.md
+++ b/docs/api/components.md
@@ -2,6 +2,45 @@
## Agent Memory
+The `AgentMemory` class manages conversation history and state for AI agents:
+
+```python
+from atomic_agents.lib.components.agent_memory import AgentMemory
+from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+
+# Initialize memory with optional max messages
+memory = AgentMemory(max_messages=10)
+
+# Add messages with proper schemas
+memory.add_message(
+ role="assistant",
+ content=BaseIOSchema(...)
+)
+
+# Access history
+history = memory.get_history()
+
+# Manage turns
+memory.initialize_turn() # Start new turn
+turn_id = memory.get_current_turn_id()
+
+# Persistence
+serialized = memory.dump() # Save to string
+memory.load(serialized) # Load from string
+
+# Create copy
+new_memory = memory.copy()
+```
+
+Key features:
+- Message history management with role-based messages
+- Turn-based conversation tracking
+- Support for multimodal content
+- Serialization and deserialization
+- Memory size management
+- Deep copy functionality
+
+For full API details:
```{eval-rst}
.. automodule:: atomic_agents.lib.components.agent_memory
:members:
@@ -12,6 +51,59 @@
## System Prompt Generator
+The `SystemPromptGenerator` creates structured system prompts for AI agents:
+
+```python
+from atomic_agents.lib.components.system_prompt_generator import (
+ SystemPromptGenerator,
+ SystemPromptContextProviderBase
+)
+
+# Create basic generator
+generator = SystemPromptGenerator(
+ background=[
+ "You are a helpful AI assistant.",
+ "You specialize in technical support."
+ ],
+ steps=[
+ "1. Understand the user's request",
+ "2. Analyze available information",
+ "3. Provide clear solutions"
+ ],
+ output_instructions=[
+ "Use clear, concise language",
+ "Include step-by-step instructions",
+ "Cite relevant documentation"
+ ]
+)
+
+# Generate prompt
+prompt = generator.generate_prompt()
+```
+
+### Context Providers
+
+Create custom context providers by extending `SystemPromptContextProviderBase`:
+
+```python
+class CustomContextProvider(SystemPromptContextProviderBase):
+ def __init__(self, title: str):
+ super().__init__(title=title)
+ self.data = {}
+
+ def get_info(self) -> str:
+ return f"Custom context: {self.data}"
+
+# Use with generator
+generator = SystemPromptGenerator(
+ background=["You are a helpful AI assistant."],
+ context_providers={
+ "custom": CustomContextProvider("Custom Info")
+ }
+)
+```
+
+For full API details:
```{eval-rst}
.. automodule:: atomic_agents.lib.components.system_prompt_generator
:members:
diff --git a/docs/api/index.md b/docs/api/index.md
index 05f3635..88cb6bb 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -28,11 +28,22 @@ The agents module provides the base classes for creating AI agents:
### Components
-The components module contains building blocks for extending agent functionality:
+The components module contains essential building blocks:
-- `AgentMemory`: Manages conversation history and context
-- `SystemPromptGenerator`: Creates dynamic system prompts
-- `SystemPromptContextProvider`: Provides contextual information for prompts
+- `AgentMemory`: Manages conversation history and state with support for:
+ - Message history with role-based messages
+ - Turn-based conversation tracking
+ - Multimodal content
+ - Serialization and persistence
+ - Memory size management
+
+- `SystemPromptGenerator`: Creates structured system prompts with:
+ - Background information
+ - Processing steps
+ - Output instructions
+ - Dynamic context through context providers
+
+- `SystemPromptContextProviderBase`: Base class for creating custom context providers that can inject dynamic information into system prompts
[Learn more about components](components.md)
@@ -52,6 +63,4 @@ The utils module provides helper functions and utilities:
For practical examples and guides on using these components, see:
- [Quickstart Guide](../guides/quickstart.md)
-- [Basic Concepts](../guides/basic_concepts.md)
- [Tools Guide](../guides/tools.md)
-- [Advanced Usage](../guides/advanced_usage.md)
diff --git a/docs/guides/advanced_usage.md b/docs/guides/advanced_usage.md
deleted file mode 100644
index b5534ba..0000000
--- a/docs/guides/advanced_usage.md
+++ /dev/null
@@ -1,241 +0,0 @@
-# Advanced Usage
-
-This guide covers advanced features and patterns in Atomic Agents.
-
-## Custom Schemas
-
-You can create custom input/output schemas for specialized agents:
-
-```python
-from typing import List
-from pydantic import Field
-from atomic_agents.lib.base.base_io_schema import BaseIOSchema
-from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig
-
-# Custom output schema
-class CustomOutputSchema(BaseIOSchema):
- """Schema for responses with suggested follow-up questions."""
-
- chat_message: str = Field(
- ...,
- description="The chat message exchanged between the user and the chat agent.",
- )
- suggested_user_questions: List[str] = Field(
- ...,
- description="A list of suggested follow-up questions the user could ask the agent.",
- )
-
-# Initialize memory with custom schema
-initial_message = CustomOutputSchema(
- chat_message="Hello! How can I assist you today?",
- suggested_user_questions=[
- "What can you do?",
- "Tell me a joke",
- "Tell me about how you were made"
- ]
-)
-memory.add_message("assistant", initial_message)
-
-# Create agent with custom schema
-agent = BaseAgent(
- config=BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- memory=memory,
- output_schema=CustomOutputSchema
- )
-)
-```
-
-## RAG Implementation
-
-Here's how to implement a Retrieval-Augmented Generation (RAG) system with two specialized agents:
-
-```python
-import instructor
-import openai
-from pydantic import Field
-from atomic_agents.agents.base_agent import BaseIOSchema, BaseAgent, BaseAgentConfig
-from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
-
-# Query Agent for generating semantic search queries
-class RAGQueryAgentInputSchema(BaseIOSchema):
- """Input schema for the RAG query agent."""
- user_message: str = Field(
- ...,
- description="The user's question or message to generate a semantic search query for"
- )
-
-class RAGQueryAgentOutputSchema(BaseIOSchema):
- """Output schema for the RAG query agent."""
- query: str = Field(
- ...,
- description="The semantic search query to use for retrieving relevant chunks"
- )
-
-query_agent = BaseAgent(
- BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- system_prompt_generator=SystemPromptGenerator(
- background=[
- "You are an expert at formulating semantic search queries for RAG systems.",
- "Your role is to convert user questions into effective semantic search queries that will retrieve the most relevant text chunks.",
- ],
- steps=[
- "1. Analyze the user's question to identify key concepts and information needs",
- "2. Reformulate the question into a semantic search query that will match relevant content",
- "3. Ensure the query captures the core meaning while being general enough to match similar content",
- ],
- output_instructions=[
- "Generate a clear, concise semantic search query",
- "Focus on key concepts and entities from the user's question",
- "Avoid overly specific details that might miss relevant matches",
- "Include synonyms or related terms when appropriate",
- "Explain your reasoning for the query formulation",
- ],
- ),
- input_schema=RAGQueryAgentInputSchema,
- output_schema=RAGQueryAgentOutputSchema,
- )
-)
-
-# QA Agent for answering questions using retrieved context
-class RAGQuestionAnsweringAgentInputSchema(BaseIOSchema):
- """Input schema for the RAG QA agent."""
- question: str = Field(
- ...,
- description="The user's question to answer"
- )
-
-class RAGQuestionAnsweringAgentOutputSchema(BaseIOSchema):
- """Output schema for the RAG QA agent."""
- answer: str = Field(
- ...,
- description="The answer to the user's question based on the retrieved context"
- )
-
-qa_agent = BaseAgent(
- BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- system_prompt_generator=SystemPromptGenerator(
- background=[
- "You are an expert at answering questions using retrieved context chunks from a RAG system.",
- "Your role is to synthesize information from the chunks to provide accurate, well-supported answers.",
- "You must explain your reasoning process before providing the answer.",
- ],
- steps=[
- "1. Analyze the question and available context chunks",
- "2. Identify the most relevant information in the chunks",
- "3. Explain how you'll use this information to answer the question",
- "4. Synthesize information into a coherent answer",
- ],
- output_instructions=[
- "First explain your reasoning process clearly",
- "Then provide a clear, direct answer based on the context",
- "If context is insufficient, state this in your reasoning",
- "Never make up information not present in the chunks",
- "Focus on being accurate and concise",
- ],
- ),
- input_schema=RAGQuestionAnsweringAgentInputSchema,
- output_schema=RAGQuestionAnsweringAgentOutputSchema,
- )
-)
-```
-
-## Streaming with Rich Display
-
-Handle streaming responses with rich formatting:
-
-```python
-from rich.live import Live
-from rich.text import Text
-from typing import List
-
-async def process_stream():
- with Live("", refresh_per_second=10, auto_refresh=True) as live:
- current_response = ""
- current_questions: List[str] = []
-
- async for partial_response in agent.run_async(input_schema):
- if hasattr(partial_response, "chat_message") and partial_response.chat_message:
- # Update message if changed
- if partial_response.chat_message != current_response:
- current_response = partial_response.chat_message
-
- # Update questions if available
- if hasattr(partial_response, "suggested_user_questions"):
- current_questions = partial_response.suggested_user_questions
-
- # Build display text
- display_text = Text.assemble(
- ("Agent: ", "bold green"),
- (current_response, "green")
- )
-
- # Add questions if we have them
- if current_questions:
- display_text.append("\n\n")
- display_text.append(
- "Suggested questions you could ask:\n",
- style="bold cyan"
- )
- for i, question in enumerate(current_questions, 1):
- display_text.append(f"{i}. {question}\n", style="cyan")
-
- live.update(display_text)
-
-# Run with asyncio
-import asyncio
-asyncio.run(process_stream())
-```
-
-## Best Practices
-
-### Error Handling
-
-```python
-try:
- response = agent.run(input_schema)
-except openai.APIError as e:
- console.print(f"[red]API Error:[/red] {e}")
- # Handle API-specific errors
-except Exception as e:
- console.print(f"[red]Error:[/red] {e}")
- # Handle other errors appropriately
-```
-
-### Memory Management
-
-```python
-# Initialize memory with context
-memory = AgentMemory()
-
-# Add system context
-memory.add_message(
- "system",
- "Important context or instructions for the agent..."
-)
-
-# Add initial message
-memory.add_message("assistant", initial_message)
-
-# Clear memory if needed
-memory.clear()
-```
-
-### Security
-
-```python
-# Use environment variables for sensitive data
-API_KEY = os.getenv("OPENAI_API_KEY")
-if not API_KEY:
- raise ValueError(
- "API key is not set. Please set the API key as a static variable "
- "or in the environment variable OPENAI_API_KEY."
- )
-```
-
-## Troubleshooting
diff --git a/docs/guides/basic_concepts.md b/docs/guides/basic_concepts.md
deleted file mode 100644
index 27dcc8e..0000000
--- a/docs/guides/basic_concepts.md
+++ /dev/null
@@ -1,237 +0,0 @@
-# Basic Concepts
-
-This guide introduces the core concepts of Atomic Agents.
-
-## What is an Agent?
-
-In Atomic Agents, an agent is an autonomous entity that can:
-
-- Process input using natural language
-- Make decisions based on its configuration and context
-- Execute actions through defined tools and capabilities
-- Maintain state and history of interactions
-
-## Core Components
-
-### BaseAgent
-
-The `BaseAgent` class is the foundation of all agents in the framework. It provides:
-
-- Input/output schema handling
-- Memory management
-- System prompt generation
-- Streaming capabilities
-- Tool integration
-
-### Components
-
-Components are modular pieces that can be added to agents to extend their functionality:
-
-#### AgentMemory
-
-Manages conversation history and state:
-
-```python
-from atomic_agents.lib.components.agent_memory import AgentMemory
-from atomic_agents.agents.base_agent import BaseAgentOutputSchema
-from rich.console import Console
-
-# Initialize console for pretty outputs
-console = Console()
-
-# Initialize memory
-memory = AgentMemory()
-
-# Initialize with a greeting
-initial_message = BaseAgentOutputSchema(
- chat_message="Hello! How can I assist you today?"
-)
-memory.add_message("assistant", initial_message)
-
-# Add system context if needed
-memory.add_message(
- "system",
- "This agent has access to specific tools and capabilities..."
-)
-
-# Access conversation history
-for message in memory.get_messages():
- console.print(f"{message.role}: {message.content}")
-```
-
-#### SystemPromptGenerator
-
-Customizes agent behavior through prompts:
-
-```python
-from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
-
-generator = SystemPromptGenerator(
- background=[
- "This assistant is a knowledgeable AI designed to be helpful, friendly, and informative.",
- "It specializes in providing clear explanations and step-by-step guidance.",
- "It maintains a professional yet approachable tone.",
- ],
- steps=[
- "1. Carefully analyze the user's input to understand their needs and context.",
- "2. Consider any relevant background information or previous conversation context.",
- "3. Formulate a clear, structured response that directly addresses the query.",
- "4. Include examples or analogies when they would help clarify the explanation.",
- ],
- output_instructions=[
- "Always provide clear, actionable information.",
- "Use markdown formatting for code blocks and technical terms.",
- "Break down complex concepts into digestible parts.",
- "Maintain a helpful and encouraging tone.",
- ]
-)
-
-# Use in agent configuration
-agent = BaseAgent(
- config=BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- memory=memory,
- system_prompt_generator=generator
- )
-)
-```
-
-## Basic Usage Patterns
-
-### Creating an Agent
-
-```python
-import os
-import instructor
-import openai
-from rich.console import Console
-from rich.panel import Panel
-from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig
-
-# Initialize console for pretty outputs
-console = Console()
-
-# API Key setup
-API_KEY = os.getenv("OPENAI_API_KEY")
-if not API_KEY:
- raise ValueError(
- "API key is not set. Please set the API key as a static variable "
- "or in the environment variable OPENAI_API_KEY."
- )
-
-# OpenAI client setup
-client = instructor.from_openai(openai.OpenAI(api_key=API_KEY))
-
-# Create agent with custom configuration
-agent = BaseAgent(
- config=BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- memory=memory,
- system_prompt_generator=generator
- )
-)
-
-# Display the system prompt
-default_system_prompt = agent.system_prompt_generator.generate_prompt()
-console.print(Panel(default_system_prompt, width=console.width, style="bold cyan"))
-```
-
-### Running Commands
-
-```python
-from atomic_agents.agents.base_agent import BaseAgentInputSchema
-from rich.text import Text
-from rich.live import Live
-
-# Simple command
-input_schema = BaseAgentInputSchema(chat_message="What is the weather?")
-response = agent.run(input_schema)
-console.print(Text("Agent:", style="bold green"), end=" ")
-console.print(Text(response.chat_message, style="green"))
-
-# Streaming response
-async def process_stream():
- with Live("", refresh_per_second=10, auto_refresh=True) as live:
- current_response = ""
- async for partial_response in agent.run_async(input_schema):
- if hasattr(partial_response, "chat_message") and partial_response.chat_message:
- if partial_response.chat_message != current_response:
- current_response = partial_response.chat_message
- display_text = Text.assemble(
- ("Agent: ", "bold green"),
- (current_response, "green")
- )
- live.update(display_text)
-
-# Run with asyncio
-import asyncio
-asyncio.run(process_stream())
-```
-
-## Next Steps
-
-After understanding these basic concepts, you can:
-
-1. Explore [advanced usage patterns](advanced_usage)
-2. Check out the [API Reference](/api/index) for detailed documentation
-3. Try building your own custom agents
-
-## Implementation Patterns
-
-Atomic Agents supports several common implementation patterns for different use cases:
-
-### Chatbots and Assistants
-
-Create conversational agents with various capabilities:
-
-```python
-from atomic_agents.lib.components.agent_memory import AgentMemory
-from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
-
-# Create memory for conversation history
-memory = AgentMemory()
-
-# Create personality
-generator = SystemPromptGenerator(
- background=["You are a helpful assistant specializing in technical support."],
- steps=[
- "1. Understand the technical issue",
- "2. Ask clarifying questions if needed",
- "3. Provide step-by-step solutions"
- ]
-)
-
-# Create agent
-support_agent = BaseAgent(
- config=BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- memory=memory,
- system_prompt_generator=generator
- )
-)
-```
-
-### RAG Systems
-
-Build Retrieval-Augmented Generation systems:
-
-```python
-from atomic_agents.lib.components.rag import RAGComponent
-from atomic_agents.lib.components.embeddings import EmbeddingsManager
-
-# Initialize RAG components
-embeddings = EmbeddingsManager(client=client)
-rag = RAGComponent(embeddings=embeddings)
-
-# Create RAG agent
-rag_agent = BaseAgent(
- config=BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- components={"rag": rag}
- )
-)
-```
diff --git a/docs/guides/quickstart.md b/docs/guides/quickstart.md
index 4e43e8d..633ea56 100644
--- a/docs/guides/quickstart.md
+++ b/docs/guides/quickstart.md
@@ -1,138 +1,323 @@
# Quickstart Guide
-This guide will help you get started with Atomic Agents quickly through practical examples.
+This guide will help you get started with the Atomic Agents framework. We'll cover basic usage, custom agents, and different AI providers.
## Installation
-1. Clone the Atomic Agents repository:
+First, install the package using pip:
- ```bash
- git clone https://github.com/BrainBlend-AI/atomic-agents
- ```
-
-2. Install dependencies using Poetry:
-
- ```bash
- cd atomic-agents
- poetry install
- ```
-
-## Basic Examples
+```bash
+pip install atomic-agents
+```
-### 1. Basic Chatbot
+## Basic Chatbot
-This example demonstrates a simple chatbot using the Atomic Agents framework:
+Let's start with a simple chatbot:
```python
import os
-import instructor
-from openai import OpenAI
+from rich.console import Console
+from dotenv import load_dotenv
from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig
+from atomic_agents.lib.components.agent_memory import AgentMemory
-# Initialize OpenAI client
-client = instructor.from_openai(OpenAI())
+# Load environment variables and setup
+load_dotenv()
+console = Console()
-# Create basic configuration
-config = BaseAgentConfig(
- client=client,
- model="gpt-4o-mini"
+# Initialize memory with assistant's first message
+memory = AgentMemory()
+memory.add_assistant_message("Hello! I'm your AI assistant. How can I help you today?")
+
+# Create agent
+agent = BaseAgent(
+ config=BaseAgentConfig(
+ client=instructor.from_openai(OpenAI(api_key=os.getenv("OPENAI_API_KEY"))),
+ model="gpt-4-turbo-preview",
+ model_api_parameters={"max_tokens": 2048}
+ )
)
-# Initialize agent
-agent = BaseAgent(config)
+# Chat loop
+while True:
+ # Get user input
+ user_input = console.input("[bold green]You:[/bold green] ")
+ if user_input.lower() in ["exit", "quit"]:
+ break
+
+ # Add user message to memory
+ memory.add_user_message(user_input)
+
+ # Get response from agent
+ response = agent.run(memory=memory)
-# Start chat loop
+ # Add response to memory and display
+ memory.add_assistant_message(response)
+ console.print("[bold blue]Assistant:[/bold blue]", response)
+```
+
+## Streaming Responses
+
+For a more interactive experience, you can use streaming:
+
+```python
+import os
+from rich.console import Console
+from rich.live import Live
+from rich.markdown import Markdown
+from dotenv import load_dotenv
+from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig
+from atomic_agents.lib.components.agent_memory import AgentMemory
+
+# Setup as before...
+
+# Chat loop with streaming
while True:
- user_input = input("You: ")
- if user_input.lower() == "exit":
+ user_input = console.input("[bold green]You:[/bold green] ")
+ if user_input.lower() in ["exit", "quit"]:
break
- response = agent.run({"chat_message": user_input})
- print(f"Assistant: {response.chat_message}")
+ memory.add_user_message(user_input)
+
+ # Stream the response
+ with Live(console=console, refresh_per_second=4) as live:
+ response = ""
+ for chunk in agent.stream(memory=memory):
+ response += chunk
+ live.update(Markdown(f"**Assistant:** {response}"))
+
+ memory.add_assistant_message(response)
```
-### 2. Custom Chatbot
+## Custom Chatbot
-This example shows how to create a custom chatbot with a specific personality:
+You can customize the agent's behavior using system prompts and context providers. Context providers are particularly useful for injecting dynamic information that changes between calls:
```python
-from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
+from dataclasses import dataclass
+from typing import List
+from atomic_agents.lib.components.system_prompt_generator import (
+ SystemPromptGenerator,
+ SystemPromptContextProviderBase
+)
+
+@dataclass
+class SearchResult:
+ content: str
+ metadata: dict
+
+class SearchResultsProvider(SystemPromptContextProviderBase):
+ def __init__(self, title: str):
+ super().__init__(title=title)
+ self.results: List[SearchResult] = []
+
+ def get_info(self) -> str:
+ """Dynamically format search results for the system prompt"""
+ if not self.results:
+ return "No search results available."
-# Create custom system prompt
-generator = SystemPromptGenerator(
+ return "\n\n".join([
+ f"Result {idx}:\nMetadata: {result.metadata}\nContent:\n{result.content}\n{'-' * 80}"
+ for idx, result in enumerate(self.results, 1)
+ ])
+
+# Create prompt generator with dynamic context
+prompt_generator = SystemPromptGenerator(
background=[
- "You are a friendly assistant that always responds in rhyming verse.",
- "You maintain a playful and poetic tone while being helpful.",
+ "You are an AI assistant that answers questions based on search results.",
+ "Analyze the provided search results to give accurate answers."
],
steps=[
- "1. Understand the user's question or request",
- "2. Formulate your response in rhyming verse",
- "3. Ensure the response is both helpful and entertaining"
+ "1. Review all provided search results",
+ "2. Extract relevant information",
+ "3. Synthesize a comprehensive answer"
],
output_instructions=[
- "Always respond in rhyming verse",
- "Keep responses concise but informative",
- "Maintain a playful tone"
- ]
+ "Base your answer only on the provided search results",
+ "Cite specific results when possible",
+ "Admit when information is not found in the results"
+ ],
+ context_providers={
+ "search_results": SearchResultsProvider("Search Results")
+ }
)
-# Create agent with custom configuration
+# Create agent with dynamic context
agent = BaseAgent(
config=BaseAgentConfig(
client=client,
- model="gpt-4o-mini",
- system_prompt_generator=generator
+ model=model,
+ system_prompt_generator=prompt_generator
)
)
+
+# Example usage with dynamic updates
+def process_question(question: str):
+ # Perform search and get results
+ results = perform_search(question) # Your search implementation
+
+ # Update context provider with new results
+ search_provider = prompt_generator.context_providers["search_results"]
+ search_provider.results = [
+ SearchResult(content=result.text, metadata=result.meta)
+ for result in results
+ ]
+
+ # Each call to the agent will now include the updated search results
+ response = agent.run(memory=memory)
```
-### 3. Custom Schema
+The key difference with context providers is that they allow you to:
+- Inject dynamic information that changes between calls
+- Update context (like search results, current state, etc.) without changing the base prompt
+- Keep a clear separation between static prompt elements and dynamic context
+- Handle potentially large or structured data in a clean way
+
+This pattern is especially useful for:
+- RAG (Retrieval Augmented Generation) systems
+- Agents that need access to external data
+- Stateful conversations where context changes
+- Multi-step processes with varying intermediate results
-This example demonstrates using a custom output schema:
+## Custom Input/Output Schema
+
+For more structured interactions, define custom schemas:
```python
-from pydantic import BaseModel
-from typing import List
+from pydantic import BaseModel, Field
-class CustomResponseSchema(BaseModel):
- chat_message: str
- follow_up_questions: List[str]
+class CustomInput(BaseModel):
+ question: str = Field(..., description="The user's question")
+ context: str = Field(..., description="Additional context for the question")
+
+class CustomOutput(BaseModel):
+ answer: str = Field(..., description="The answer to the user's question")
+ confidence: float = Field(..., description="Confidence score (0-1)")
+ sources: list[str] = Field(default_factory=list, description="Sources used")
# Create agent with custom schema
-agent = BaseAgent(
+agent = BaseAgent[CustomInput, CustomOutput](
config=BaseAgentConfig(
client=client,
- model="gpt-4o-mini",
- output_schema=CustomResponseSchema
+ model=model,
+ input_schema=CustomInput,
+ output_schema=CustomOutput
)
)
+
+# Use with custom schema
+result = agent.run(
+ memory=memory,
+ input_data=CustomInput(
+ question="What is machine learning?",
+ context="Explain for a beginner"
+ )
+)
+print(f"Answer: {result.answer}")
+print(f"Confidence: {result.confidence}")
+print(f"Sources: {result.sources}")
```
-### 4. Multiple Providers
+## Multiple Providers
-This example shows how to use different AI providers:
+The framework supports multiple AI providers:
```python
-# OpenAI
-openai_client = instructor.from_openai(OpenAI())
-
-# Groq
-from groq import Groq
-groq_client = instructor.from_openai(Groq())
-
-# Ollama (for local development)
-from atomic_agents.lib.providers.ollama import OllamaClient
-ollama_client = instructor.from_openai(OllamaClient())
+import os
+import instructor
+from rich.console import Console
+from dotenv import load_dotenv
+from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig
-# Use any provider
+load_dotenv()
+console = Console()
+
+def setup_client(provider):
+ if provider == "openai":
+ from openai import OpenAI
+ api_key = os.getenv("OPENAI_API_KEY")
+ client = instructor.from_openai(OpenAI(api_key=api_key))
+ model = "gpt-4-turbo-preview"
+
+ elif provider == "anthropic":
+ from anthropic import Anthropic
+ api_key = os.getenv("ANTHROPIC_API_KEY")
+ client = instructor.from_anthropic(Anthropic(api_key=api_key))
+ model = "claude-3-haiku-20240307"
+
+ elif provider == "groq":
+ from groq import Groq
+ api_key = os.getenv("GROQ_API_KEY")
+ client = instructor.from_groq(
+ Groq(api_key=api_key),
+ mode=instructor.Mode.JSON
+ )
+ model = "mixtral-8x7b-32768"
+
+ elif provider == "ollama":
+ from openai import OpenAI as OllamaClient
+ client = instructor.from_openai(
+ OllamaClient(
+ base_url="http://localhost:11434/v1",
+ api_key="ollama"
+ )
+ )
+ model = "llama2"
+
+ elif provider == "gemini":
+ from openai import OpenAI
+ api_key = os.getenv("GEMINI_API_KEY")
+ client = instructor.from_openai(
+ OpenAI(
+ api_key=api_key,
+ base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
+ ),
+ mode=instructor.Mode.JSON
+ )
+ model = "gemini-pro"
+
+ else:
+ raise ValueError(f"Unsupported provider: {provider}")
+
+ return client, model
+
+# Choose a provider
+provider = "openai" # or "anthropic", "groq", "ollama", "gemini"
+client, model = setup_client(provider)
+
+# Create agent with chosen provider
agent = BaseAgent(
config=BaseAgentConfig(
- client=openai_client, # or groq_client, or ollama_client
- model="gpt-4o-mini" # adjust model name based on provider
+ client=client,
+ model=model,
+ model_api_parameters={"max_tokens": 2048}
)
)
```
+The framework supports multiple providers through Instructor:
+
+- **OpenAI**: Standard GPT models
+- **Anthropic**: Claude models
+- **Groq**: Fast inference for open models
+- **Ollama**: Local models (requires Ollama running)
+- **Gemini**: Google's Gemini models
+
+Each provider requires its own API key (except Ollama) which should be set in environment variables:
+```bash
+# OpenAI
+export OPENAI_API_KEY="your-openai-key"
+
+# Anthropic
+export ANTHROPIC_API_KEY="your-anthropic-key"
+
+# Groq
+export GROQ_API_KEY="your-groq-key"
+
+# Gemini
+export GEMINI_API_KEY="your-gemini-key"
+```
+
## Running the Examples
To run any of these examples:
@@ -154,7 +339,5 @@ To run any of these examples:
After trying these examples, you can:
-1. Explore [basic concepts](basic_concepts) for deeper understanding
-2. Learn about [tools and their integration](tools.md)
-3. Check out [advanced usage patterns](advanced_usage)
-4. Review the [API reference](../api/index) for detailed documentation
+1. Learn about [tools and their integration](tools.md)
+2. Review the [API reference](../api/index) for detailed documentation
diff --git a/docs/guides/tools.md b/docs/guides/tools.md
index cc933df..acae497 100644
--- a/docs/guides/tools.md
+++ b/docs/guides/tools.md
@@ -1,225 +1,165 @@
# Tools Guide
-Atomic Agents provides a collection of tools through the Atomic Forge that extend agent capabilities.
+Atomic Agents uses a unique approach to tools through the **Atomic Forge** system. Rather than bundling all tools into a single package, tools are designed to be standalone, modular components that you can download and integrate into your project as needed.
-## Installing Tools
+## Philosophy
-Tools are managed using the Atomic Assembler CLI:
+The Atomic Forge approach provides several key benefits:
-```bash
-# Install a specific tool
-atomic-assembler install calculator
-
-# List available tools
-atomic-assembler list
-
-# Update installed tools
-atomic-assembler update
-```
+1. **Full Control**: You have complete ownership and control over each tool you download. Want to modify a tool's behavior? You can change it without impacting other users.
+2. **Dependency Management**: Since tools live in your codebase, you have better control over dependencies.
+3. **Lightweight**: Download only the tools you need, avoiding unnecessary dependencies. For example, you don't need Sympy if you're not using the Calculator tool.
## Available Tools
-### Calculator
+The Atomic Forge includes several pre-built tools:
-A tool for performing mathematical calculations:
+- **Calculator**: Perform mathematical calculations
+- **SearxNG Search**: Search the web using SearxNG
+- **Tavily Search**: AI-powered web search
+- **YouTube Transcript Scraper**: Extract transcripts from YouTube videos
+- **Webpage Scraper**: Extract content from web pages
-```python
-from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig
+## Using Tools
-agent = BaseAgent(
- config=BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- tools=["calculator"]
- )
-)
+### 1. Download Tools
-# The agent can now perform calculations
-response = agent.run({
- "chat_message": "What is the square root of 144 plus 50?"
-})
-```
-
-### SearxNG Search
-
-A privacy-focused web search tool:
+Use the Atomic Assembler CLI to download tools:
-```python
-# Configure with your SearxNG instance
-agent = BaseAgent(
- config=BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- tools=["searxng_search"],
- tool_configs={
- "searxng_search": {
- "instance_url": "https://your-searxng-instance.com"
- }
- }
- )
-)
+```bash
+atomic
```
-### Tavily Search
-
-An AI-optimized search engine:
+This will present a menu where you can select and download tools. Each tool includes:
+- Input/Output schemas
+- Usage examples
+- Dependencies
+- Installation instructions
-```python
-import os
+### 2. Tool Structure
-# Set your Tavily API key
-os.environ["TAVILY_API_KEY"] = "your-api-key"
+Each tool follows a standard structure:
-agent = BaseAgent(
- config=BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- tools=["tavily_search"]
- )
-)
+```
+tool_name/
+│ .coveragerc
+│ pyproject.toml
+│ README.md
+│ requirements.txt
+│ poetry.lock
+│
+├── tool/
+│ │ tool_name.py
+│ │ some_util_file.py
+│
+└── tests/
+ │ test_tool_name.py
+ │ test_some_util_file.py
```
-### YouTube Transcript Scraper
+### 3. Using a Tool
-Extract transcripts from YouTube videos:
+Here's an example of using a downloaded tool:
```python
-import os
-
-# Set your YouTube API key
-os.environ["YOUTUBE_API_KEY"] = "your-api-key"
-
-agent = BaseAgent(
- config=BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- tools=["youtube_transcript"]
- )
+from calculator.tool.calculator import (
+ CalculatorTool,
+ CalculatorInputSchema,
+ CalculatorToolConfig
)
-# The agent can now analyze YouTube videos
-response = agent.run({
- "chat_message": "Summarize this video: https://youtube.com/watch?v=..."
-})
-```
-
-### Webpage Scraper
-
-Extract content from web pages:
+# Initialize the tool
+calculator = CalculatorTool(
+ config=CalculatorToolConfig()
+)
-```python
-agent = BaseAgent(
- config=BaseAgentConfig(
- client=client,
- model="gpt-4o-mini",
- tools=["webpage_scraper"]
+# Use the tool
+result = calculator.run(
+ CalculatorInputSchema(
+ expression="2 + 2"
)
)
-
-# The agent can now analyze web pages
-response = agent.run({
- "chat_message": "What are the main points from this article: https://..."
-})
+print(f"Result: {result.value}") # Result: 4
```
## Creating Custom Tools
-You can create your own tools by following these steps:
-
-### 1. Create Tool Structure
-
-Create a new directory with the required files:
-
-```
-my_tool/
-├── __init__.py
-├── README.md
-├── pyproject.toml
-└── my_tool/
- ├── __init__.py
- └── tool.py
-```
-
-### 2. Implement Tool Logic
+You can create your own tools by following these guidelines:
-Create your tool implementation:
+### 1. Basic Structure
```python
-from pydantic import BaseModel
-from atomic_agents.lib.tools import BaseTool
-
-class MyToolInputs(BaseModel):
- param1: str
- param2: int
+from atomic_agents.lib.base.base_tool import BaseTool, BaseToolConfig
+from atomic_agents.agents.base_agent import BaseIOSchema
+
+################
+# Input Schema #
+################
+
+class MyToolInputSchema(BaseIOSchema):
+ """Define what your tool accepts as input"""
+ value: str = Field(..., description="Input value to process")
+
+#####################
+# Output Schema(s) #
+#####################
+
+class MyToolOutputSchema(BaseIOSchema):
+ """Define what your tool returns"""
+ result: str = Field(..., description="Processed result")
+
+#################
+# Configuration #
+#################
+
+class MyToolConfig(BaseToolConfig):
+ """Tool configuration options"""
+ api_key: str = Field(
+ default=os.getenv("MY_TOOL_API_KEY"),
+ description="API key for the service"
+ )
-class MyToolOutputs(BaseModel):
- result: str
+#####################
+# Main Tool & Logic #
+#####################
class MyTool(BaseTool):
- name = "my_tool"
- description = "Description of what my tool does"
- inputs_schema = MyToolInputs
- outputs_schema = MyToolOutputs
-
- def run(self, inputs: MyToolInputs) -> MyToolOutputs:
- # Implement your tool logic here
- result = f"Processed {inputs.param1} {inputs.param2} times"
- return MyToolOutputs(result=result)
-```
-
-### 3. Configure Package
-
-Create a pyproject.toml:
-
-```toml
-[tool.poetry]
-name = "my-tool"
-version = "0.1.0"
-description = "My custom tool for Atomic Agents"
-authors = ["Your Name <[email protected]>"]
-
-[tool.poetry.dependencies]
-python = "^3.11"
-atomic-agents = "^0.1.0"
+ """Main tool implementation"""
+ input_schema = MyToolInputSchema
+ output_schema = MyToolOutputSchema
+
+ def __init__(self, config: MyToolConfig = MyToolConfig()):
+ super().__init__(config)
+ self.api_key = config.api_key
+
+ def run(self, params: MyToolInputSchema) -> MyToolOutputSchema:
+ # Implement your tool's logic here
+ result = self.process_input(params.value)
+ return MyToolOutputSchema(result=result)
```
-### 4. Document Usage
-
-Create a README.md with:
-
-* Installation instructions
-* Configuration requirements
-* Usage examples
-* Any environment variables needed
-
-## Best Practices
-
-### 1. Error Handling
-
-* Implement proper error handling in tools
-* Return meaningful error messages
-* Handle rate limits and retries
-
-### 2. Configuration
-
-* Use environment variables for sensitive data
-* Make configuration flexible but with sensible defaults
-* Document all configuration options
-
-### 3. Testing
+### 2. Best Practices
-* Write unit tests for your tools
-* Include integration tests if applicable
-* Test error cases and edge conditions
+- **Single Responsibility**: Each tool should do one thing well
+- **Clear Interfaces**: Use explicit input/output schemas
+- **Error Handling**: Validate inputs and handle errors gracefully
+- **Documentation**: Include clear usage examples and requirements
+- **Tests**: Write comprehensive tests for your tool
+- **Dependencies**: Manually create `requirements.txt` with only runtime dependencies
-### 4. Documentation
+### 3. Tool Requirements
-* Keep README up to date
-* Include example code
-* Document any breaking changes
+- Must inherit from appropriate base classes:
+ - Input/Output schemas from `BaseIOSchema`
+ - Configuration from `BaseToolConfig`
+ - Tool class from `BaseTool`
+- Must include proper documentation
+- Must include tests
+- Must follow the standard directory structure
## Next Steps
-* Check out the [example projects](../examples/index.md)
-* Learn about [advanced usage patterns](advanced_usage.md)
-* Contribute your own tools to the [Atomic Forge](../contributing.md)
+1. Browse available tools in the [Atomic Forge repository](https://github.com/BrainBlend-AI/atomic-agents/tree/main/atomic-forge)
+2. Try downloading and using different tools via the CLI
+3. Consider creating your own tools following the guidelines
+4. Share your tools with the community through pull requests