agenticstack 0.1.0

The WordPress of AI Agents - A modular, lightweight agentic framework

🤖 AgentStack

The WordPress of AI Agents - A modular, lightweight, plugin-first agentic framework that makes building AI agents as easy as WordPress makes building websites.

✨ Features

• 🧩 Modular Architecture - Plug-and-play components for skills, tools, memory, and more
• 🔌 Plugin System - Extend functionality with WordPress-style plugins
• 🧠 Multi-Type Memory - Conversation, long-term, semantic, and composite memory
• 📊 Graph Workflows - Visual, state-based workflow orchestration
• 🔍 RAG Pipeline - Built-in retrieval-augmented generation with reranking
• 👥 Human-in-the-Loop - Approval workflows, feedback, and intervention points
• 🤱 Mother Agent - AI-powered assistant to help you build agents
• 🔧 12+ LLM Providers - OpenAI, Anthropic, Google, Azure, and more
• 📝 Type-Safe - Full type hints and validation

🚀 Quick Start

Installation

pip install agentstack

Create Your First Agent

from agentstack import Agent, skill
from agentstack.memory import ConversationMemory

@skill(id="greet", description="Greet the user")
async def greet(name: str = "friend") -> str:
    return f"Hello, {name}! How can I help you today?"

agent = Agent(
    name="GreeterBot",
    skills=[greet],
    memory=ConversationMemory(),
    model="gpt-4"
)

# Run interactively
agent.run()

Using the CLI

# Create a new project
stack init my-agent

# Run your agent
cd my-agent
stack run

# Get help from Mother Agent
stack mother

📖 Documentation

Core Concepts

Concept	Description
Agent	The main entity that processes requests
Skills	Capabilities your agent can use
Tools	External integrations (web, files, code)
Memory	Context and conversation history
Workflows	Multi-step process orchestration

Modules

• Memory - Conversation, buffer, window, long-term, composite
• RAG - Document loading, chunking, retrieval, reranking
• Tools - Built-in and custom tools
• Workflows - State graphs and execution
• HITL - Human-in-the-loop patterns
• Plugins - Creating and using plugins

Guides

• Getting Started
• Building Your First Agent
• Adding Memory
• Using Tools
• Creating Workflows
• RAG Implementation
• Multi-Agent Systems
• Plugin Development

🧱 Architecture

┌─────────────────────────────────────────────────────────────┐
│                         AgentStack                          │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   Agent     │  │  MultiAgent │  │   Mother    │          │
│  │             │  │   System    │  │   Agent     │          │
│  └──────┬──────┘  └──────┬──────┘  └─────────────┘          │
│         │                │                                  │
│  ┌──────┴────────────────┴──────────────────────────────┐   │
│  │                    Core Modules                      │   │
│  ├──────────┬──────────┬──────────┬──────────┬──────────┤   │
│  │  Skills  │  Tools   │  Memory  │Workflows │   RAG    │   │
│  └──────────┴──────────┴──────────┴──────────┴──────────┘   │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                  Foundation Layer                    │   │
│  ├─────────┬─────────┬─────────┬─────────┬──────────────┤   │
│  │ Kernel  │ Vectors │ Tracing │ Guards  │Orchestrate   │   │
│  └─────────┴─────────┴─────────┴─────────┴──────────────┘   │
│                                                             │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                   LLM Providers                        │ │
│  ├────────┬──────────┬────────┬────────┬──────────┬───────┤ │
│  │ OpenAI │Anthropic │ Google │ Azure  │ Cohere   │ More  │ │
│  └────────┴──────────┴────────┴────────┴──────────┴───────┘ │
└─────────────────────────────────────────────────────────────┘

📦 Examples

Research Agent with RAG

from agentstack import Agent, skill
from agentstack.rag import RAGPipeline, SemanticRetriever
from agentstack.tools import WebSearchTool, WebFetchTool

@skill(id="research", description="Research a topic")
async def research(topic: str) -> str:
    # Skill implementation
    pass

agent = Agent(
    name="Researcher",
    skills=[research],
    tools=[WebSearchTool(), WebFetchTool()],
    rag=RAGPipeline(retriever=SemanticRetriever()),
)

Workflow with State Graph

from agentstack.workflows import StateGraph, GraphExecutor

graph = StateGraph()

graph.add_node("analyze", analyze_function)
graph.add_node("process", process_function)
graph.add_node("output", output_function)

graph.add_edge("analyze", "process")
graph.add_conditional_edge("process", router_function)

graph.set_entry_point("analyze")
compiled = graph.compile()

executor = GraphExecutor()
result = await executor.run(compiled.graph, initial_state={})

Multi-Agent Collaboration

from agentstack import Agent, MultiAgent

researcher = Agent(name="Researcher", skills=[search])
writer = Agent(name="Writer", skills=[write])
reviewer = Agent(name="Reviewer", skills=[review])

team = MultiAgent(
    name="ContentTeam",
    agents=[researcher, writer, reviewer],
    strategy="sequential",
)

result = await team.run("Create an article about AI agents")

🔌 Creating Plugins

from agentstack.plugins import Plugin
from agentstack.tools import tool

class WeatherPlugin(Plugin):
    name = "weather"
    version = "1.0.0"

    def on_load(self):
        self.register_tool(self._create_weather_tool())

    def _create_weather_tool(self):
        @tool(name="get_weather", description="Get weather for a city")
        async def get_weather(city: str) -> dict:
            # Implementation
            return {"city": city, "temp": 72}
        return get_weather

🤱 Mother Agent

The Mother Agent is your AI-powered development assistant:

# Interactive mode
stack mother

# Design an agent
stack mother build "I need a research agent"

# Validate your project
stack mother validate

# Generate from template
stack mother generate researcher --name MyResearcher

from agentstack.mother import MotherAgent

mother = MotherAgent()

# Get help designing an agent
blueprint = await mother.help_build(
    "I need an agent that searches the web and summarizes articles"
)

# Validate configuration
result = mother.validate(config=my_config)

# Debug an error
analysis = mother.debug(agent, error)

🛠️ CLI Commands

Command	Description
stack init <name>	Create a new project
stack run	Run the agent
stack mother	Start Mother Agent
stack plugin list	List plugins
stack plugin install <name>	Install a plugin
stack tool list	List available tools
stack workflow create <name>	Create a workflow
stack validate	Validate project

🧪 Testing

# Run all tests
pytest tests/

# Run specific tests
pytest tests/test_memory.py

# Run with coverage
pytest --cov=agentstack tests/

📋 Requirements

• Python 3.10+
• Dependencies installed via pip

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

AgentStack is inspired by the WordPress model of accessible, extensible software that empowers creators of all skill levels.

---

Built with ❤️ by the AgentStack Team

Documentation • GitHub • Discord