Skip to content

quickstart.md

Latest commit

 

History

History
381 lines (286 loc) · 11 KB

quickstart.md

File metadata and controls

381 lines (286 loc) · 11 KB

Quickstart Guide

Get from install to your first multi-agent run in 5 minutes.

1. Install

pip install miniautogen

2. Create a Project

miniautogen init my-project --template quickstart
cd my-project

Three templates are available:

Template Description
quickstart Ready-to-run project with a pre-configured agent and flow
minimal Bare minimum structure for experienced users
advanced Full-featured scaffold with multiple agents, flows, and policies

This scaffolds the following structure:

my-project/
  miniautogen.yaml   # Project config (engines, flows, defaults)
  agents/            # Agent definitions (YAML)
  pipelines/         # Pipeline entry points
  skills/            # Reusable skill packages
  tools/             # Tool definitions
  memory/            # Memory profiles
  mcp/               # MCP server configs
  .env               # Environment variables (API keys)

By default, the project is configured with OpenAI (gpt-4o-mini). You can change the provider and model at init time:

# Use a different model
miniautogen init my-project --provider openai --model gpt-4o

# Use Gemini CLI as the backend
miniautogen init my-project --provider gemini-cli --model gemini-2.5-pro

3. Configure Your Engine

The generated miniautogen.yaml includes a default engine:

engines:
  default_api:
    kind: api
    provider: "openai"
    model: "gpt-4o-mini"
    temperature: 0.2

For OpenAI, set your API key in .env:

OPENAI_API_KEY=sk-...

To use Gemini CLI instead, change the engine to:

engines:
  gemini:
    kind: cli
    provider: "gemini-cli"
    model: "gemini-2.5-pro"
    command: "gemini"

You can also add or manage engines with the CLI:

miniautogen engine create my-engine --provider openai --model gpt-4o

Endpoint Configuration for Local Providers

When endpoint points to a local or custom OpenAI-compatible host (Ollama, LM Studio, vLLM, Gemini CLI Gateway, etc.), the framework auto-injects a sentinel token and does not require OPENAI_API_KEY:

engines:
  local_ollama:
    kind: api
    provider: "openai"
    model: "llama3"
    endpoint: "http://localhost:11434/v1"

No api_key is needed for local endpoints. For real OpenAI endpoints (api.openai.com), you must configure api_key (e.g. ${OPENAI_API_KEY}) pointing to a valid environment variable — omitting it will produce a clear configuration error.

4. Create Agents

Agents live as YAML files in the agents/ directory. The scaffold includes an example agent. Here is what a typical agent looks like:

# agents/researcher.yaml
id: researcher
name: Research Specialist
role: Research Specialist
goal: >
  Investigate topics, locate reliable sources, and produce structured summaries.

engine_profile: default_api

tool_access:
  mode: allowlist
  allow:
    - web_search

runtime:
  max_turns: 10
  timeout_seconds: 300

Create additional agents with the CLI:

miniautogen agent create writer --engine default_api --role "Technical Writer"

5. Define a Flow

Flows define how agents coordinate. The scaffold creates a main flow in miniautogen.yaml that references a pipeline builder function:

flows:
  main:
    target: pipelines.main:build_pipeline

The target points to a Python function (build_pipeline in pipelines/main.py) that constructs and returns a pipeline using the SDK. This gives you full programmatic control over agent orchestration.

You can also define flows declaratively with a mode and participants list:

flows:
  build:
    mode: workflow
    participants:
      - architect
      - developer
      - tester

  review:
    mode: deliberation
    participants:
      - architect
      - developer
      - tester
    leader: architect

MiniAutoGen supports three declarative flow modes:

Mode Description
workflow Sequential execution -- agents run in order
deliberation Multi-round discussion -- agents contribute and review
loop Router-driven agentic loop with dynamic routing

Create flows with the CLI:

miniautogen flow create research --mode workflow

6. Validate and Run

Before running, validate your project configuration:

miniautogen check

This checks that all agents, engines, flows, and dependencies are properly configured.

Then run a flow:

miniautogen run main

The CLI provides a Rich Live inline UI showing agent activity, current action, turn/round progress, and streaming thoughts in real time:

┌─ miniautogen run · main · run_id=abc12345 · elapsed=02:14 ─┐
│                                                             │
│  ▶ Engenheiro de Dados  · Contribute · Round 2/5            │
│                                                             │
│  └─ "Proponho um pipeline streaming via Kafka particionado  │
│      por hash de CPF para isolar consumo PII..."            │
│                                                             │
│  Events: 47  ·  Press Ctrl+C to cancel & save               │
└─────────────────────────────────────────────────────────────┘

The UI behaviour adapts to the execution context:

Cenário Comando UI exibida
Terminal interativo miniautogen run main Rich Live inline
Debug verboso miniautogen run main --verbose Logs por linha
CI / pipe miniautogen run main | cat Logs por linha
Output programático miniautogen run main --format json Sem UI (só JSON)
Forçar modo CI MINIAUTOGEN_NO_TTY=1 miniautogen run main Logs por linha

Rich Live Demo Rich Live inline UI during a 3-agent deliberation.

You can also send a single message to an agent directly:

miniautogen send "Hello, world!" --agent assistant

Or start an interactive chat session:

miniautogen chat --agent assistant

Check the workspace status at any time:

miniautogen status

Graceful Cancellation and Resume

Long-running flows can be interrupted with Ctrl+C. The framework saves a checkpoint of the current execution state before exiting, so you can resume later:

# Start a long flow
miniautogen run research --timeout 600

# (interrupt with Ctrl+C)
# Output: "Saving checkpoint before exit..."

# Resume from the last checkpoint
miniautogen run research --resume <run_id>

The checkpoint captures which agent was executing, the current round/turn, and the reason for interruption (cancelled or timed_out). Exit codes reflect the termination reason: 130 for Ctrl+C, 124 for timeout, 0 for successful completion.

Note: Double Ctrl+C forces immediate exit without saving. Press once and wait for the "Saving checkpoint..." message.

7. What Happens Under the Hood

When you run a flow, MiniAutoGen orchestrates execution through a layered architecture:

  1. PipelineRunner -- the core execution engine. It manages the run lifecycle (PENDING -> RUNNING -> COMPLETED/FAILED), enforces timeouts, handles checkpoints, and emits execution events.

  2. AgentRuntime -- wraps each agent with tool access, memory, delegation capabilities, and supervision. The runtime resolves the engine driver for each agent and manages turn-by-turn execution.

  3. Events -- the system emits 72 typed events across 13 categories (run lifecycle, agent turns, tool calls, errors, etc.) for full observability via structlog.

  4. Policies -- transversal concerns like retry, budget tracking, approval gates, and circuit breaking run as reactive policies that observe events without coupling to core logic.

  5. Results -- each run produces a RunResult with the final state, collected outputs from all agents, and any errors encountered.

8. Web Console

Launch the web console for a full GUI experience with CRUD management of agents, flows, and engines, plus settings editor, log viewer, and run tracking:

miniautogen console

Open http://localhost:8080 in your browser.

9. Docker Quick Start

Run MiniAutoGen in a container:

docker-compose up

This starts the API server and web console. See the included Dockerfile and docker-compose.yml for configuration options.

10. Configurando SLAs por Agente

Spec 013 introduz timeouts em três níveis de granularidade no YAML:

Precedência Nível Campo Exemplo
1 (maior) Por agente agent_timeouts engenheiro: 60.0
2 Por round round_timeouts contribute: 60.0
3 Do flow --timeout (CLI) miniautogen run --timeout 120
4 (menor) Da engine timeout_seconds timeout_seconds: 300.0 
# miniautogen.yaml
flows:
  especificacao:
    mode: deliberation
    participants: [advogado, paralegal, engenheiro]
    leader: advogado

    # Per-agent: cada agente tem seu próprio SLA
    agent_timeouts:
      advogado: 300.0
      engenheiro: 60.0
      paralegal: 120.0

    # Per-round: fases da deliberação
    round_timeouts:
      contribute: 60.0
      review: 90.0
      synthesize: 180.0

    # continue (default): agente silenciosamente ignorado
    # abort: falha o flow inteiro
    on_timeout_action: continue

continue vs abort

  • continue (default): se o timeout de um agente expirar, a contribuição é marcada como incompleta e o flow prossegue normalmente. Use quando a ausência de um agente não deve bloquear a deliberação.
  • abort: se o timeout expirar, o TimeoutError propaga e encerra o flow com exit code 124. Use quando todas as contribuições são obrigatórias.

Leitura complementar:

11. Next Steps

  • miniautogen dash -- launch the TUI dashboard to monitor and manage agents, flows, and runs visually.
  • miniautogen console -- launch the web console with full CRUD, settings, and log viewer.
  • miniautogen sessions -- list and inspect past run sessions.
  • miniautogen status -- check workspace and run status.
  • miniautogen doctor -- diagnose your environment setup.
  • miniautogen check -- validate your project at any time.
  • Browse the architecture docs for deeper technical details.
  • See the examples/ directory for complete project examples.