# Quickstart Guide

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

## 1. Install

```bash
pip install miniautogen
```

## 2. Create a Project

```bash
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:

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

```yaml
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:

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

You can also add or manage engines with the CLI:

```bash
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`:

```yaml
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:

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

```bash
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:

```yaml
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:

```yaml
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:

```bash
miniautogen flow create research --mode workflow
```

## 6. Validate and Run

Before running, validate your project configuration:

```bash
miniautogen check
```

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

Then run a flow:

```bash
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](assets/rich-live-demo.svg)
> *Rich Live inline UI during a 3-agent deliberation.*

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

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

Or start an interactive chat session:

```bash
miniautogen chat --agent assistant
```

Check the workspace status at any time:

```bash
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:

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

```bash
miniautogen console
```

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

## 9. Docker Quick Start

Run MiniAutoGen in a container:

```bash
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` |

```yaml
# 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:**
> - [Spec completa](/.specs/per-agent-timeouts.md)
> - [Graceful Cancel e Checkpoint](/.specs/cancel-checkpoint.md) (interage com save shielded)

## 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](pt/architecture/README.md) for deeper
  technical details.
- See the [examples/](../examples/) directory for complete project examples.
