Skip to content

GLOSSARIO

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

📝 Glossário de Termos - Mangaba AI

Este glossário define todos os termos técnicos e conceitos utilizados no projeto Mangaba AI. Os termos estão organizados alfabeticamente para facilitar a consulta.

📋 Navegação Rápida

Por Categoria:

Por Letra: A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

A

Agent-to-Agent (A2A)

Definição: Protocolo de comunicação que permite que múltiplos agentes de IA se comuniquem diretamente entre si, compartilhando informações e coordenando tarefas.

Exemplo de uso: Um agente especializado em análise financeira pode solicitar a um agente redator que crie um relatório baseado em seus dados de análise.

Veja também: Protocolo A2A, Broadcast

Agente

Definição: Uma instância do sistema Mangaba AI capaz de processar linguagem natural, analisar textos, traduzir idiomas e se comunicar com outros agentes.

Características:

  • 🧠 Processamento de linguagem natural
  • 🔄 Comunicação A2A
  • 💾 Gerenciamento de contexto MCP
  • 🎯 Especialização em domínios específicos

Exemplo:

agente = MangabaAgent(
    api_key="sua_chave",
    agent_id="agente_financeiro",
    enable_mcp=True
)

API Key

Definição: Chave de autenticação fornecida pelo Google Cloud que permite acesso aos serviços do Google Generative AI (Gemini).

Como obter: Através do Google AI Studio

Segurança: Sempre armazene em variáveis de ambiente, nunca diretamente no código.

Análise de Texto

Definição: Capacidade do agente de examinar, interpretar e extrair insights de textos usando instruções específicas.

Exemplo:

resultado = agente.analyze_text(
    text="Relatório financeiro trimestral...",
    instruction="Identifique tendências e riscos principais"
)

Assíncrono (Async)

Definição: Execução não-bloqueante de operações, permitindo que múltiplas tarefas sejam processadas simultaneamente.

Uso no Mangaba: Comunicação A2A, processamento de múltiplas requisições, operações de I/O.

B

Broadcast

Definição: Envio de uma mensagem de um agente para múltiplos agentes simultaneamente através do protocolo A2A.

Exemplo:

resultados = agente.broadcast_message(
    message="Reunião às 15h hoje",
    tags=["meeting", "urgent"]
)

Diferença do send: Send é 1:1, broadcast é 1:N (um para muitos).

Builder Pattern

Definição: Padrão de design usado para construir objetos complexos passo a passo, comum na configuração de agentes.

Exemplo:

agente = (AgentBuilder()
          .with_mcp(True)
          .with_model("gemini-pro")
          .with_cache(True)
          .build())

C

Cache

Definição: Sistema de armazenamento temporário que guarda respostas já processadas para evitar chamadas desnecessárias à API.

Benefícios:

  • ⚡ Reduz tempo de resposta
  • 💰 Diminui custos da API
  • 🔄 Melhora eficiência geral

Implementação:

cache = ResponseCache(duration=3600)  # 1 hora
agente = CachedMangabaAgent(cache=cache)

Context Type

Definição: Classificação dos tipos de contexto no protocolo MCP.

Tipos disponíveis:

  • USER: Informações sobre o usuário
  • TASK: Dados de tarefas específicas
  • SYSTEM: Configurações e estado do sistema
  • CONVERSATION: Histórico de conversas

Context Priority

Definição: Nível de importância atribuído a um contexto MCP.

Níveis:

  • HIGH: Alta prioridade, sempre mantido
  • MEDIUM: Prioridade média, mantido conforme espaço
  • LOW: Baixa prioridade, primeiro a ser removido

Contexto

Definição: Informações armazenadas pelo protocolo MCP que influenciam as respostas do agente, incluindo histórico de conversas, preferências do usuário e dados de tarefas.

Exemplo de uso: Se um usuário mencionou que trabalha em marketing, futuras perguntas considerarão essa informação.

D

Deploy

Definição: Processo de colocar o sistema Mangaba AI em produção, incluindo configuração de ambiente, instalação de dependências e validação de funcionamento.

Scripts disponíveis:

  • quick_setup.py: Deploy automatizado
  • validate_env.py: Validação pós-deploy
  • health_check.py: Monitoramento contínuo

Docstring

Definição: Documentação embutida no código Python que descreve função, parâmetros, retorno e exemplos de uso.

Padrão do projeto:

def processar_texto(texto: str, instrucao: str) -> str:
    """
    Processa texto usando o agente Mangaba.
    
    Args:
        texto (str): Texto a ser processado
        instrucao (str): Instrução para processamento
        
    Returns:
        str: Texto processado
    """

E

Environment Variables

Definição: Variáveis do sistema operacional usadas para configurar o Mangaba AI sem expor informações sensíveis no código.

Principais variáveis:

GOOGLE_API_KEY=sua_chave_google
MODEL_NAME=gemini-pro
LOG_LEVEL=INFO
AGENT_ID_PREFIX=prod_

Error Handling

Definição: Tratamento de erros específico do Mangaba AI, incluindo exceções customizadas para diferentes tipos de falha.

Exceções principais:

  • ErroMangabaAPI: Erro geral da API
  • ErroConfiguracaoAgente: Configuração inválida
  • ErroProtocoloA2A: Falha na comunicação A2A
  • ErroContextoMCP: Problema no gerenciamento de contexto

F

Factory Pattern

Definição: Padrão de design para criar agentes especializados de forma padronizada.

Exemplo:

class AgentFactory:
    @staticmethod
    def criar_agente_medico():
        return MangabaAgent(
            agent_id="medico_especialista",
            model="gemini-pro"
        )

Framework

Definição: O Mangaba AI como um todo - conjunto de ferramentas, protocolos e bibliotecas para desenvolvimento de sistemas de agentes de IA.

G

Gemini

Definição: Modelo de inteligência artificial da Google usado como base pelos agentes Mangaba AI.

Modelos disponíveis:

  • gemini-pro: Texto e raciocínio geral
  • gemini-pro-vision: Texto e imagens
  • gemini-ultra: Versão mais avançada (quando disponível)

Google Generative AI

Definição: Plataforma de IA generativa da Google que fornece os modelos Gemini através de APIs REST.

Documentação oficial: ai.google.dev

H

Handler

Definição: Função especializada que processa tipos específicos de mensagens no protocolo A2A.

Exemplo:

@agente.a2a_protocol.register_handler("analisar_documento")
def handle_analise(message):
    documento = message.content.get("texto")
    return agente.analyze_text(documento, "análise completa")

Health Check

Definição: Verificação automática do status e funcionamento dos agentes e protocolos.

Endpoint típico: GET /health Resposta: Status (healthy/unhealthy/degraded) e métricas

I

Integration Tests

Definição: Testes que verificam a interação entre diferentes componentes do sistema, como comunicação A2A entre agentes.

Exemplo: Teste que verifica se dois agentes conseguem trocar mensagens com sucesso.

Instruction

Definição: Comando ou diretriz fornecida ao agente durante análise de texto, especificando que tipo de processamento deve ser realizado.

Exemplos:

  • "Analise o sentimento do texto"
  • "Extraia os pontos principais"
  • "Traduza para linguagem técnica"

J

JSON

Definição: Formato de dados usado na comunicação entre agentes e armazenamento de contextos MCP.

Exemplo de mensagem A2A:

{
  "sender_id": "agente1",
  "target_id": "agente2", 
  "action": "analyze",
  "params": {"text": "texto para análise"}
}

L

Load Balancing

Definição: Distribuição de carga entre múltiplos agentes para otimizar performance e evitar sobrecarga.

Estratégias:

  • Round-robin: Distribuição sequencial
  • Least-load: Agente com menor carga
  • Capability-based: Baseado em especialização

Logging

Definição: Sistema de registro de eventos e atividades dos agentes para monitoramento e debug.

Níveis:

  • DEBUG: Informações detalhadas
  • INFO: Eventos normais
  • WARNING: Situações de atenção
  • ERROR: Erros que impedem funcionamento

M

Mangaba AI

Definição: Framework brasileiro open-source para criação de agentes de IA com protocolos A2A e MCP, otimizado para português brasileiro.

Origem do nome: Mangaba é uma fruta nativa do Brasil, simbolizando a origem nacional do projeto.

MangabaAgent

Definição: Classe principal que representa um agente no sistema, combinando capacidades de IA, comunicação A2A e gerenciamento de contexto MCP.

Principais métodos:

  • chat(): Conversa geral
  • analyze_text(): Análise específica
  • translate(): Tradução
  • send_agent_request(): Comunicação A2A

MCP (Model Context Protocol)

Definição: Protocolo proprietário do Mangaba AI para gerenciamento inteligente de contexto, permitindo que agentes "lembrem" de informações relevantes.

Funcionalidades:

  • 💾 Armazenamento de contexto
  • 🔍 Busca por relevância
  • 🏷️ Organização por tags
  • ⏰ Limpeza automática

Metrics

Definição: Métricas de performance e uso coletadas automaticamente pelo sistema.

Métricas principais:

  • Tempo de resposta
  • Número de requisições
  • Uso de memória
  • Taxa de erro

Model Context Protocol → Veja MCP

P

Performance

Definição: Medida da eficiência e velocidade do sistema Mangaba AI.

Fatores que influenciam:

  • Tamanho do contexto MCP
  • Complexidade das instruções
  • Número de agentes conectados
  • Cache de respostas

Prompt

Definição: Texto enviado ao modelo de IA (Gemini) contendo a pergunta do usuário, contexto relevante e instruções específicas.

Estrutura típica:

[CONTEXTO MCP]
[INSTRUÇÃO ESPECÍFICA]
[PERGUNTA DO USUÁRIO]

Protocolo

Definição: Conjunto de regras e formatos para comunicação entre componentes do sistema.

Protocolos do Mangaba:

  • A2A: Comunicação entre agentes
  • MCP: Gerenciamento de contexto

Protocolo A2A

Definição: Sistema de comunicação que permite que agentes se conectem e troquem mensagens diretamente, formando redes distribuídas de IA.

Características:

  • 🔄 Comunicação bidirecional
  • 📡 Suporte a broadcast
  • 🎯 Handlers especializados
  • 🌐 Conexões de rede

Pull Request (PR)

Definição: Proposta de mudança no código do projeto, submetida por contribuidores para revisão e possível incorporação.

Processo típico:

  1. Fork do repositório
  2. Implementação da mudança
  3. Criação do PR
  4. Code review
  5. Merge (se aprovado)

Q

Query

Definição: Consulta ou pergunta feita ao agente, seja através de chat direto ou busca de contexto MCP.

Queue

Definição: Fila de mensagens ou tarefas aguardando processamento, especialmente relevante em cenários de alta carga.

R

Rate Limiting

Definição: Controle da frequência de requisições para evitar exceder limites da API Google e otimizar custos.

Implementação típica:

@rate_limit(calls_per_minute=30)
def funcao_limitada():
    return agente.chat("pergunta")

Response

Definição: Resposta gerada pelo agente após processar uma requisição, seja de chat, análise ou tradução.

RPM (Requests Per Minute)

Definição: Métrica que mede quantas requisições por minuto são feitas à API Google.

Limites típicos:

  • Gratuito: 15 RPM
  • Pago: Configurável (padrão 60 RPM)

S

Session

Definição: Sessão MCP que agrupa contextos relacionados, permitindo isolamento de diferentes conversas ou usuários.

Operações:

  • Criar nova sessão
  • Adicionar contextos à sessão
  • Buscar contextos na sessão
  • Limpar/deletar sessão

Setup

Definição: Processo de configuração inicial do ambiente Mangaba AI.

Scripts disponíveis:

  • quick_setup.py: Configuração automática
  • setup_env.py: Configuração manual
  • validate_env.py: Validação da configuração

T

Tag

Definição: Rótulo usado para categorizar e buscar contextos MCP.

Exemplos de tags:

  • usuario, perfil
  • financeiro, marketing
  • tarefa, analise
  • traducao, documento

Target Language

Definição: Idioma de destino especificado em operações de tradução.

Exemplo:

traducao = agente.translate(
    text="Hello world",
    target_language="português brasileiro"
)

Thread-Safe

Definição: Característica de código que pode ser executado simultaneamente por múltiplas threads sem causar problemas.

Relevante para: Comunicação A2A, operações MCP, cache compartilhado.

Timeout

Definição: Tempo limite para operações, após o qual são consideradas falhadas.

Aplicações:

  • Requisições à API Google
  • Comunicação A2A
  • Operações de cache

Type Hints

Definição: Anotações de tipo em Python que indicam os tipos esperados para parâmetros e retornos.

Exemplo:

def processar(texto: str, opcoes: Dict[str, Any]) -> Optional[str]:
    pass

U

Unit Tests

Definição: Testes que verificam o funcionamento de componentes individuais do sistema.

Exemplo: Teste que verifica se a função chat() retorna uma string não-vazia.

User Context

Definição: Tipo específico de contexto MCP que armazena informações sobre o usuário.

Exemplos:

  • Nome e cargo
  • Empresa e setor
  • Preferências de resposta
  • Histórico de interações

V

Validation

Definição: Verificação de que configurações, parâmetros e estados estão corretos.

Tipos de validação:

  • Configuração de ambiente
  • Parâmetros de entrada
  • Formato de mensagens A2A
  • Integridade de contextos MCP

Verbose

Definição: Modo de operação que fornece informações detalhadas sobre o que está acontecendo.

Uso: Debug, troubleshooting, monitoramento de desenvolvimento.

W

WebSocket

Definição: Protocolo de comunicação bidirecional usado em implementações avançadas de A2A para conexões persistentes.

Wrapper

Definição: Função ou classe que encapsula outra para adicionar funcionalidades extras.

Exemplo: CachedMangabaAgent é um wrapper que adiciona cache ao MangabaAgent.

🤖 Agentes e IA

Termos Relacionados a Agentes

Termos de IA e ML

🌐 Protocolos

A2A - Agent-to-Agent

MCP - Model Context Protocol

🔧 Técnicos

Desenvolvimento

Arquitetura

Performance

Qualidade

🏢 Negócios

Custos e Limites

Operações

📞 Ainda Tem Dúvidas?

Não encontrou um termo?

Quer contribuir com o glossário?

  • ➕ Sugira novos termos via Pull Request
  • ✏️ Corrija definições existentes
  • 📖 Adicione exemplos mais claros

💡 Dica: Use este glossário como referência rápida durante o desenvolvimento!

🔗 Links úteis: Wiki | FAQ | Melhores Práticas | Como Contribuir

Última atualização: Dezembro 2024 | Versão: 1.0 | Total de termos: 80+

🗺️ Navigation

Clone this wiki locally