Building AI agents, atomically
Update BaseAgent and components documentation
KennyVaneetvelde516f7311c025
diff --git a/docs/api/agents.md b/docs/api/agents.mdindex 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 OpenAIfrom atomic_agents.agents.base_agent import BaseAgent, BaseAgentConfigfrom 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.mdindex 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 messagesmemory = AgentMemory(max_messages=10)-# Add messages with proper schemas+# Add messagesmemory.add_message(- role="assistant",+ role="user",content=BaseIOSchema(...))+# Initialize a new turn+memory.initialize_turn()+turn_id = memory.get_current_turn_id()+# Access historyhistory = 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# Persistenceserialized = memory.dump() # Save to string-memory.load(serialized) # Load from string+memory.load(serialized) # Load from string# Create copynew_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 contentgenerator = 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 generatorgenerator = 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:```