Chat Assistant

Build an interactive AI chat assistant with Atlas

Chat Assistant Tutorial

Learn how to build an interactive AI chat assistant using Atlas’s ConversationAgent. This tutorial will teach you how to create a conversational AI that maintains context and can help with various tasks.

What You’ll Build

An AI chat assistant that can:

• 🗣️ Have natural conversations
• 🧠 Remember context within sessions
• 🛠️ Use tools to help with tasks
• 📝 Provide helpful responses

Prerequisites

• Atlas installed and daemon running
• Basic understanding of workspace.yml
• Completed the Hello World Tutorial

Step 1: Create the Workspace

mkdir chat-assistant
cd chat-assistant
atlas init "Chat Assistant"

Step 2: Configure the ConversationAgent

Edit workspace.yml:

version: "1.0"

workspace:
  name: "chat-assistant"
  description: "Interactive AI chat assistant"

agents:
  assistant:
    type: "system"
    agent: "conversation"
    config:
      model: "claude-3-5-sonnet-20241022"
      system_prompt: |
        You are a helpful AI assistant named Atlas. You're knowledgeable,
        friendly, and eager to help with any questions or tasks.
        
        Your capabilities include:
        - Answering questions on a wide range of topics
        - Helping with analysis and problem-solving
        - Providing coding assistance
        - General conversation and support
        
        Always be concise but thorough, and ask clarifying questions when needed.
      
      # Enable conversation features
      memory_enabled: true
      streaming: true
      max_conversation_length: 50

signals:
  chat:
    provider: "cli"
    description: "Start a chat conversation"
    schema:
      type: "object"
      properties:
        message:
          type: "string"
        conversation_id:
          type: "string"
          description: "Optional ID to continue a conversation"

jobs:
  chat-session:
    triggers:
      - signal: "chat"
    execution:
      agents:
        - id: "assistant"
          input_source: "signal"

Step 3: Test Basic Chat

Start a conversation:

atlas signal trigger chat --data '{"message": "Hello! What can you help me with?"}'

Step 4: Add Conversation Continuity

Continue the same conversation by including a conversation ID:

# First message
atlas signal trigger chat --data '{
  "message": "My name is Alice and I need help planning a trip to Japan",
  "conversation_id": "trip-planning-123"
}'

# Follow-up message (assistant remembers you're Alice)
atlas signal trigger chat --data '{
  "message": "What cities should I visit?",
  "conversation_id": "trip-planning-123"  
}'

Step 5: Add Tools

Give your assistant capabilities:

agents:
  assistant:
    type: "system"
    agent: "conversation"
    config:
      model: "claude-3-5-sonnet-20241022"
      system_prompt: |
        You are a helpful AI assistant with access to tools.
        Use them when appropriate to provide better assistance.
      
      # Add tools
      tools: ["web-search", "calculator", "weather"]
      
      # Other settings...

tools:
  mcp:
    servers:
      web-search:
        transport:
          type: "stdio"
          command: "mcp-websearch"
        env:
          SEARCH_API_KEY: "${SEARCH_API_KEY}"
      
      calculator:
        transport:
          type: "stdio"
          command: "mcp-calculator"
      
      weather:
        transport:
          type: "http"
          url: "https://weather-api.example.com/mcp"
        config:
          units: "metric"

Now test with tools:

atlas signal trigger chat --data '{
  "message": "What's the weather like in Tokyo?",
  "conversation_id": "trip-planning-123"
}'

Step 6: Add Reasoning

Enable step-by-step reasoning for complex queries:

config:
  # Enable reasoning
  use_reasoning: true
  max_reasoning_steps: 15
  
  # Show reasoning to user (optional)
  show_reasoning: false

Test with a complex question:

atlas signal trigger chat --data '{
  "message": "Help me plan a 7-day itinerary for Japan on a budget",
  "conversation_id": "trip-planning-123"
}'

Step 7: Create a Chat Interface

For a better experience, create a simple chat loop script:

#!/usr/bin/env python3
# chat.py

import subprocess
import json
import uuid

conversation_id = str(uuid.uuid4())
print(f"Chat session started (ID: {conversation_id})")
print("Type 'exit' to quit\n")

while True:
    message = input("You: ")
    if message.lower() == 'exit':
        break
    
    # Trigger Atlas
    data = json.dumps({
        "message": message,
        "conversation_id": conversation_id
    })
    
    result = subprocess.run(
        ["atlas", "signal", "trigger", "chat", "--data", data],
        capture_output=True,
        text=True
    )
    
    print("Assistant:", result.stdout)
    print()

Make it executable and run:

chmod +x chat.py
./chat.py

Advanced Features

Custom Personalities

Create different assistant personalities:

agents:
  technical-assistant:
    type: "system"
    agent: "conversation"
    config:
      system_prompt: |
        You are a technical assistant specializing in software development.
        Focus on providing code examples, technical explanations, and best practices.
  
  creative-assistant:
    type: "system"
    agent: "conversation"
    config:
      system_prompt: |
        You are a creative writing assistant. Help with storytelling,
        character development, and creative ideas. Be imaginative!
      temperature: 0.8  # Higher for creativity

Integration with Slack

Add a Slack webhook signal:

signals:
  slack-chat:
    provider: "webhook"
    description: "Chat via Slack"
    config:
      path: "/webhooks/slack"
      auth:
        type: "secret"
        header: "X-Slack-Signature"

Session Analytics

Track conversation metrics:

jobs:
  chat-session:
    config:
      metrics:
        enabled: true
        track:
          - message_count
          - response_time
          - tool_usage
          - user_satisfaction

Best Practices

1. Clear System Prompts: Define the assistant’s role and capabilities clearly
2. Appropriate Models: Use Haiku for simple chats, Sonnet for complex assistance
3. Memory Management: Set reasonable conversation length limits
4. Tool Selection: Only include tools the assistant actually needs
5. Error Handling: Provide fallback responses for tool failures

Troubleshooting

Assistant Not Responding

• Check Atlas daemon is running
• Verify API keys are set
• Check logs: atlas logs <session-id>

Lost Context

• Ensure conversation_id is consistent
• Check memory_enabled is true
• Verify conversation hasn’t exceeded max_length

Slow Responses

• Consider using streaming
• Use a faster model (Haiku)
• Check tool timeout settings

Next Steps

• Add more specialized tools
• Create multiple assistant personalities
• Build a web interface
• Integrate with messaging platforms
• Try the Automated Tasks Tutorial

Complete Code