Skip to content

Home

Jump to bottom
Ysrael edited this page May 10, 2026 · 1 revision

🥭 Mangaba AI — Documentação Completa

Professional multi-agent orchestration framework with ReAct reasoning, RAG, memory, and function calling.

Versão: 3.2.0 | Licença: MIT | Python: ≥3.9

📚 Índice

Seção Descrição
Home Visão geral e introdução
Getting Started Instalação e primeiro projeto
Core Components Agent, Task, Crew
LLM Providers Google, OpenAI, Anthropic, HuggingFace, OpenRouter
Tools Sistema de ferramentas
Memory Short-term, Long-term, Entity
RAG Retrieval-Augmented Generation
Vector Stores InMemory, Redis, PostgreSQL
Workflows Pipeline, Stage, ParallelStage
Events EventBus e Callbacks
Guardrails Validação de entrada/saída
Protocols A2A e MCP
API Reference Referência completa da API
Examples Exemplos práticos

🏗️ Arquitetura

┌─────────────────────────────────────────────────────────┐
│                    Mangaba AI Framework                  │
├──────────┬──────────┬──────────┬──────────┬─────────────┤
│  Agent   │  Crew    │ Workflow │  RAG     │  Protocols  │
│  (ReAct) │(Orchestr)│(Pipeline)│(Retrieval)│ (A2A/MCP)  │
├──────────┴──────────┴──────────┴──────────┴─────────────┤
│                    Core Engine                           │
│  ┌────────┐ ┌──────┐ ┌───────┐ ┌────────┐ ┌──────────┐ │
│  │  LLM   │ │Tools │ │Memory │ │Events  │ │Guardrails│ │
│  │Client  │ │System│ │System │ │ Bus    │ │ Parsers  │ │
│  └────────┘ └──────┘ └───────┘ └────────┘ └──────────┘ │
├─────────────────────────────────────────────────────────┤
│              LLM Providers (5 backends)                  │
│  Google  │  OpenAI  │  Anthropic  │  HF  │  OpenRouter  │
├─────────────────────────────────────────────────────────┤
│              Vector Stores (3 backends)                  │
│  InMemory  │  Redis (RediSearch)  │  PostgreSQL(pgvector)│
└─────────────────────────────────────────────────────────┘

✨ Recursos Principais

Recurso Descrição
Multi-Agent Orquestre múltiplos agents com 4 modos: Sequential, Hierarchical, Parallel, Consensual
ReAct Reasoning Thought → Action → Observation loop para uso inteligente de ferramentas
5 LLM Providers Google Gemini, OpenAI, Anthropic Claude, HuggingFace, OpenRouter
Function Calling Tool use nativo em todos os providers
RAG Pipeline completo: loaders, splitters, retriever, chain
3 Vector Stores InMemory, Redis (RediSearch HNSW), PostgreSQL (pgvector)
Memory Short-term (sliding window), Long-term (SQLite), Entity
Workflows Pipeline com Stage, ParallelStage, ConditionalStage
Event Bus Sistema de eventos para observabilidade e logging
Guardrails Validação de entrada/saída com cadeias de guardrails
A2A Protocol Agent-to-Agent communication
MCP Protocol Model Context Protocol integration
Streaming Suporte a streaming em todos os providers
Caching Cache de respostas LLM (InMemory, Disk)
Retry Retry automático com backoff exponencial

🚀 Quick Start

from mangaba import Agent, Task, Crew, Process
from mangaba.core.types import LLMConfig
from mangaba.core.llm import create_llm_client

# 1. Configuração via LLMConfig
llm_config = LLMConfig(
    provider="google",
    model="gemini-2.5-flash",
    api_key="YOUR_KEY",
    temperature=0.7,
    max_tokens=4096,
)

llm = create_llm_client(
    provider=llm_config.provider,
    api_key=llm_config.api_key,
    model=llm_config.model,
    temperature=llm_config.temperature,
    max_output_tokens=llm_config.max_tokens,
)

# 2. Create agent
researcher = Agent(
    role="Senior Researcher",
    goal="Discover cutting-edge developments in AI",
    backstory="Expert AI researcher with deep knowledge of the field",
    llm=llm,
    verbose=True,
)

# 3. Create task
task = Task(
    description="Research the latest trends in AI agents for 2026",
    expected_output="A comprehensive report with 10 key findings",
    agent=researcher,
)

# 4. Create crew and run
crew = Crew(
    agents=[researcher],
    tasks=[task],
    process=Process.SEQUENTIAL,
)
result = crew.kickoff()
print(result)

📦 Instalação

# Instalar via pip
pip install mangaba

# Com RAG support
pip install mangaba[rag]

# Com Redis vector store
pip install mangaba[redis]

# Com PostgreSQL vector store
pip install mangaba[postgres]

# Todas as dependências
pip install mangaba[all]

📁 Estrutura do Projeto

mangaba_ai/
├── mangaba/                    # Main package
│   ├── __init__.py             # Public API exports
│   ├── core/                   # Core framework
│   │   ├── agent.py            # Agent with ReAct reasoning
│   │   ├── task.py             # Task definitions
│   │   ├── crew.py             # Multi-agent orchestration
│   │   ├── workflow.py         # Pipeline engine
│   │   ├── events.py           # Event bus & callbacks
│   │   ├── reasoning.py        # ReAct engine
│   │   ├── guardrails.py       # Input/output validation
│   │   ├── output_parsers.py   # JSON, Pydantic parsers
│   │   ├── planner.py          # Task planning
│   │   ├── types.py            # Pydantic models
│   │   ├── exceptions.py       # Custom exceptions
│   │   └── llm/                # LLM providers
│   │       ├── client.py       # Multi-provider engine
│   │       ├── cache.py        # Response caching
│   │       ├── retry.py        # Retry logic
│   │       ├── token_counter.py# Token tracking
│   │       └── prompt_templates.py
│   ├── tools/                  # Tool system
│   │   ├── base.py             # BaseTool abstract class
│   │   ├── decorator.py        # @tool decorator
│   │   ├── toolkit.py          # Tool collections
│   │   ├── math_tools.py       # Calculator
│   │   ├── text_tools.py       # Text utilities
│   │   ├── file_tools.py       # File operations
│   │   └── web_search.py       # Web search
│   ├── memory/                 # Memory systems
│   │   ├── base.py             # BaseMemory abstract class
│   │   ├── short_term.py       # Sliding window
│   │   ├── long_term.py        # SQLite + vector search
│   │   └── entity.py           # Entity tracking
│   ├── embeddings/             # Embedding providers
│   │   ├── base.py             # BaseEmbedding interface
│   │   ├── openai_embed.py     # OpenAI embeddings
│   │   └── google_embed.py     # Google embeddings
│   ├── vectorstores/           # Vector stores
│   │   ├── base.py             # BaseVectorStore interface
│   │   ├── in_memory.py        # Pure Python implementation
│   │   ├── redis.py            # Redis Stack (RediSearch)
│   │   ├── postgres.py         # PostgreSQL (pgvector)
│   │   └── factory.py          # create_vectorstore()
│   ├── rag/                    # RAG pipeline
│   │   ├── document.py         # Document model
│   │   ├── loaders.py          # Text, CSV loaders
│   │   ├── splitters.py        # Text splitting
│   │   ├── retriever.py        # Embedding + vector store
│   │   └── chain.py            # RAG chain for Q&A
│   └── callbacks/              # Observability
├── protocols/                  # Communication protocols
│   ├── a2a.py                  # Agent-to-Agent protocol
│   └── mcp.py                  # Model Context Protocol
├── examples/                   # Example scripts
├── tests/                      # Test suite
├── docs/                       # Documentation (this wiki)
├── pyproject.toml              # Project config
└── docker-compose.vectorstores.yml

🗺️ Navigation

Clone this wiki locally