Using LLM Agents

LLM (Large Language Model) agents are the most versatile agents in Atlas. They can understand natural language, reason through problems, generate content, and interact with tools. Let’s explore how to create and use them effectively.

Basic LLM Agent

Start with a simple LLM agent:

agents:
  assistant:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    purpose: "General purpose AI assistant"
    prompts:
      system: "You are a helpful AI assistant. Be concise and accurate."

This creates an agent that:

Uses Claude 3.5 Sonnet model
Has a clear purpose
Follows the system prompt instructions

Model Selection

Available Models

Atlas supports multiple AI providers: Anthropic Claude:

# Fast, efficient
model: "claude-3-5-haiku-20241022"

# Balanced performance (recommended)
model: "claude-3-5-sonnet-20241022"

# Maximum capability
model: "claude-3-5-opus-20241022"

OpenAI GPT:

# Fast, cost-effective
model: "gpt-3.5-turbo"

# High performance
model: "gpt-4"

# Latest and greatest
model: "gpt-4-turbo"

Other Providers:

# Google
model: "gemini-pro"

# Mistral
model: "mistral-medium"

# Local models (with Ollama)
model: "ollama:llama2"

Choosing the Right Model

Consider these factors:

Use Case	Recommended Model	Why
Simple tasks	Haiku/GPT-3.5	Fast, cost-effective
General purpose	Sonnet/GPT-4	Balanced performance
Complex reasoning	Opus/GPT-4-Turbo	Maximum capability
Code generation	Sonnet/GPT-4	Strong coding ability
Creative writing	Sonnet/GPT-4	Good creativity
Local/Private	Ollama models	Data stays local

Advanced Configuration

Full Configuration Example

agents:
  analyzer:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    description: "Data analysis specialist"
    purpose: "Analyze datasets and provide insights"
    
    # Prompts
    prompts:
      system: |
        You are a data analysis expert with skills in:
        - Statistical analysis
        - Pattern recognition
        - Data visualization recommendations
        - Business insights
        
        Always provide clear, actionable insights.
      
      # Optional user prompt template
      user: |
        Analyze the following data:
        {input}
        
        Focus on: {analysis_focus}
    
    # Model parameters
    config:
      temperature: 0.3          # 0-1, lower = more focused
      max_tokens: 2000         # Maximum response length
      top_p: 0.9              # Nucleus sampling
      frequency_penalty: 0.1   # Reduce repetition
      presence_penalty: 0.1    # Encourage topic diversity
      
      # Operational settings
      timeout: "120s"          # Maximum execution time
      retry_on_failure: true   # Retry on errors
      max_retries: 3          # Number of retries
      
      # Provider-specific settings
      provider: "anthropic"    # or "openai", "google", etc.
      api_key_env: "ANTHROPIC_API_KEY"  # Environment variable

Prompt Engineering

System Prompts

The system prompt defines your agent’s personality and capabilities:

prompts:
  system: |
    # Role Definition
    You are a senior software architect with 15 years of experience.
    
    # Expertise Areas
    - System design and architecture
    - Performance optimization
    - Security best practices
    - Team leadership
    
    # Communication Style
    - Be direct and practical
    - Use examples to illustrate points
    - Acknowledge tradeoffs in decisions
    - Ask clarifying questions when needed
    
    # Output Format
    - Start with a brief summary
    - Use bullet points for clarity
    - Include code examples when relevant
    - End with actionable next steps

Dynamic Prompts

Use variables in prompts:

prompts:
  system: |
    You are a {role} specializing in {domain}.
    Current date: {current_date}
    User context: {user_context}
  
  user: |
    Task: {task}
    Additional requirements: {requirements}
    Expected format: {output_format}

Pass variables during execution:

jobs:
  analyze:
    execution:
      agents:
        - id: "analyzer"
          input_template:
            role: "financial analyst"
            domain: "cryptocurrency markets"
            task: "{signal.data.task}"

Prompt Patterns

1. Role-Based Pattern

system: |
  You are a [SPECIFIC ROLE] with expertise in [DOMAINS].
  Your responsibilities include [TASKS].
  Always [BEHAVIORS] and never [CONSTRAINTS].

2. Chain-of-Thought Pattern

system: |
  When solving problems:
  1. First, understand the requirements
  2. Break down the problem into steps
  3. Think through each step carefully
  4. Check your work
  5. Provide a clear solution

3. Few-Shot Pattern

system: |
  Here are examples of good responses:
  
  Example 1:
  Input: [SAMPLE INPUT]
  Output: [SAMPLE OUTPUT]
  
  Example 2:
  Input: [SAMPLE INPUT]
  Output: [SAMPLE OUTPUT]
  
  Follow these patterns in your responses.

Working with Tools

Enabling Tools

Give your LLM agents access to tools:

agents:
  researcher:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    tools: ["web-search", "calculator", "file-reader"]
    
    prompts:
      system: |
        You have access to tools. Use them when needed:
        - web-search: For current information
        - calculator: For precise calculations
        - file-reader: To analyze documents

Tool Selection Strategy

Configure how agents choose tools:

config:
  tool_choice: "auto"     # Let the model decide
  # tool_choice: "none"   # Disable tools
  # tool_choice: "required" # Must use a tool
  # tool_choice: {"name": "web-search"} # Force specific tool

Custom Tool Integration

Define MCP tools for agents:

tools:
  mcp:
    servers:
      data-analyzer:
        transport:
          type: "stdio"
          command: "python"
          args: ["analyzer_server.py"]

agents:
  analyst:
    type: "llm"
    tools: ["data-analyzer"]

Context Management

Memory Integration

Enable memory for context awareness:

agents:
  assistant:
    type: "llm"
    config:
      memory_enabled: true
      memory_scope: "workspace"  # or "session", "agent"
      context_window: 10         # Recent memories to include
      
      # Memory types to access
      memory_types:
        - "episodic"    # Past events
        - "semantic"    # Learned facts
        - "procedural"  # How-to knowledge

Context Windows

Manage input context effectively:

config:
  # Maximum input tokens
  max_input_tokens: 8000
  
  # Context prioritization
  context_strategy: "recent_first"  # or "relevance_based"
  
  # Truncation handling
  truncation: "smart"  # Intelligently truncate long inputs

Performance Optimization

Response Speed

Optimize for faster responses:

agents:
  quick-responder:
    type: "llm"
    model: "claude-3-5-haiku-20241022"  # Faster model
    config:
      max_tokens: 500      # Shorter responses
      temperature: 0.3     # More focused
      stream: true         # Stream responses
      cache_enabled: true  # Cache common queries

Cost Management

Control API costs:

config:
  # Token limits
  max_tokens: 1000
  max_input_tokens: 2000
  
  # Smart routing
  fallback_model: "claude-3-5-haiku-20241022"
  complexity_threshold: 0.7  # Use smaller model below threshold
  
  # Caching
  cache_ttl: "3600s"  # 1 hour cache
  cache_key_fields: ["task", "input_type"]

Batch Processing

Handle multiple items efficiently:

agents:
  batch-processor:
    type: "llm"
    config:
      batch_size: 5
      parallel_processing: true
      
    prompts:
      system: |
        Process multiple items efficiently.
        Provide structured output for each.

Error Handling

Graceful Failures

Configure robust error handling:

config:
  # Retry configuration
  retry_on_failure: true
  max_retries: 3
  retry_delay: "2s"
  exponential_backoff: true
  
  # Fallback behavior
  fallback_strategy: "simplified_prompt"
  fallback_model: "claude-3-5-haiku-20241022"
  
  # Error responses
  error_handling:
    timeout: "Return partial results if available"
    api_error: "Retry with fallback model"
    validation_error: "Request clarification"

Validation

Ensure quality outputs:

agents:
  validator:
    type: "llm"
    config:
      # Output validation
      output_schema:
        type: "object"
        properties:
          summary: { type: "string" }
          details: { type: "array" }
          confidence: { type: "number" }
      
      # Retry on validation failure
      validate_output: true
      max_validation_retries: 2

Common Patterns

1. The Analyst Pattern

agents:
  analyst:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    purpose: "Analyze data and provide insights"
    prompts:
      system: |
        Analyze data with this structure:
        1. Overview - What the data shows
        2. Key Findings - Important discoveries
        3. Patterns - Trends and correlations
        4. Recommendations - Actionable insights
        5. Confidence - How certain you are
    config:
      temperature: 0.2  # Analytical precision

2. The Creator Pattern

agents:
  creator:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    purpose: "Generate creative content"
    prompts:
      system: |
        You are a creative writer who:
        - Generates original, engaging content
        - Adapts tone to the audience
        - Uses vivid, descriptive language
        - Maintains consistency in style
    config:
      temperature: 0.8  # More creativity

3. The Coder Pattern

agents:
  coder:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    purpose: "Write and review code"
    prompts:
      system: |
        You are an expert programmer who:
        - Writes clean, maintainable code
        - Follows best practices and patterns
        - Includes helpful comments
        - Considers edge cases
        - Provides test examples
    config:
      temperature: 0.3
      max_tokens: 3000  # Longer for code

4. The Teacher Pattern

agents:
  teacher:
    type: "llm"
    model: "claude-3-5-sonnet-20241022"
    purpose: "Educate and explain concepts"
    prompts:
      system: |
        You are a patient teacher who:
        - Explains complex topics simply
        - Uses analogies and examples
        - Checks understanding
        - Provides exercises
        - Encourages questions
    config:
      temperature: 0.5

Testing LLM Agents

Unit Testing

Test individual agents:

# test-config.yml
test_cases:
  - agent: "analyzer"
    input: "Sample data"
    expected_contains: ["summary", "findings"]
    max_tokens: 500

Integration Testing

Test agents in workflows:

# Test with specific input
atlas signal trigger test-analysis --data '{
  "test_case": "edge_case_1",
  "input": "unusual data format"
}'

Performance Testing

Monitor agent performance:

config:
  metrics_enabled: true
  track_metrics:
    - "response_time"
    - "token_usage"
    - "tool_calls"
    - "cache_hits"

Best Practices

1. Start Simple

Begin with basic configuration and add complexity as needed.

2. Test Prompts

Iterate on prompts with real examples to refine behavior.

3. Monitor Costs

Track token usage and optimize expensive operations.

4. Use Appropriate Models

Match model capability to task complexity.

5. Handle Edge Cases

Plan for unexpected inputs and errors.

6. Document Purpose

Clear documentation helps maintain and share agents.

Working with Agents

Workspace Configuration

Tutorials

​Using LLM Agents

​Basic LLM Agent

​Model Selection

​Available Models

​Choosing the Right Model

​Advanced Configuration

​Full Configuration Example

​Prompt Engineering

​System Prompts

​Dynamic Prompts

​Prompt Patterns

​Working with Tools

​Enabling Tools

​Tool Selection Strategy

​Custom Tool Integration

​Context Management

​Memory Integration

​Context Windows

​Performance Optimization

​Response Speed

​Cost Management

​Batch Processing

​Error Handling

​Graceful Failures

​Validation

​Common Patterns

​1. The Analyst Pattern

​2. The Creator Pattern

​3. The Coder Pattern

​4. The Teacher Pattern

​Testing LLM Agents

​Unit Testing

​Integration Testing

​Performance Testing

​Best Practices

​1. Start Simple

​2. Test Prompts

​3. Monitor Costs

​4. Use Appropriate Models

​5. Handle Edge Cases

​6. Document Purpose

​Next Steps