🧠 Learning Agent

A sophisticated autonomous agent system that learns from experience, orchestrates parallel task execution, and adapts its behavior based on past successes and failures.

✨ Features

• 🎭 DeepAgents Framework: Built on the upstream deepagents project for sophisticated agent orchestration, including subagents with their own graphs
• 🐘 PostgreSQL Vector Storage: Production-ready vector database with pgvector for semantic memory search
• 🔄 Multi-Dimensional Learning: Captures tactical, strategic, and meta-level insights from every execution
• 🧠 Context-Aware Learning Retrieval: Synthesizes conversation context for intelligent learning search in multi-turn conversations
• ⚡ Parallel Sub-Agents: Specialized sub-agent for research tasks (research-agent)
• 🐍 Python Sandbox: Secure code execution with Pyodide WebAssembly environment
• 📊 Visualization Support: Automatic capture of matplotlib plots, PIL images, and pandas DataFrames
• 🌐 REST API Server: FastAPI endpoints for memory retrieval and pattern analysis (port 8001)
• 📝 Narrative Memory: Creates human-readable narratives of experiences with deep reflection
• 🔍 Execution Analysis: Automatic detection of inefficiencies, redundancies, and optimization opportunities
• 🗂️ Virtual File System: Safe file operations through deepagents' virtual filesystem
• 📊 LangSmith Integration: Complete observability of agent execution and learning processes
• 🖥️ Web UI: React-based interface for visual interaction with the agent (port 10300)

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• uv package manager (recommended) or pip
• OpenAI API key or other supported LLM provider
• Docker and Docker Compose (for UI)

Installation

# Clone the repository
git clone https://github.com/johannhartmann/learning-agent.git
cd learning-agent

# Install with uv (recommended)
uv sync --all-extras

# Or install with pip
pip install -e ".[dev]"

# Copy environment variables
cp .env.example .env
# Edit .env and add your API keys

Basic Usage

import asyncio
from learning_agent.agent import create_learning_agent

async def main():
    # Create the learning agent
    agent = create_learning_agent()

    # Process a task - the agent will plan, execute, and learn
    state = {"messages": [{"role": "user", "content":
        "Create a Python function to calculate fibonacci numbers and test it"}]}
    result = await agent.ainvoke(state)

    # Extract the last message as the summary
    if result.get("messages"):
        last_msg = result["messages"][-1]
        print(f"Result: {last_msg.content if hasattr(last_msg, 'content') else last_msg}")

    # The agent has now learned from this experience
    # Future similar tasks will be executed more efficiently

asyncio.run(main())

🖥️ Web UI

The Learning Agent includes a React-based web UI for visual interaction with the agent system.

Quick Start

# Build and start all services (PostgreSQL, API server, LangGraph server, UI)
docker compose up -d

# Or use the Make command
make docker-up

# Access the services:
# - Web UI: http://localhost:10300
# - LangGraph Server: http://localhost:2024
# - API Server: http://localhost:8001
# - PostgreSQL: localhost:5433

Docker Compose Commands

# Start all services (PostgreSQL, API Server, LangGraph Server, UI)
docker compose up -d

# Start specific services
docker compose up -d postgres  # Just database
docker compose up -d server    # LangGraph + API server
docker compose up -d ui        # Just UI

# View logs
docker compose logs -f        # All services
docker compose logs -f postgres  # Specific service

# Stop services
docker compose down

# Stop and remove volumes (caution: deletes data)
docker compose down -v

# Rebuild images
docker compose build

# Or use Make commands (wrapper around docker compose)
make docker-build   # Build images
make docker-up      # Start all services
make docker-logs    # View logs
make docker-down    # Stop services
make docker-clean   # Clean up including volumes

Using the DeepAgents API Directly

from learning_agent.agent import create_learning_agent
from learning_agent.state import LearningAgentState

# Create a deepagents-based learning agent
agent = create_learning_agent()

# Create initial state
initial_state: LearningAgentState = {
    "messages": [{"role": "user", "content": "Your task here"}],
    "todos": [],
    "files": {},
    "memories": [],
}

# Execute task
result = await agent.ainvoke(initial_state)

🐍 Python Sandbox

The agent includes a secure Python sandbox powered by Pyodide (Python compiled to WebAssembly) for safe code execution:

# The agent can execute Python code safely
state = {"messages": [{"role": "user", "content":
    "Analyze this data and create a visualization: [1,2,3,4,5]"}]}
result = await agent.ainvoke(state)

# The sandbox supports:
# - Data analysis with pandas, numpy, scipy
# - Matplotlib visualizations (captured as base64 images)
# - PIL/Pillow image processing
# - Stateful execution (variables persist between calls)
# - Package installation from PyPI (with allow_network=True)

Sandbox Features:

• Isolated Execution: Runs in WebAssembly environment, isolated from host system
• Visualization Capture: Automatically captures matplotlib plots and PIL images as base64
• Data Analysis: Pre-loaded with pandas, numpy, and scientific computing libraries
• Stateful Sessions: Variables and imports persist across multiple executions
• Safe Testing: Test algorithms and logic before writing to files

🏗️ Architecture

The Learning Agent combines DeepAgents framework with PostgreSQL vector storage, API server, and web UI:

graph TD
    UI[React Web UI] -->|HTTP| API[FastAPI Server :8001]
    UI -->|WebSocket| Server[LangGraph Server :2024]

    CLI[CLI Interface] --> Agent[DeepAgents Agent]
    Server --> Agent

    Agent --> Tools[Core Tools]
    Agent --> SubAgents[Sub-Agents via Task Tool]

    Tools --> PT[Planning Tool - write_todos]
    Tools --> FS[File System - read/write/edit]
    Tools --> PS[Python Sandbox - code execution]

    SubAgents --> ES[execution-specialist]
    SubAgents --> RS[research-agent]

    Agent -->|Background Learning| NL[NarrativeLearner]
    NL -->|Stores| PG[(PostgreSQL + pgvector :5433)]

    API -->|Queries| PG
    LT -->|Search| PG

    PG -->|Stores| Memories[Multi-Dimensional Memories]
    PG -->|Stores| Patterns[Execution Patterns]
    PG -->|Stores| Embeddings[Vector Embeddings]

Loading

Core Components

• React Web UI (Port 10300): TypeScript-based interface for visual interaction
• FastAPI Server (Port 8001): REST API for memory retrieval and pattern analysis
• LangGraph Server (Port 2024): Serves the agent as an API endpoint
• PostgreSQL + pgvector (Port 5433): Production-ready vector database for semantic search
• DeepAgents Agent: Core agent built with create_deep_agent() that directly integrates learning. The research workflow is implemented as a dedicated subagent graph that streams atomic browser actions.

Browser Research (Playwright + MCP)

• The agent exposes browser tools via an MCP stdio server implemented with Playwright (no browser-use dependency). Subagents rely on research_extract_structured_data to fetch filtered, paginated HTML snippets instead of streaming entire pages.
• The main agent is restricted from calling these tools directly; browsing is delegated via task(agent_name="research-agent") to a dedicated subagent graph.
• Each tool returns a small JSON payload with action, status, and url so the UI can stream per-step provenance.
• When running custom scripts, call await shutdown_mcp_browser() (or shutdown_mcp_browser_sync()) during teardown to close the shared Playwright session cleanly.

Enable in Docker using the browser extra (already installed in Dockerfile.server). Configure via .env:

• BROWSER_HEADLESS=true
• BROWSER_VIEWPORT_WIDTH=1280, BROWSER_VIEWPORT_HEIGHT=720
• Python Sandbox: Pyodide-based WebAssembly environment for safe code execution with visualization support
• NarrativeLearner: Background processor that converts conversations into multi-dimensional learnings
• Specialized Sub-Agents: Four agents for different execution aspects
• Learning-aware Orchestration: Learning happens automatically after each run; no dedicated learning tools are exposed to the agent

🌐 API Server

The FastAPI server provides a REST endpoint for accessing consolidated memories:

Endpoint

• GET /learnings - Retrieve persisted learnings for the UI dashboard

Example Usage

# Get recent learnings used by the UI polling hook
curl http://localhost:8001/learnings

🧪 Testing

The project includes comprehensive test coverage with CI/CD integration:

# Run all tests
make test

# Run specific test categories
make test-unit          # Unit tests
make test-integration   # Integration tests

# Run with coverage
make test-coverage

# Type checking
make typecheck

# Linting
make lint

CI/CD Pipeline

• GitHub Actions: Automated testing on every push
• Test Matrix: Python 3.11 and 3.12
• Quality Checks: Linting, type checking, security scanning
• Coverage: Unit tests with pytest-cov
• API Key Safety: Tests skip when API keys unavailable

📊 Observability

The agent provides full observability through LangSmith:

1. Trace Every Decision: Complete visibility into planning and execution
2. Learning Metrics: Track memory extraction volume and confidence
3. Performance Monitoring: Latency, token usage, and cost tracking
4. Anomaly Detection: Automatic detection of behavioral changes

Configure LangSmith in your .env:

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=your_api_key
LANGSMITH_PROJECT=learning-agent

🛠️ Development

Setup Development Environment

# Install development dependencies
make install-dev

# Install pre-commit hooks
make pre-commit-install

# Run all quality checks
make check

Available Commands

make help              # Show all available commands
make test             # Run tests
make lint             # Run linting
make format           # Format code
make typecheck        # Type checking
make security         # Security scan
make deadcode         # Find unused code

Code Quality

• Linting: Ruff with extensive rule set
• Type Checking: Strict mypy configuration
• Security: Bandit for security issues
• Dead Code: Vulture for unused code detection
• Coverage: Pytest-cov with 52% traditional coverage + LangSmith probabilistic testing

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (make test-all)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📚 Documentation

• Learning System Architecture - Deep dive into how the agent captures, stores, and retrieves knowledge
• Testing Strategy
• Contributing Guidelines

🐘 PostgreSQL Vector Storage

The Learning Agent uses PostgreSQL with pgvector extension for production-ready vector storage:

Features

• Multi-Dimensional Learning Storage: Stores tactical, strategic, and meta-level insights
• Semantic Search: Vector similarity search for finding relevant past experiences
• Execution Metadata Capture: Tracks tool usage, efficiency scores, and anti-patterns alongside each memory
• Scalable: Production-ready database that can handle millions of memories

Every new request runs a quick similarity search so the agent receives a system message summarizing the most relevant prior learnings, helping it avoid repeating past mistakes.

The system uses intelligent context synthesis:

• First message in a thread: Uses the raw user message as the search query (fast, no extra LLM call)
• Follow-up messages: Synthesizes the overall task from conversation history using LLM
• Example: "add colors" in a Snake game conversation becomes "add colors to the Snake game" for more relevant learning retrieval

Database Schema

• Memories Table: Stores conversation memories with embeddings
• Execution Metadata: Stores tool sequences, timings, and efficiency metrics for each memory

Connection

DATABASE_URL=postgresql://learning_agent:learning_agent_pass@localhost:5433/learning_memories

🔧 Configuration

The agent is highly configurable through environment variables:

# LLM Configuration
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini
LLM_TEMPERATURE=0.7

# API Keys
OPENAI_API_KEY=your_api_key
ANTHROPIC_API_KEY=your_api_key  # Optional
LANGSMITH_API_KEY=your_api_key

# Database Configuration
DATABASE_URL=postgresql://learning_agent:learning_agent_pass@localhost:5433/learning_memories

# Learning Configuration
ENABLE_LEARNING=true
LEARNING_CONFIDENCE_THRESHOLD=0.9
PATTERN_RETENTION_DAYS=90

# Performance
MAX_PARALLEL_AGENTS=10
TASK_TIMEOUT_SECONDS=300

# Embedding Configuration
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small

See .env.example for all options.

🚦 Project Status

This project is in active development.

✅ Completed Features

• PostgreSQL vector storage with pgvector
• Multi-dimensional learning extraction (tactical, strategic, meta)
• Web UI with React/TypeScript
• REST API for memory access
• Python sandbox with Pyodide for safe code execution
• Automatic visualization capture (matplotlib, PIL, pandas)
• Execution pattern analysis
• Support for multiple LLM providers (OpenAI, Anthropic, Ollama, etc.)
• CI/CD pipeline with GitHub Actions

🔥 Recent Improvements

• Context-aware learning retrieval with conversation synthesis
• Fixed research-agent infinite recursion by removing unnecessary research_done tool
• Updated all npm dependencies to fix CVE-2025-57319

🚧 In Progress

• Long-term memory consolidation
• Advanced pattern recognition algorithms
• Collaborative multi-agent learning
• Memory pruning and optimization
• Real-time learning dashboard

📝 License

License to be determined.

🙏 Acknowledgments

Built with:

• LangChain - LLM orchestration
• LangGraph - State machine orchestration
• LangSmith - Observability and testing
• Rich - Terminal UI

📬 Contact

Johann Hartmann - @johannhartmann

Project Link: https://github.com/johannhartmann/learning-agent