MiniAutoGen

Biblioteca Python de microkernel para orquestração de pipelines e coordenação multi-agente assíncrona.

Getting Started

pip install miniautogen
miniautogen init hello --template quickstart
cd hello
miniautogen send "Hello!" --agent assistant

See the Quickstart Guide for install -> first run in 5 minutes.

O MiniAutoGen fornece contratos tipados, runtimes de coordenação e policies transversais para construir sistemas multi-agente. A arquitetura separa rigorosamente o núcleo dos adapters externos, permitindo trocar providers LLM, stores e backends sem alterar lógica de domínio. Todo o fluxo de execução é assíncrono via AnyIO.

Modos de coordenação

• Workflow -- execução sequencial de steps com agentes atribuídos
• Deliberation -- ciclos de contribuição e revisão entre pares
• Agentic loop -- loop conversacional com roteamento dinâmico
• Team -- orquestração hierárquica com Lead e colaboradores (Spec 015)
• Composite -- composição de subruns heterogêneos num único run

Estado atual

• PipelineRunner como runtime oficial com timeout, checkpoint e lifecycle de eventos
• Contratos tipados em core/contracts/ (Pydantic models e Protocol definitions)
• 5 stores especializados (messages, runs, checkpoints, effects, events) com backends InMemory e SQLAlchemy
• 11 policies transversais: budget, approval, retry, timeout, validation, permission, execution, chain, reactive, effect, semantic_cache
• 72 tipos de evento em 13 categorias para observabilidade via structlog
• Abstração de backend drivers com AgentAPIDriver para endpoints OpenAI-compatible
• CLI com 16 comandos e grupos: init, check, run, send, chat, status, agent, engine, flow, sessions, server, console, daemon, dash, doctor, completions
• Taxonomia canónica de erros com 8 categorias e classify_error() extensível
• Effect Engine com idempotência via EffectInterceptor e EffectJournal
• Supervisão hierárquica (StepSupervisor + FlowSupervisor) em todos os runtimes
• RunStateMachine com transições formais de estado (PENDING→RUNNING→terminal)
• EventBus assíncrono com subscrições tipadas e ReactivePolicy
• CheckpointManager para coordenação de checkpoint + eventos
• HeartbeatToken para detecção de agentes zombie
• CircuitBreakerRegistry global para circuit breaking partilhado

Gemini CLI Integration

O MiniAutoGen suporta o uso do Gemini CLI como motor LLM para agentes headless através de um gateway local compatível com a API da OpenAI.

1. Iniciar o Gateway

O gateway atua como uma ponte HTTP para o binário do Gemini.

# Instale as dependências e inicie o gateway
uvicorn gemini_cli_gateway.app:app --host 127.0.0.1 --port 8000

2. Configurar o Engine

No seu miniautogen.yaml, vincule o engine ao gateway:

engines:
  gemini:
    kind: api
    provider: openai-compat
    endpoint: http://127.0.0.1:8000/v1
    model: gemini-2.0-flash
    timeout_seconds: 120

defaults:
  engine: gemini

3. Vincular Agentes

Os agentes podem agora usar o Gemini CLI de forma transparente:

# agents/assistant.yaml
name: assistant
role: "Assistente útil"
goal: "Responder perguntas de forma concisa"
engine: gemini

Guia detalhado: Gemini CLI Gateway

Backend drivers

Camada unificada de drivers para agentes externos:

• AgentDriver -- interface abstrata (start_session, send_turn, cancel_turn, close_session, capabilities)
• AgentAPIDriver -- driver HTTP para endpoints OpenAI-compatible (Gemini CLI gateway, LiteLLM, vLLM, Ollama)
• BackendResolver -- resolução config-driven com factory registry

Documentação: Arquitetura

Web Console

Dashboard web para observação e controle de flows em tempo real.

# Modo produção (single port)
miniautogen console --port 8080

# Modo dev (API + frontend com hot reload)
miniautogen console --dev

# Com persistência
miniautogen console --db sqlite:///runs.db

Funcionalidades:

• Dashboard com contadores de agents, flows e runs
• CRUD completo de agents, flows e engines via interface web
• Settings editor e log viewer integrados
• Visualização de flows com React Flow (workflow e deliberation graphs)
• Trigger de runs via interface web com run tracking
• Event feed em tempo real (WebSocket com fallback para polling)
• Human-in-the-loop (approval list e modal)
• Standalone mode com store-backed data (SQLAlchemy ou in-memory)
• 134 frontend tests

CLI reference

Documentação

• Documentação em português
• Arquitetura atual (C4)
• Referência rápida dos módulos

Docker

docker-compose up

Dockerfile e docker-compose.yml incluídos para deploy containerizado.

Testes

• 2,457+ testes Python (pytest + AnyIO)
• 134 testes frontend (Vitest)

Exemplos executáveis

• Tutorial da nova arquitetura
• Mini app com Gemini CLI
• Agentic loop com debate