ai-agent-deep-dive-teaching-framework

ai-agent-deep-dive-teaching-framework

Skill by ara.so — AI Agent Skills collection.

Overview

ai-agent-deep-dive is a teaching-focused Python project that demonstrates how to build a minimal AI Agent from scratch. It includes:

• A core Agent loop implementation
• A swappable LLM interface (currently using a fake LLM for teaching)
• A skill discovery and loading system
• CLI interface for interaction
• Educational documentation and reports on AI Agent architecture

The project is designed to keep complexity minimal while showing the essential components every AI Agent needs. It's ideal for learning agent architecture before building production systems.

Installation

The project uses Poetry for dependency management.

# Clone the repository
git clone https://github.com/tvytlx/ai-agent-deep-dive.git
cd ai-agent-deep-dive

# Install dependencies
poetry install

# Verify installation
poetry run agt --help

Core Architecture

The teaching agent consists of three main components:

1. Agent Core (src/agt/agent.py) - Main loop and execution logic
2. CLI Interface (src/agt/cli.py) - Command-line entry point
3. Skills System - Pluggable capabilities loaded from a skills directory

CLI Commands

Basic Usage

# Run agent with a simple query
poetry run agt "hello world"

# List available skills
poetry run agt --skills-dir ./skills --list-skills

# Specify custom skills directory
poetry run agt --skills-dir /path/to/skills "your query"

CLI Options

• query - The input query for the agent (positional argument)
• --skills-dir - Path to directory containing skill modules (default: ./skills)
• --list-skills - Display all discovered skills and exit

Code Examples

Basic Agent Usage

from agt.agent import Agent

# Initialize agent with default fake LLM
agent = Agent()

# Run agent with a query
response = agent.run("What can you help me with?")
print(response)

Understanding the Agent Loop

from agt.agent import Agent

# The agent loop follows this pattern:
# 1. Receive user input
# 2. Send to LLM (currently fake)
# 3. Stream response back
# 4. Execute any triggered skills

agent = Agent(skills_dir="./skills")
result = agent.run("Calculate 2+2")

Custom LLM Interface

The project uses a fake LLM for teaching. To replace with a real LLM:

from agt.agent import Agent

class RealLLM:
    """Replace the fake LLM with real API calls"""
    
    def __init__(self, api_key=None):
        self.api_key = api_key or os.getenv("OPENAI_API_KEY")
    
    def stream_response(self, prompt: str):
        """Stream tokens from real LLM"""
        # Implementation would call actual API
        # and yield tokens as they arrive
        pass

# Extend Agent class to use real LLM
class ProductionAgent(Agent):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.llm = RealLLM()

Creating Custom Skills

Skills are Python modules placed in the skills directory:

# skills/calculator.py

def add(a: int, b: int) -> int:
    """Add two numbers together"""
    return a + b

def multiply(a: int, b: int) -> int:
    """Multiply two numbers"""
    return a * b

# Skills metadata (optional)
SKILL_METADATA = {
    "name": "calculator",
    "description": "Basic arithmetic operations",
    "functions": ["add", "multiply"]
}

Programmatic Agent Interaction

from agt.agent import Agent
import os

# Initialize with environment configuration
agent = Agent(
    skills_dir=os.getenv("AGENT_SKILLS_DIR", "./skills")
)

# Process multiple queries
queries = [
    "Hello, what can you do?",
    "Calculate something",
    "List your capabilities"
]

for query in queries:
    print(f"\nUser: {query}")
    response = agent.run(query)
    print(f"Agent: {response}")

Configuration

Environment Variables

# Example .env file
AGENT_SKILLS_DIR=./skills
OPENAI_API_KEY=your-api-key-here  # For when you replace fake LLM
LOG_LEVEL=INFO

Agent Configuration

from agt.agent import Agent

agent = Agent(
    skills_dir="./custom_skills",  # Custom skills location
    verbose=True,                   # Enable detailed logging
    max_iterations=10               # Limit agent loop iterations
)

Project Structure

ai-agent-deep-dive/
├── src/
│   └── agt/
│       ├── agent.py      # Core agent implementation
│       ├── cli.py        # CLI entry point
│       └── __init__.py
├── skills/               # Skill modules directory
├── docs/                 # Teaching documentation
├── pyproject.toml       # Poetry dependencies
└── README.md

Common Patterns

Pattern 1: Agent with Skill Discovery

from agt.agent import Agent
import os

# Agent automatically discovers skills in directory
agent = Agent(skills_dir="./skills")

# Skills are loaded and available during agent execution
response = agent.run("Use available skills to help me")

Pattern 2: Streaming Response Handler

from agt.agent import Agent

agent = Agent()

# The fake LLM demonstrates streaming pattern
# Real implementation would stream from API
def handle_stream(query: str):
    for chunk in agent.stream_query(query):
        print(chunk, end="", flush=True)
    print()  # Newline after stream completes

Pattern 3: Extending the Agent

from agt.agent import Agent

class CustomAgent(Agent):
    """Extended agent with custom behavior"""
    
    def pre_process(self, query: str) -> str:
        """Custom preprocessing"""
        return query.strip().lower()
    
    def post_process(self, response: str) -> str:
        """Custom postprocessing"""
        return response.upper()
    
    def run(self, query: str) -> str:
        query = self.pre_process(query)
        response = super().run(query)
        return self.post_process(response)

Learning Resources

The repository includes extensive documentation:

• PDF Reports: Deep dive analysis of AI Agent architectures
  • ai-agent-deep-dive-v2.1.pdf - Includes memory systems chapter
  • ai-agent-deep-dive-v2.pdf - Core agent analysis
• Teaching Docs: /docs directory with architectural explanations

Troubleshooting

Skills Not Loading

# Verify skills directory exists and has valid Python modules
import os

skills_dir = "./skills"
if not os.path.exists(skills_dir):
    os.makedirs(skills_dir)

# List skills to debug
from agt.cli import main
# Run: poetry run agt --list-skills

Import Errors

# Ensure you're in the project directory
cd ai-agent-deep-dive

# Reinstall dependencies
poetry install

# Verify installation
poetry run python -c "from agt.agent import Agent; print('OK')"

Poetry Not Found

# Install poetry
curl -sSL https://install.python-poetry.org | python3 -

# Or via pip
pip install poetry

# Verify
poetry --version

Next Steps

This teaching framework uses a fake LLM to demonstrate structure. To build a production agent:

1. Replace the fake LLM with real API calls (OpenAI, Anthropic, etc.)
2. Implement proper error handling and retries
3. Add memory/context management
4. Enhance skill execution with function calling
5. Add logging and monitoring

Example Real LLM Integration:

import os
from openai import OpenAI

class OpenAILLM:
    def __init__(self):
        self.client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
    
    def stream_response(self, prompt: str):
        stream = self.client.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": prompt}],
            stream=True
        )
        for chunk in stream:
            if chunk.choices[0].delta.content:
                yield chunk.choices[0].delta.content

This teaching project provides the architectural foundation — real integrations follow the same patterns but with production-grade implementations.