Skip to content

Building AI agents, atomically

Update BaseAgent and components documentation

KennyVaneetvelde516f7311c025
diff --git a/docs/api/agents.md b/docs/api/agents.md
index 4c5a6a0..251167e 100644
--- a/docs/api/agents.md
+++ b/docs/api/agents.md
@@ -97,252 +97,163 @@ class CustomOutputSchema(BaseIOSchema):
)
```
-## Base Agent Configuration
-
-### BaseAgentConfig
-
-The configuration class for BaseAgent that defines all settings and components.
-
-```{eval-rst}
-.. py:class:: BaseAgentConfig
-
- Configuration class for BaseAgent.
-
- **Inheritance:**
- - :class:`pydantic.BaseModel`
-
- .. py:attribute:: client
- :type: Any
-
- The LLM client to use (e.g., OpenAI, Anthropic, etc.). Must be wrapped with instructor.
-
- .. py:attribute:: model
- :type: str
-
- The model identifier to use with the client (e.g., "gpt-4", "claude-3-opus-20240229").
-
- .. py:attribute:: memory
- :type: Optional[AgentMemory]
-
- Memory component for storing conversation history. Defaults to None.
-
- .. py:attribute:: system_prompt_generator
- :type: Optional[SystemPromptGenerator]
-
- Generator for creating system prompts. Defaults to None.
-
- .. py:attribute:: input_schema
- :type: Optional[Type[BaseIOSchema]]
-
- Schema for validating agent inputs. Defaults to BaseAgentInputSchema.
- Must be a subclass of BaseIOSchema.
-
- .. py:attribute:: output_schema
- :type: Optional[Type[BaseIOSchema]]
-
- Schema for validating agent outputs. Defaults to BaseAgentOutputSchema.
- Must be a subclass of BaseIOSchema.
-
- .. py:attribute:: tools
- :type: Optional[List[str]]
-
- List of tool names to make available to the agent. Defaults to None.
-
- .. py:attribute:: tool_configs
- :type: Optional[Dict[str, Dict[str, Any]]]
-
- Configuration parameters for tools. Defaults to None.
-
- .. py:attribute:: components
- :type: Optional[Dict[str, Any]]
-
- Additional components to attach to the agent. Defaults to None.
-
- Example:
- >>> config = BaseAgentConfig(
- ... client=instructor.from_openai(OpenAI()),
- ... model="gpt-4",
- ... input_schema=CustomInputSchema,
- ... output_schema=CustomOutputSchema,
- ... memory=AgentMemory(),
- ... system_prompt_generator=SystemPromptGenerator(
- ... background=["You are a helpful assistant"],
- ... steps=["1. Understand the request", "2. Provide a response"]
- ... )
- ... )
-```
-
## Base Agent
-The BaseAgent class provides core functionality for building AI agents with structured input/output schemas,
-memory management, and streaming capabilities.
-
-### Basic Usage
+The `BaseAgent` class is the foundation for building AI agents in the Atomic Agents framework. It handles chat interactions, memory management, system prompts, and responses from language models.
```python
-import instructor
-from openai import OpenAI
from atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfig
from atomic_agents.lib.components.agent_memory import AgentMemory
+from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
-# Initialize with OpenAI
-client = instructor.from_openai(OpenAI())
-
-# Create basic configuration
-config = BaseAgentConfig(
- client=client,
- model="gpt-4",
- memory=AgentMemory()
+# Create agent with basic configuration
+agent = BaseAgent(
+ config=BaseAgentConfig(
+ client=instructor.from_openai(OpenAI()),
+ model="gpt-4-turbo-preview",
+ memory=AgentMemory(),
+ system_prompt_generator=SystemPromptGenerator()
+ )
)
-# Initialize agent
-agent = BaseAgent(config)
-```
-
-### Class Documentation
-
-```{eval-rst}
-.. py:class:: BaseAgent
-
- .. py:method:: __init__(config: BaseAgentConfig)
-
- Initializes a new BaseAgent instance.
-
- :param config: Configuration object containing client, model, memory, and other settings
- :type config: BaseAgentConfig
-
- .. py:method:: run(user_input: Optional[BaseIOSchema] = None) -> BaseIOSchema
-
- Runs the chat agent with the given user input synchronously.
-
- :param user_input: The input from the user
- :type user_input: Optional[BaseIOSchema]
- :return: The response from the chat agent
- :rtype: BaseIOSchema
-
- .. py:method:: run_async(user_input: Optional[BaseIOSchema] = None) -> AsyncGenerator[BaseIOSchema, None]
+# Run the agent
+response = agent.run(user_input)
- Runs the chat agent with streaming output asynchronously.
+# Stream responses
+async for partial_response in agent.run_async(user_input):
+ print(partial_response)
+```
- :param user_input: The input from the user
- :type user_input: Optional[BaseIOSchema]
- :return: An async generator yielding partial responses
- :rtype: AsyncGenerator[BaseIOSchema, None]
+### Configuration
- .. py:method:: reset_memory()
+The `BaseAgentConfig` class provides configuration options:
- Resets the agent's memory to its initial state.
+```python
+class BaseAgentConfig:
+ client: instructor.Instructor # Client for interacting with the language model
+ model: str = "gpt-4-turbo-preview" # Model to use
+ memory: Optional[AgentMemory] = None # Memory component
+ system_prompt_generator: Optional[SystemPromptGenerator] = None # Prompt generator
+ input_schema: Optional[Type[BaseModel]] = None # Custom input schema
+ output_schema: Optional[Type[BaseModel]] = None # Custom output schema
+ model_api_parameters: Optional[dict] = None # Additional API parameters
+```
- .. py:method:: get_context_provider(provider_name: str) -> Type[SystemPromptContextProviderBase]
+### Input/Output Schemas
- Retrieves a context provider by name.
+Default schemas for basic chat interactions:
- :param provider_name: The name of the context provider
- :type provider_name: str
- :return: The context provider if found
- :rtype: SystemPromptContextProviderBase
- :raises KeyError: If the context provider is not found
+```python
+class BaseAgentInputSchema(BaseIOSchema):
+ """Input from the user to the AI agent."""
+ chat_message: str = Field(
+ ...,
+ description="The chat message sent by the user."
+ )
- .. py:method:: register_context_provider(provider_name: str, provider: SystemPromptContextProviderBase)
+class BaseAgentOutputSchema(BaseIOSchema):
+ """Response generated by the chat agent."""
+ chat_message: str = Field(
+ ...,
+ description="The markdown-enabled response generated by the chat agent."
+ )
+```
- Registers a new context provider.
+### Key Methods
- :param provider_name: The name of the context provider
- :type provider_name: str
- :param provider: The context provider instance
- :type provider: SystemPromptContextProviderBase
+- `run(user_input: Optional[BaseIOSchema] = None) -> BaseIOSchema`: Process user input and get response
+- `run_async(user_input: Optional[BaseIOSchema] = None)`: Stream responses asynchronously
+- `get_response(response_model=None) -> Type[BaseModel]`: Get direct model response
+- `reset_memory()`: Reset memory to initial state
+- `get_context_provider(provider_name: str)`: Get a registered context provider
+- `register_context_provider(provider_name: str, provider: SystemPromptContextProviderBase)`: Register a new context provider
+- `unregister_context_provider(provider_name: str)`: Remove a context provider
- .. py:method:: unregister_context_provider(provider_name: str)
+### Context Providers
- Unregisters an existing context provider.
+Context providers can be used to inject dynamic information into the system prompt:
- :param provider_name: The name of the context provider to remove
- :type provider_name: str
- :raises KeyError: If the context provider is not found
+```python
+from atomic_agents.lib.components.system_prompt_generator import SystemPromptContextProviderBase
+
+class SearchResultsProvider(SystemPromptContextProviderBase):
+ def __init__(self, title: str):
+ super().__init__(title=title)
+ self.results = []
+
+ def get_info(self) -> str:
+ return "\n\n".join([
+ f"Result {idx}:\n{result}"
+ for idx, result in enumerate(self.results, 1)
+ ])
+
+# Register with agent
+agent.register_context_provider(
+ "search_results",
+ SearchResultsProvider("Search Results")
+)
```
-### Examples
+### Streaming Support
-#### Basic Synchronous Interaction
+The agent supports streaming responses for more interactive experiences:
```python
-# Create input and get response
-user_input = agent.input_schema(chat_message="Tell me about quantum computing")
-response = agent.run(user_input)
-
-print(f"Assistant: {response.chat_message}")
+async def chat():
+ async for partial_response in agent.run_async(user_input):
+ # Handle each chunk of the response
+ print(partial_response.chat_message)
```
-#### Streaming Response
-
-```python
-import asyncio
+### Memory Management
-async def stream_chat():
- # Initialize with AsyncOpenAI for streaming
- client = instructor.from_openai(AsyncOpenAI())
- agent = BaseAgent(BaseAgentConfig(client=client, model="gpt-4"))
+The agent automatically manages conversation history through the `AgentMemory` component:
- # Create input and stream response
- user_input = agent.input_schema(chat_message="Explain streaming")
- print("\nUser: Explain streaming")
- print("Assistant: ", end="", flush=True)
+```python
+# Access memory
+history = agent.memory.get_history()
- async for partial_response in agent.run_async(user_input):
- if hasattr(partial_response, "chat_message"):
- print(partial_response.chat_message, end="", flush=True)
- print()
+# Reset to initial state
+agent.reset_memory()
-asyncio.run(stream_chat())
+# Save/load memory state
+serialized = agent.memory.dump()
+agent.memory.load(serialized)
```
-#### Using Tools
-
-```python
-# Create agent with tools
-agent = BaseAgent(
- config=BaseAgentConfig(
- client=client,
- model="gpt-4",
- tools=["calculator", "searxng_search"],
- tool_configs={
- "searxng_search": {
- "instance_url": "https://your-searxng-instance.com"
- }
- }
- )
-)
-
-# The agent can now use these tools in its responses
-response = agent.run(
- agent.input_schema(
- chat_message="What is the square root of 144 plus the current temperature in London?"
- )
-)
-```
+### Custom Schemas
-#### Custom Memory and System Prompt
+You can use custom input/output schemas for structured interactions:
```python
-from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
+from pydantic import BaseModel, Field
+from typing import List
-# Create custom system prompt
-generator = SystemPromptGenerator(
- background=["You are a helpful AI assistant specializing in technical support."],
- steps=[
- "1. Understand the technical issue",
- "2. Ask clarifying questions if needed",
- "3. Provide step-by-step solutions"
- ]
-)
+class CustomInput(BaseIOSchema):
+ """Custom input with specific fields"""
+ question: str = Field(..., description="User's question")
+ context: str = Field(..., description="Additional context")
-# Create agent with custom memory and prompt
-agent = BaseAgent(
+class CustomOutput(BaseIOSchema):
+ """Custom output with structured data"""
+ answer: str = Field(..., description="Answer to the question")
+ sources: List[str] = Field(..., description="Source references")
+
+# Create agent with custom schemas
+agent = BaseAgent[CustomInput, CustomOutput](
config=BaseAgentConfig(
client=client,
- model="gpt-4",
- memory=AgentMemory(),
- system_prompt_generator=generator
+ model=model,
+ input_schema=CustomInput,
+ output_schema=CustomOutput
)
)
```
+
+For full API details:
+```{eval-rst}
+.. automodule:: atomic_agents.agents.base_agent
+ :members:
+ :undoc-members:
+ :show-inheritance:
+```
diff --git a/docs/api/components.md b/docs/api/components.md
index df0cd18..260a5c6 100644
--- a/docs/api/components.md
+++ b/docs/api/components.md
@@ -11,22 +11,26 @@ 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
+# Add messages
memory.add_message(
- role="assistant",
+ role="user",
content=BaseIOSchema(...)
)
+# Initialize a new turn
+memory.initialize_turn()
+turn_id = memory.get_current_turn_id()
+
# Access history
history = memory.get_history()
-# Manage turns
-memory.initialize_turn() # Start new turn
-turn_id = memory.get_current_turn_id()
+# Manage memory
+memory.get_message_count() # Get number of messages
+memory.delete_turn_id(turn_id) # Delete messages by turn
# Persistence
serialized = memory.dump() # Save to string
-memory.load(serialized) # Load from string
+memory.load(serialized) # Load from string
# Create copy
new_memory = memory.copy()
@@ -35,18 +39,33 @@ new_memory = memory.copy()
Key features:
- Message history management with role-based messages
- Turn-based conversation tracking
-- Support for multimodal content
-- Serialization and deserialization
+- Support for multimodal content (images, etc.)
+- Serialization and persistence
- Memory size management
- Deep copy functionality
-For full API details:
-```{eval-rst}
-.. automodule:: atomic_agents.lib.components.agent_memory
- :members:
- :undoc-members:
- :show-inheritance:
- :no-index: Message.role Message.content Message.turn_id
+### Message Structure
+
+Messages in memory are structured as:
+
+```python
+class Message(BaseModel):
+ role: str # e.g., 'user', 'assistant', 'system'
+ content: BaseIOSchema # Message content following schema
+ turn_id: Optional[str] # Unique ID for grouping messages
+```
+
+### Multimodal Support
+
+The memory system automatically handles multimodal content:
+
+```python
+# For content with images
+history = memory.get_history()
+for message in history:
+ if isinstance(message.content, list):
+ text_content = message.content[0] # JSON string
+ images = message.content[1:] # List of images
```
## System Prompt Generator
@@ -59,7 +78,7 @@ from atomic_agents.lib.components.system_prompt_generator import (
SystemPromptContextProviderBase
)
-# Create basic generator
+# Create generator with static content
generator = SystemPromptGenerator(
background=[
"You are a helpful AI assistant.",
@@ -81,49 +100,124 @@ generator = SystemPromptGenerator(
prompt = generator.generate_prompt()
```
-### Context Providers
+### Dynamic Context Providers
-Create custom context providers by extending `SystemPromptContextProviderBase`:
+Context providers inject dynamic information into prompts:
```python
-class CustomContextProvider(SystemPromptContextProviderBase):
+from dataclasses import dataclass
+from typing import List
+
+@dataclass
+class SearchResult:
+ content: str
+ metadata: dict
+
+class SearchResultsProvider(SystemPromptContextProviderBase):
def __init__(self, title: str):
super().__init__(title=title)
- self.data = {}
+ self.results: List[SearchResult] = []
def get_info(self) -> str:
- return f"Custom context: {self.data}"
+ """Format search results for the prompt"""
+ if not self.results:
+ return "No search results available."
+
+ return "\n\n".join([
+ f"Result {idx}:\nMetadata: {result.metadata}\nContent:\n{result.content}\n{'-' * 80}"
+ for idx, result in enumerate(self.results, 1)
+ ])
# Use with generator
generator = SystemPromptGenerator(
- background=["You are a helpful AI assistant."],
+ background=["You answer based on search results."],
context_providers={
- "custom": CustomContextProvider("Custom Info")
+ "search_results": SearchResultsProvider("Search Results")
}
)
```
+The generated prompt will include:
+1. Background information
+2. Processing steps (if provided)
+3. Dynamic context from providers
+4. Output instructions
+
+## Base Components
+
+### BaseIOSchema
+
+Base class for all input/output schemas:
+
+```python
+from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+from pydantic import Field
+
+class CustomSchema(BaseIOSchema):
+ """Schema description (required)"""
+ field: str = Field(..., description="Field description")
+```
+
+Key features:
+- Requires docstring description
+- Rich representation support
+- Automatic schema validation
+- JSON serialization
+
+### BaseTool
+
+Base class for creating tools:
+
+```python
+from atomic_agents.lib.base.base_tool import BaseTool, BaseToolConfig
+from pydantic import Field
+
+class MyToolConfig(BaseToolConfig):
+ """Tool configuration"""
+ api_key: str = Field(
+ default=os.getenv("API_KEY"),
+ description="API key for the service"
+ )
+
+class MyTool(BaseTool):
+ """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 tool logic
+ pass
+```
+
+Key features:
+- Structured input/output schemas
+- Configuration management
+- Title and description overrides
+- Error handling
+
For full API details:
```{eval-rst}
-.. automodule:: atomic_agents.lib.components.system_prompt_generator
+.. automodule:: atomic_agents.lib.components.agent_memory
:members:
:undoc-members:
:show-inheritance:
-```
-
-## Base Components
-```{eval-rst}
-.. automodule:: atomic_agents.lib.base.base_tool
+.. automodule:: atomic_agents.lib.components.system_prompt_generator
:members:
:undoc-members:
:show-inheritance:
- :no-index: BaseToolConfig.title BaseToolConfig.description BaseTool.input_schema BaseTool.output_schema
-```
-```{eval-rst}
.. automodule:: atomic_agents.lib.base.base_io_schema
:members:
:undoc-members:
:show-inheritance:
+
+.. automodule:: atomic_agents.lib.base.base_tool
+ :members:
+ :undoc-members:
+ :show-inheritance:
```