Content
# 🥭 Mangaba AI
[](https://pypi.org/project/mangaba/)
[](https://www.python.org/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/usuario/mangaba-ai/actions)
Repositório minimalista para criação de agentes de IA inteligentes e versáteis com protocolos **A2A** (Agent-to-Agent) e **MCP** (Model Context Protocol).
> 📚 **[WIKI AVANÇADA](docs/WIKI.md)** - Documentação completa em português brasileiro
> 📋 **[ÍNDICE COMPLETO](INDICE.md)** - Navegação rápida por todo o repositório
## ✨ Características Principais
### 🆕 Versão 2.0 - Multi-Agent Orchestration
- 👥 **Multi-Agent Crews**: Coordene equipes de agentes especializados
- 🎭 **Roles & Goals**: Agentes com personalidade e especialização definidas
- 📋 **Structured Tasks**: Sistema completo de orquestração de tarefas
- 🔄 **Process Types**: Sequential e Hierarchical workflows
- 🔧 **Tools Ecosystem**: Integrações com web search, file ops, e mais
- 🤖 **Backward Compatible**: Mantém compatibilidade com API v1.x
### Core Features
- 🔗 **Protocolo A2A**: Comunicação entre agentes
- 🧠 **Protocolo MCP**: Gerenciamento avançado de contexto
- 📝 **Funcionalidades Integradas**: Chat, análise, tradução e mais
- 🌐 **Multi-LLM Real**: Google Gemini, OpenAI GPT, Anthropic Claude e Hugging Face
- ⚡ **Configuração Simples**: Apenas 2 passos para começar
## 🚀 Instalação Rápida
Precisa apenas usar a biblioteca diretamente? Ela já está publicada no PyPI e pode ser instalada tanto com **pip** quanto com **UV**:
```bash
# pip tradicional
pip install mangaba
# usando UV (mesmo comando do pip, porém turbo)
uv pip install mangaba
# teste rápido após a instalação
python -c "from mangaba_ai import MangabaAgent; print(MangabaAgent)"
```
> ✅ Esses comandos funcionam em qualquer ambiente virtual ou no sistema.
> ✅ `uv pip install mangaba` também aceita `--extra`/`--index` iguais ao pip.
Se quiser clonar o repositório para contribuir, rode os passos abaixo e escolha entre **UV** (ultra-rápido) ou **pip** (tradicional):
### ⚡ Opção A: Com UV (10-100x mais rápido!)
```bash
# Windows
.\uv sync
.\uv run python examples/basic_example.py
# Linux/Mac
uv sync
uv run python examples/basic_example.py
```
> 💡 **Novo em UV?** [Guia completo de UV](docs/UV_SETUP.md) • [Migração pip para UV](docs/MIGRACAO_PIP_UV.md)
### 🐍 Opção B: Com pip (tradicional)
```bash
# 1. Criar e ativar ambiente virtual
python -m venv .venv
# Windows
.\.venv\Scripts\Activate.ps1
# Linux/Mac
source .venv/bin/activate
# 2. Instalar dependências
pip install -r requirements.txt
# 3. Executar exemplo
python examples/basic_example.py
```
### 🤖 Opção C: Setup Automático
```bash
# Detecta automaticamente UV ou pip
python scripts/quick_setup.py
```
<details>
<summary>📋 <strong>Configuração do arquivo .env</strong></summary>
```bash
# Copiar template (ou criar manualmente)
cp .env.example .env # Linux/Mac
copy .env.example .env # Windows
```
Edite `.env` e adicione sua chave:
```env
LLM_PROVIDER=google # ou openai | anthropic | huggingface
# Informe apenas a chave correspondente ao provedor escolhido
GOOGLE_API_KEY=sua_chave_google
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
HUGGINGFACE_API_KEY=
MODEL_NAME=gemini-2.5-flash
LOG_LEVEL=INFO
```
Obtenha sua chave nos provedores suportados:
- Google Gemini: https://makersuite.google.com/app/apikey
- OpenAI: https://platform.openai.com/api-keys
- Anthropic: https://console.anthropic.com/account/keys
- Hugging Face: https://huggingface.co/settings/tokens
</details>
## 📦 UV vs pip - Qual usar?
| Característica | UV ⚡ | pip 🐍 |
|----------------|------|--------|
| **Velocidade** | 10-100x mais rápido | Padrão Python |
| **Instalação** | `pip install uv` | Já vem com Python |
| **Compatibilidade** | 100% compatível | Nativo |
| **Lock file** | ✅ `uv.lock` | ❌ Manual |
| **Uso** | `.\uv sync` | `pip install -r requirements.txt` |
| **Recomendado para** | Desenvolvimento ativo | CI/CD tradicional |
**💡 Dica:** Pode usar ambos! UV é retrocompatível com pip.
## ⚙️ Configuração
### 🔧 Comandos por Gerenciador
#### Com UV:
```bash
# Sincronizar dependências
.\uv sync # Windows
uv sync # Linux/Mac
# Instalar pacote novo
.\uv pip install nome-pacote
# Executar script
.\uv run python seu_script.py
# Ver pacotes instalados
.\uv pip list
```
#### Com pip:
```bash
# Ativar ambiente virtual primeiro
.\.venv\Scripts\Activate.ps1 # Windows
source .venv/bin/activate # Linux/Mac
# Instalar dependências
pip install -r requirements.txt
# Instalar pacote novo
pip install nome-pacote
# Executar script
python seu_script.py
# Ver pacotes instalados
pip list
```
### 🛠️ Configuração Manual do .env
1. **Copie o arquivo de exemplo:**
```bash
cp .env.example .env # Linux/Mac
copy .env.example .env # Windows
```
2. **Edite o arquivo .env:**
```env
# Obrigatório
LLM_PROVIDER=google # google | openai | anthropic | huggingface
GOOGLE_API_KEY=sua_chave_google
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
HUGGINGFACE_API_KEY=
# Opcional (com valores padrão)
MODEL_NAME=gemini-2.5-flash
AGENT_NAME=MangabaAgent
LOG_LEVEL=INFO
```
3. **Obtenha sua chave no provedor escolhido:**
- Google Gemini: https://makersuite.google.com/app/apikey
- OpenAI: https://platform.openai.com/api-keys
- Anthropic: https://console.anthropic.com/account/keys
- Hugging Face: https://huggingface.co/settings/tokens
### 🌐 Selecionando o Provedor LLM
No arquivo `.env`, defina qual motor de IA deseja utilizar:
```env
LLM_PROVIDER=google # google | openai | anthropic | huggingface
```
| Provedor | Variável de API Key | Modelo padrão (`MODEL_NAME`) |
|---------------|--------------------------------|---------------------------------------|
| `google` | `GOOGLE_API_KEY` | `gemini-2.5-flash` |
| `openai` | `OPENAI_API_KEY` | `gpt-4o-mini` |
| `anthropic` | `ANTHROPIC_API_KEY` | `claude-3-haiku-20240307` |
| `huggingface` | `HUGGINGFACE_API_KEY` / `HF_TOKEN` | `mistralai/Mistral-7B-Instruct-v0.2` |
👉 Informe **apenas** a chave do provedor selecionado. Trocar de provider exige apenas atualizar `LLM_PROVIDER` (e opcionalmente `MODEL_NAME`).
### 🔍 Validação do Ambiente
```bash
# Validação rápida
python check_setup.py
# Validação completa
python scripts/validate_env.py
# Com relatório detalhado
python scripts/validate_env.py --save-report
```
## 📖 Uso Super Simples
### 🆕 Modo Crew (v2.0) - Multi-Agent
```python
from mangaba import Agent, Task, Crew, Process
# Criar agentes especializados
researcher = Agent(
role="Research Analyst",
goal="Find and analyze information",
backstory="Expert researcher with analytical skills",
verbose=True
)
writer = Agent(
role="Content Writer",
goal="Create engaging content",
backstory="Professional writer with tech expertise"
)
# Definir tarefas
research_task = Task(
description="Research AI trends in {year}",
expected_output="List of 10 key trends",
agent=researcher
)
write_task = Task(
description="Write a report about the findings",
expected_output="Comprehensive report",
agent=writer,
context=[research_task],
output_file="report.md"
)
# Criar e executar crew
crew = Crew(
agents=[researcher, writer],
tasks=[research_task, write_task],
process=Process.SEQUENTIAL,
verbose=True
)
result = crew.kickoff(inputs={"year": "2025"})
print(result.final_output)
```
### 📱 Modo Simples (v1.x - compatível)
```python
from mangaba_ai import MangabaAgent
# Inicializar com protocolos A2A e MCP habilitados
agent = MangabaAgent()
# Chat com contexto automático
resposta = agent.chat("Olá! Como você pode me ajudar?")
print(resposta)
```
> 💡 **Novo projeto?** Use a API v2.0 com Agents/Tasks/Crews
> 💡 **Migrando?** A API v1.x continua funcionando perfeitamente!
## 🎯 Exemplos Práticos
### 🆕 Crew com Processo Hierárquico
```python
from mangaba import Agent, Task, Crew, Process
# Manager (primeiro agente)
manager = Agent(
role="Project Manager",
goal="Coordinate and ensure quality",
backstory="Experienced PM with great leadership",
allow_delegation=True
)
# Workers
developer = Agent(
role="Developer",
goal="Write quality code",
backstory="Senior Python developer"
)
# Tasks
dev_task = Task(
description="Develop authentication system",
expected_output="Working code with tests",
agent=developer
)
# Hierarchical crew (manager delega e revisa)
crew = Crew(
agents=[manager, developer],
tasks=[dev_task],
process=Process.HIERARCHICAL,
verbose=True
)
result = crew.kickoff()
```
### Chat Básico com Contexto MCP
```python
from mangaba_ai import MangabaAgent
agent = MangabaAgent()
# O contexto é mantido automaticamente
print(agent.chat("Meu nome é João"))
print(agent.chat("Qual é o meu nome?")) # Lembra do contexto anterior
```
### Análise de Texto
```python
agent = MangabaAgent()
text = "A inteligência artificial está transformando o mundo."
analysis = agent.analyze_text(text, "Faça uma análise detalhada")
print(analysis)
```
### Tradução
```python
agent = MangabaAgent()
translation = agent.translate("Hello, how are you?", "português")
print(translation)
```
### Resumo do Contexto
```python
agent = MangabaAgent()
# Após algumas interações...
summary = agent.get_context_summary()
print(summary)
```
## 🔗 Protocolo A2A (Agent-to-Agent)
O protocolo A2A permite comunicação entre múltiplos agentes:
### Comunicação entre Agentes
```python
# Criar dois agentes
agent1 = MangabaAgent()
agent2 = MangabaAgent()
# Enviar requisição de um agente para outro
result = agent1.send_agent_request(
target_agent_id=agent2.agent_id,
action="chat",
params={"message": "Olá do Agent 1!"}
)
```
### Broadcast para Múltiplos Agentes
```python
agent = MangabaAgent()
# Enviar mensagem para todos os agentes conectados
result = agent.broadcast_message(
message="Olá a todos!",
tags=["general", "announcement"]
)
```
### Tipos de Mensagens A2A
- **REQUEST**: Requisições entre agentes
- **RESPONSE**: Respostas a requisições
- **BROADCAST**: Mensagens para múltiplos agentes
- **NOTIFICATION**: Notificações assíncronas
- **ERROR**: Mensagens de erro
## 🧠 Protocolo MCP (Model Context Protocol)
O protocolo MCP gerencia contexto avançado automaticamente:
### Tipos de Contexto
- **CONVERSATION**: Conversas e diálogos
- **TASK**: Tarefas e operações específicas
- **MEMORY**: Memórias de longo prazo
- **SYSTEM**: Informações do sistema
### Prioridades de Contexto
- **HIGH**: Contexto crítico (sempre preservado)
- **MEDIUM**: Contexto importante
- **LOW**: Contexto opcional
### Funcionalidades MCP
```python
agent = MangabaAgent()
# Chat com contexto automático
response = agent.chat("Mensagem", use_context=True)
# Chat sem contexto
response = agent.chat("Mensagem", use_context=False)
# Obter resumo do contexto atual
summary = agent.get_context_summary()
```
## 🛠️ Exemplo Avançado
```python
from mangaba_ai import MangabaAgent
def demo_completa():
# Criar agente com protocolos habilitados
agent = MangabaAgent()
print(f"Agent ID: {agent.agent_id}")
print(f"MCP Habilitado: {agent.mcp_enabled}")
# Sequência de interações com contexto
agent.chat("Olá, meu nome é Maria")
agent.chat("Eu trabalho com programação")
# Análise com contexto preservado
analysis = agent.analyze_text(
"Python é uma linguagem versátil",
"Analise considerando meu perfil profissional"
)
# Tradução
translation = agent.translate("Good morning", "português")
# Resumo do contexto acumulado
context = agent.get_context_summary()
print("Contexto atual:", context)
# Comunicação A2A
agent.broadcast_message("Demonstração concluída!")
if __name__ == "__main__":
demo_completa()
```
## 🎮 Exemplo Interativo
Execute o exemplo interativo:
```bash
python examples/basic_example.py
```
Comandos disponíveis:
- `/analyze <texto>` - Analisa texto
- `/translate <texto>` - Traduz texto
- `/context` - Mostra contexto atual
- `/broadcast <mensagem>` - Envia broadcast
- `/request <agent_id> <action>` - Requisição para outro agente
- `/help` - Ajuda
## 🧪 Demonstração dos Protocolos
Para ver uma demonstração completa dos protocolos A2A e MCP:
```bash
python examples/basic_example.py --demo
```
## 📋 Funcionalidades Principais
### MangabaAgent
- `chat(message, use_context=True)` - Chat com/sem contexto
- `analyze_text(text, instruction)` - Análise de texto
- `translate(text, target_language)` - Tradução
- `get_context_summary()` - Resumo do contexto
- `send_agent_request(agent_id, action, params)` - Requisição A2A
- `broadcast_message(message, tags)` - Broadcast A2A
### Protocolos Integrados
- **A2A Protocol**: Comunicação entre agentes
- **MCP Protocol**: Gerenciamento de contexto
- **Handlers Customizados**: Para requisições específicas
- **Sessões MCP**: Contexto isolado por sessão
## 🔧 Configuração Avançada
### Variáveis de Ambiente
```bash
API_KEY=sua_chave_api_aqui # Obrigatório
MODEL=modelo_desejado # Opcional
LOG_LEVEL=INFO # Opcional (DEBUG, INFO, WARNING, ERROR)
```
### Personalização
```python
# Agente com configurações customizadas
agent = MangabaAgent()
# Acessar protocolos diretamente
a2a = agent.a2a_protocol
mcp = agent.mcp
# ID único do agente
print(f"Agent ID: {agent.agent_id}")
# Sessão MCP atual
print(f"Session ID: {agent.current_session_id}")
```
agent = MangabaAgent()
resposta = agent.chat_with_context(
context="Você é um tutor de programação",
message="Como criar uma lista em Python?"
)
print(resposta)
```
### Análise de Texto
```python
from mangaba_ai import MangabaAgent
agent = MangabaAgent()
texto = "Este é um texto para analisar..."
analise = agent.analyze_text(texto, "Resuma os pontos principais")
print(analise)
```
## 🔧 Personalização
Para usar um modelo diferente, apenas mude no `.env`:
```
MODEL=modelo-avancado # Modelo mais avançado
MODEL=modelo-multimodal # Para diferentes tipos de entrada
```
## 🚀 Scripts Disponíveis
> 🔧 **Todos os scripts estão organizados na pasta [scripts/](scripts/)**
- [`validate_env.py`](scripts/validate_env.py) - Valida configuração do ambiente
- [`quick_setup.py`](scripts/quick_setup.py) - Configuração rápida automatizada
- [`example_env_usage.py`](scripts/example_env_usage.py) - Exemplo de uso das configurações
- [`exemplo_curso_basico.py`](scripts/exemplo_curso_basico.py) - Exemplos práticos do curso básico
- [`setup_env.py`](scripts/setup_env.py) - Configuração manual detalhada
## 📁 Estrutura do Projeto
```
mangaba_ai/
├── 📁 docs/ # 📚 Documentação
│ ├── CURSO_BASICO.md # Curso básico completo
│ ├── SETUP.md # Guia de configuração
│ ├── PROTOCOLS.md # Documentação dos protocolos
│ ├── CHANGELOG.md # Histórico de mudanças
│ ├── SCRIPTS.md # Documentação dos scripts
│ └── README.md # Índice da documentação
├── 📁 scripts/ # 🔧 Scripts de configuração
│ ├── validate_env.py # Validação do ambiente
│ ├── quick_setup.py # Setup rápido automatizado
│ ├── example_env_usage.py # Exemplo de uso
│ ├── exemplo_curso_basico.py # Exemplos do curso
│ ├── setup_env.py # Setup manual detalhado
│ └── README.md # Documentação dos scripts
├── 📁 protocols/ # 🌐 Protocolos de comunicação
│ ├── mcp.py # Model Context Protocol
│ └── a2a.py # Agent-to-Agent Protocol
├── 📁 examples/ # 📖 Exemplos de uso
│ └── basic_example.py # Exemplo básico completo
├── 📁 utils/ # 🛠️ Utilitários
│ ├── __init__.py
│ └── logger.py # Sistema de logs
├── mangaba_agent.py # 🤖 Agente principal
├── config.py # ⚙️ Configurações do sistema
├── ESTRUTURA.md # 📁 Organização do repositório
├── .env.example # 🔐 Exemplo de configuração
├── requirements.txt # 📦 Dependências Python
└── README.md # 📖 Este arquivo
```
> 📋 **Para detalhes completos da estrutura, consulte [ESTRUTURA.md](ESTRUTURA.md)**
## 🧪 Testar Rapidamente
### Com UV:
```bash
.\uv run python check_setup.py # Validação rápida
.\uv run python examples/basic_example.py # Exemplo v1.x
.\uv run python examples/crew_example.py # 🆕 Exemplo v2.0 Crew
.\uv run python -m pytest tests/ # Executar testes
```
### Com pip (após ativar .venv):
```bash
python check_setup.py # Validação rápida
python examples/basic_example.py # Exemplo v1.x
python examples/crew_example.py # 🆕 Exemplo v2.0 Crew
python scripts/quick_setup.py # Setup automático
python -m pytest tests/ # Executar testes
```
### Scripts Úteis:
```bash
python scripts/validate_env.py # Validação completa
python scripts/example_env_usage.py # Exemplo de uso
python scripts/exemplo_curso_basico.py # Exemplos do curso
python test_correcoes.py # Testar correções
```
## 📚 Wiki Avançada e Documentação
### 🌟 **[📖 WIKI COMPLETA](docs/WIKI.md) - Portal Principal da Documentação**
A **Wiki Avançada** do Mangaba AI oferece documentação abrangente em português brasileiro para todos os níveis:
#### 🎓 **Para Iniciantes**
- [🚀 Visão Geral do Projeto](docs/WIKI.md#-visão-geral-do-projeto) - O que é e para que serve
- [🎓 Curso Básico Completo](docs/CURSO_BASICO.md) - Tutorial passo-a-passo
- [⚙️ Instalação e Configuração](docs/SETUP.md) - Guia detalhado de setup
- [❓ FAQ - Perguntas Frequentes](docs/FAQ.md) - Dúvidas comuns e soluções
#### 👨💻 **Para Desenvolvedores**
- [🌐 Protocolos A2A e MCP](docs/PROTOCOLS.md) - Documentação técnica completa
- [⭐ Melhores Práticas](docs/MELHORES_PRATICAS.md) - Guia de boas práticas
- [🤝 Como Contribuir](docs/CONTRIBUICAO.md) - Diretrizes de contribuição
- [📝 Glossário de Termos](docs/GLOSSARIO.md) - Definições técnicas
#### 🛠️ **Recursos Técnicos**
- [🔧 Scripts e Automação](docs/SCRIPTS.md) - Documentação dos scripts
- [📊 Histórico de Mudanças](docs/CHANGELOG.md) - Changelog completo
- [📁 Estrutura do Projeto](ESTRUTURA.md) - Organização do repositório
> 🎯 **Comece pela [Wiki Principal](docs/WIKI.md)** - É seu portal de entrada para toda a documentação!
## 🤝 Contribuição
Agradecemos seu interesse em contribuir! Consulte nosso **[Guia Completo de Contribuição](docs/CONTRIBUICAO.md)** para informações detalhadas.
### 🚀 **Primeiros Passos**
1. 📚 Leia as [Diretrizes de Contribuição](docs/CONTRIBUICAO.md)
2. 🍴 Faça fork do projeto
3. 🔧 Configure o ambiente de desenvolvimento
4. ⭐ Siga as [Melhores Práticas](docs/MELHORES_PRATICAS.md)
5. 🧪 Execute os testes
6. 📤 Abra um Pull Request
### 💡 **Formas de Contribuir**
- 🐛 **Correção de bugs**
- ✨ **Novas funcionalidades**
- 📚 **Melhoria da documentação**
- 🧪 **Adição de testes**
- 🌐 **Tradução para outros idiomas**
> 📖 **Primeira contribuição?** Procure por issues marcadas com `good first issue`!
## 📄 Licença
MIT License
---
**Mangaba AI** - Agentes de IA simples e eficazes! 🤖✨
Connection Info
You Might Also Like
MarkItDown MCP
Converting files and office documents to Markdown.
Time
Obtaining current time information and converting time between different...
Filesystem
Model Context Protocol Servers
Sequential Thinking
Offers a structured approach to dynamic and reflective problem-solving,...
Git
Model Context Protocol Servers
Context 7
Context7 MCP Server -- Up-to-date code documentation for LLMs and AI code editors