mangaba_ai

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

Stars: 166

Visit
 screenshot

Mangaba AI is a minimalist repository for creating intelligent and versatile AI agents with A2A (Agent-to-Agent) and MCP (Model Context Protocol) protocols. It supports any AI provider, facilitates communication between agents, manages context effectively, and offers integrated functionalities like chat, analysis, and translation. The setup is straightforward with only 2 steps to get started. The repository includes scripts for automated configuration, manual setup, and environment validation. Users can easily chat with context, analyze text, translate, and interact with multiple agents using A2A protocol. The MCP protocol handles advanced context management automatically, categorizing context types and priorities. The repository also provides examples, documentation, and a comprehensive wiki in Brazilian Portuguese for beginners and developers.

README:

🥭 Mangaba AI

PyPI version Python License Build Status

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 todo o repositório

✨ Características Principais

  • 🤖 Agente de IA Versátil: Suporte a qualquer provedor de IA
  • 🔗 Protocolo A2A: Comunicação entre agentes
  • 🧠 Protocolo MCP: Gerenciamento avançado de contexto
  • 📝 Funcionalidades Integradas: Chat, análise, tradução e mais
  • Configuração Simples: Apenas 2 passos para começar

🚀 Instalação Rápida

Opção 1: Configuração Automática (Recomendado)

# Configuração completa em um comando
python quick_setup.py

Opção 2: Configuração Manual

# 1. Instalar dependências
pip install -r requirements.txt

# 2. Configurar ambiente
copy .env.template .env
# Edite o arquivo .env com suas configurações

# 3. Validar instalação
python validate_env.py

⚙️ Configuração

🔧 Configuração Automática

O script quick_setup.py automatiza todo o processo:

  • ✅ Cria ambiente virtual
  • ✅ Instala dependências
  • ✅ Configura arquivo .env
  • ✅ Valida instalação

🛠️ Configuração Manual

  1. Configure o arquivo .env (copie de .env.template):
# Obrigatório
GOOGLE_API_KEY=sua_chave_google_api_aqui

# Opcional (com valores padrão)
MODEL_NAME=gemini-2.5-flash
AGENT_NAME=MangabaAgent
LOG_LEVEL=INFO
  1. Obtenha sua Google API Key:

🔍 Validação do Ambiente

# Verifica se tudo está configurado corretamente
python validate_env.py

# Salva relatório detalhado
python validate_env.py --save-report

📖 Uso Super Simples

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)

🎯 Exemplos Práticos

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/

📁 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_protocol.py         # Model Context Protocol
│   └── a2a_protocol.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

# 1. Configuração rápida
python scripts/quick_setup.py

# 2. Validar ambiente
python scripts/validate_env.py

# 3. Testar exemplo
python scripts/example_env_usage.py

# 4. Exemplos do curso básico
python scripts/exemplo_curso_basico.py

# 5. Exemplo interativo
python examples/basic_example.py

📚 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

👨‍💻 Para Desenvolvedores

🛠️ Recursos Técnicos

🎯 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! 🤖✨

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for mangaba_ai

Similar Open Source Tools

For similar tasks

For similar jobs