Skip to content

Building AI agents, atomically

7.6 KB
Raw Blame

Context

For a comprehensive guide on memory management, multi-agent patterns, and best practices, see the **[Memory and Context Guide](/guides/memory)**.

Agent History

The ChatHistory class manages conversation history and state for AI agents. It implements BaseChatHistory, an interface-only abstract base class that declares the memory contract AtomicAgent depends on (the type AgentConfig.history accepts). Implement BaseChatHistory directly, or subclass ChatHistory, to plug in your own persistent or backend-specific memory store. See the Memory guide's "Writing a Custom Memory Backend" section for the full contract and a recommended pattern.

from atomic_agents.context import ChatHistory
from atomic_agents import BaseIOSchema

# Initialize history with optional max messages
history = ChatHistory(max_messages=10)

# Add messages
history.add_message(
    role="user",
    content=BaseIOSchema(...)
)

# Initialize a new turn
history.initialize_turn()
turn_id = history.get_current_turn_id()

# Access history
history = history.get_history()

# Manage history
history.get_message_count()  # Get number of messages
history.delete_turn_id(turn_id)  # Delete messages by turn

# Persistence
serialized = history.dump()  # Save to string
history.load(serialized)  # Load from string

# Create copy
new_history = history.copy()

Key features:

  • Message history management with role-based messages
  • Turn-based conversation tracking
  • Support for multimodal content (images, etc.)
  • Serialization and persistence
  • History size management
  • Deep copy functionality

Message Structure

Messages in history are structured as:

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 history system automatically handles multimodal content:

# For content with images
history = history.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

The SystemPromptGenerator creates structured system prompts for AI agents:

from atomic_agents.context import (
    SystemPromptGenerator,
    BaseDynamicContextProvider
)

# Create generator with static content
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()

Custom System Prompt Generator

If you require finer control over system prompt construction, subclass BaseSystemPromptGenerator and implement generate_prompt(). This approach is useful when prompt content should be maintained in a human-readable format (e.g., Markdown or text file) to allow review or editing by non-developers.

from pathlib import Path
from typing import Dict, Optional, Union

from atomic_agents.context import (
    BaseDynamicContextProvider, 
    BaseSystemPromptGenerator
)


class MarkdownFileSystemPromptGenerator(BaseSystemPromptGenerator):
    def __init__(
        self,
        md_file: Union[Path, str],
        context_providers: Optional[Dict[str, BaseDynamicContextProvider]] = None,
    ):
        super().__init__(context_providers=context_providers)

        path = Path(md_file)
        if not path.exists():
            raise FileNotFoundError(f"System prompt file not found: {md_file}")

        self.system_prompt = path.read_text(encoding="utf-8")

    def generate_prompt(self) -> str:
        return f"{self.system_prompt}\n\n{self._build_context_string()}"

    def _build_context_string(self) -> str:
        if not self.context_providers:
            return ""

        context_sections = ["# Additional Context"]
        for provider in self.context_providers.values():
            info = provider.get_info()
            if info:
                context_sections.append(f"## {provider.title}")
                context_sections.append(info)
                context_sections.append("")
        return "\n".join(context_sections).strip()

generator = MarkdownFileSystemPromptGenerator("path/to/system_prompt.md")
prompt = generator.generate_prompt()

Dynamic Context Providers

Context providers inject dynamic information into prompts:

from dataclasses import dataclass
from typing import List

@dataclass
class SearchResult:
    content: str
    metadata: dict

class SearchResultsProvider(BaseDynamicContextProvider):
    def __init__(self, title: str):
        super().__init__(title=title)
        self.results: List[SearchResult] = []

    def get_info(self) -> str:
        """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 answer based on search results."],
    context_providers={
        "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:

from atomic_agents 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:

from atomic_agents 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[MyToolInputSchema, MyToolOutputSchema]):
    """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:

.. automodule:: atomic_agents.context.chat_history
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: atomic_agents.context.base_chat_history
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: atomic_agents.context.system_prompt_generator
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: atomic_agents.base.base_io_schema
   :members:
   :undoc-members:
   :show-inheritance:

.. automodule:: atomic_agents.base.base_tool
   :members:
   :undoc-members:
   :show-inheritance: