mangaba 2.0.3

Framework de Agentes IA com Multi-Agent Orchestration, Protocolos A2A e MCP

🥭 Mangaba AI

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 - Documentação completa em português brasileiro

📋 ÍNDICE COMPLETO - Navegação rápida por toda a documentação

✨ 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:

# 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!)

# 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 • Migração pip para UV

🐍 Opção B: Com pip (tradicional)

# 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

# Detecta automaticamente UV ou pip
python scripts/quick_setup.py

📋 Configuração do arquivo .env

# Copiar template (ou criar manualmente)
cp .env.example .env  # Linux/Mac
copy .env.example .env  # Windows

Edite .env e adicione sua chave:

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

📦 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:

# 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:

# 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:

cp .env.example .env      # Linux/Mac
copy .env.example .env    # Windows

2. Edite o arquivo .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:

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

# 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

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)

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

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

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

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

agent = MangabaAgent()
translation = agent.translate("Hello, how are you?", "português")
print(translation)

Resumo do Contexto

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

# 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

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

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

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:

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:

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

API_KEY=sua_chave_api_aqui          # Obrigatório
MODEL=modelo_desejado               # Opcional
LOG_LEVEL=INFO                      # Opcional (DEBUG, INFO, WARNING, ERROR)

Personalização

# 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/

• validate_env.py - Valida configuração do ambiente
• quick_setup.py - Configuração rápida automatizada
• example_env_usage.py - Exemplo de uso das configurações
• exemplo_curso_basico.py - Exemplos práticos do curso básico
• 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

🧪 Testar Rapidamente

Com UV:

.\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):

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:

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 - 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 - O que é e para que serve
• 🎓 Curso Básico Completo - Tutorial passo-a-passo
• ⚙️ Instalação e Configuração - Guia detalhado de setup
• ❓ FAQ - Perguntas Frequentes - Dúvidas comuns e soluções

👨‍💻 Para Desenvolvedores

• 🌐 Protocolos A2A e MCP - Documentação técnica completa
• ⭐ Melhores Práticas - Guia de boas práticas
• 🤝 Como Contribuir - Diretrizes de contribuição
• 📝 Glossário de Termos - Definições técnicas

🛠️ Recursos Técnicos

• 🔧 Scripts e Automação - Documentação dos scripts
• 📊 Histórico de Mudanças - Changelog completo
• 📁 Estrutura do Projeto - Organização do repositório

🎯 Comece pela Wiki Principal - É seu portal de entrada para toda a documentação!

🤝 Contribuição

Agradecemos seu interesse em contribuir! Consulte nosso Guia Completo de Contribuição para informações detalhadas.

🚀 Primeiros Passos

1. 📚 Leia as Diretrizes de Contribuição
2. 🍴 Faça fork do projeto
3. 🔧 Configure o ambiente de desenvolvimento
4. ⭐ Siga as Melhores Práticas
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! 🤖✨