🚀 AstraAgent - Autonomous AI Agent Framework

AstraAgent is a state-of-the-art autonomous AI agent framework designed to accomplish complex tasks with minimal human intervention. It rivals industry-leading agents from Google and OpenAI, featuring a modular architecture, comprehensive tool system, and advanced memory management.

✨ Key Features

🧠 Autonomous Problem Solving

• OBSERVE → THINK → PLAN → ACT → REFLECT → ITERATE workflow
• Self-correcting behavior with error recovery
• Dynamic plan adjustment based on results

🔧 Comprehensive Tool System

• Shell: Execute system commands safely
• File System: Read, write, copy, delete files
• Python: Execute code in sandboxed environment
• Web Search: DuckDuckGo integration
• Web Fetch: Extract content from URLs
• Browser: Playwright-based automation
• Git: Repository management
• Memory: Persistent knowledge storage

🧬 Advanced Memory System

• Short-term, long-term, episodic, and semantic memory
• Automatic memory consolidation
• Similarity-based recall
• Persistent storage with auto-save

🛡️ Safety Guardrails

• Dangerous command blocking
• File extension restrictions
• Execution timeout limits
• Approval system for high-risk actions

🔌 Multi-Provider LLM Support

• Grok/xAI (grok-3, grok-3-fast, grok-3-mini) ⭐ NEW
• OpenAI (GPT-4, GPT-4o, GPT-3.5)
• Anthropic (Claude 3.5, Claude 3)
• Local models (Ollama, LM Studio)

📦 Installation

Quick Install

pip install -e .

Install via npm (global launcher)

npm install -g astraagent
astraagent setup
astraagent start -i

With All Features

pip install -e ".[all]"

Development Install

pip install -e ".[dev]"

Browser Automation (optional)

pip install playwright
playwright install chromium

🚀 Quick Start

Set Your API Key

# Grok/xAI (recommended)
set XAI_API_KEY=your-key-here          # Windows
export XAI_API_KEY=your-key-here       # Linux/Mac

# Or OpenAI
set OPENAI_API_KEY=your-key-here       # Windows
export OPENAI_API_KEY=your-key-here    # Linux/Mac

Run the Agent

# Quick start alias (interactive)
python main.py start -i

# Run agent with a goal
python main.py run "Create a Python script that generates prime numbers"

# Run in interactive mode
python main.py run -i

# List available tools
python main.py tools

# Interactive multi-provider chat
python main.py chat                    # Interactive selection
python main.py chat --list-providers   # Show available providers

# Update checker/auto updater
python main.py update --check
python main.py update --auto

###💬 Interactive Chat with Multiple LLM Providers

NEW: Chat with GPT-4, Claude, Gemini, Ollama, and more!

# Start interactive chat mode
python main.py chat

# List available providers
python main.py chat --list-providers

Supported providers:

• 🆓 Local - Ollama, LM Studio (free, self-hosted)
• OpenAI - GPT-4, GPT-4 Turbo, GPT-3.5
• Google Gemini - Gemini 2.0 Flash, 1.5 Pro/Flash
• Anthropic Claude - Claude 3.5 Sonnet, Claude 3 Opus
• OpenRouter - Access 100+ models in one place
• Groq - Fast inference (Mixtral, Llama, Gemma)

See CHAT_GUIDE.md for complete chat documentation.

Programmatic Usage

import asyncio
from astra import AstraAgent, AgentConfig

async def main():
    config = AgentConfig()
    config.llm.provider = "openai"
    config.llm.model = "gpt-4"
    
    agent = AstraAgent(config)
    result = await agent.run("Write a web scraper for news headlines")
    print(result)
    agent.shutdown()

asyncio.run(main())

🛠️ Available Tools

| Tool | Description | Risk Level | |------|-------------|------------| | shell | Execute shell commands | High | | read_file | Read file contents | Low | | write_file | Write/create files | Medium | | list_dir | List directory contents | Low | | python | Execute Python code | Medium | | web_search | Search the web | Low | | google_search | Search via Google | Low | | exa_search | Search via Exa API | Low | | web_search_multi | Multi-engine web search | Low | | web_fetch | Fetch URL content | Low | | browser | Browser automation | Medium | | git | Git operations | Medium | | memory | Store/recall information | Low |

⚙️ Configuration

Environment Variables

# API Keys (set one)
XAI_API_KEY=xai-...          # Grok/xAI API key (recommended)
OPENAI_API_KEY=sk-...        # OpenAI API key
ANTHROPIC_API_KEY=sk-ant-... # Anthropic API key
EXA_API_KEY=exa-...          # Exa search API key (optional)
GOOGLE_CSE_API_KEY=...       # Google Custom Search API key (optional)
GOOGLE_CSE_ID=...            # Google Custom Search engine ID (optional)

# Configuration
ASTRA_MODE=autonomous        # Execution mode
ASTRA_MODEL=grok-3          # LLM model
ASTRA_PROVIDER=grok         # LLM provider: grok, openai, anthropic, ollama
ASTRA_MAX_ITERATIONS=50     # Max agent iterations

Configuration File

from astra import AgentConfig

config = AgentConfig()
config.llm.provider = "grok"    # or "openai", "anthropic", "ollama"
config.llm.model = "grok-3"     # or "gpt-4", "claude-3-sonnet"
config.llm.temperature = 0.7
config.max_iterations = 100
config.workspace_path = "./workspace"
config.save("config.json")

📁 Project Structure

AstraAgent/
├── astra/
│   ├── __init__.py
│   ├── cli.py                 # Command-line interface
│   ├── core/
│   │   ├── agent.py           # Main agent class
│   │   ├── config.py          # Configuration system
│   │   ├── state.py           # State management
│   │   └── memory.py          # Memory system
│   ├── tools/
│   │   ├── base.py            # Tool framework
│   │   ├── shell.py           # Shell commands
│   │   ├── file.py            # File operations
│   │   ├── python.py          # Python execution
│   │   ├── web.py             # Web search/fetch
│   │   ├── browser.py         # Browser automation
│   │   ├── git.py             # Git operations
│   │   └── memory_tool.py     # Memory management
│   └── llm/
│       └── __init__.py        # LLM providers
├── main.py                    # Entry point
├── pyproject.toml             # Project config
└── README.md

🎯 Example Use Cases

1. Code Generation

python main.py run "Create a FastAPI REST API with user authentication"

2. Data Analysis

python main.py run "Analyze the CSV files in ./data and create a report"

3. Web Research

python main.py run "Research the latest AI developments and summarize in a report"

4. Automation

python main.py run "Set up a new Python project with pytest and CI/CD"

5. Documentation

python main.py run "Generate API documentation for the src/ folder"

🔒 Safety Features

• Command Blocking: Prevents rm -rf, format, and other dangerous commands
• Sandboxed Execution: Python code runs in restricted environment
• File Restrictions: Blocks writes to system directories
• Timeout Limits: Prevents infinite loops
• Approval Mode: Optional user confirmation for risky actions

🧪 Development

Run Tests

pytest tests/

Auto Update

python main.py update --check
python main.py update --auto

Format Code

black astra/
ruff check astra/ --fix

📊 Comparison

| Feature | AstraAgent | ChatGPT | Google Agent | |---------|------------|---------|--------------| | Autonomous Execution | ✅ | ❌ | ✅ | | Local File Access | ✅ | ❌ | ❌ | | Shell Commands | ✅ | ❌ | ❌ | | Browser Automation | ✅ | ❌ | ✅ | | Persistent Memory | ✅ | Limited | ❌ | | Self-Hosted | ✅ | ❌ | ❌ | | Multi-Provider LLM | ✅ | ❌ | ❌ | | Extensible Tools | ✅ | Via Plugins | ❌ |

📜 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Built with the power of modern LLMs and inspired by the vision of truly autonomous AI assistants.