Lab 01 — Hello Architect

Configura Architect desde cero, ejecuta una tarea simple y entiende el flujo básico: prompt → LLM → tool calls → resultado.

Objetivo

Configurar Architect desde cero, ejecutar una tarea simple y entender el flujo básico: prompt → LLM → tool calls → resultado.

Nivel: Básico

Duración estimada: 15 minutos. Feature principal: architect run.

Setup

mkdir -p ~/architect-labs/lab-01 && cd ~/architect-labs/lab-01
git init

1. Crear el proyecto Python de ejemplo

mkdir -p src tests

src/calculator.py

def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

def multiply(a, b):
    return a * b

tests/test_calculator.py

from src.calculator import add, subtract, multiply

def test_add():
    assert add(2, 3) == 5

def test_subtract():
    assert subtract(5, 3) == 2

def test_multiply():
    assert multiply(3, 4) == 12

2. Crear configuración de Architect

.architect.yaml

llm:
  model: openai/gpt-4.1
  api_base: http://localhost:4000/v1   # LiteLLM proxy
  api_key_env: LITELLM_API_KEY

logging:
  level: human

3. Verificar que el proyecto funciona

export PYTHONPATH=.
pytest tests/ -v
# Deberían pasar los 3 tests

4. Commit inicial

git add -A
git commit -m "initial: calculator project"

Ejercicio 1: Primera ejecución con run

Pide a Architect que añada una función divide con manejo de división por cero:

architect run "Añade una función divide(a, b) en src/calculator.py \
  que divida a entre b. Si b es 0, lanza un ValueError con mensaje \
  'Cannot divide by zero'. Añade tests para la función en \
  tests/test_calculator.py incluyendo el caso de error." \
  --config .architect.yaml \
  --confirm-mode confirm

Qué observar:

Architect muestra cada tool call que quiere hacer (leer archivo, editar, etc.)
En modo confirm te pide aprobación antes de cada escritura
Al terminar, verifica los cambios con:

git diff
pytest tests/ -v

Consejo

El modo confirm es ideal para aprender cómo funciona Architect internamente. Te permite ver y aprobar cada paso del proceso.

Ejercicio 2: Modo yolo (sin confirmación)

Ahora pide otra feature sin confirmación manual:

architect run "Añade una función power(base, exponent) en src/calculator.py \
  que calcule base^exponent usando el operador **. \
  Añade tests en tests/test_calculator.py con al menos 3 casos: \
  positivos, exponente 0, y exponente negativo." \
  --config .architect.yaml \
  --confirm-mode yolo

Qué observar:

Ejecuta sin pedir confirmación
Más rápido pero sin control paso a paso
Ideal para tareas bien definidas y de bajo riesgo

pytest tests/ -v
# Deberían pasar todos los tests (viejos + nuevos)

Importante

El modo yolo ejecuta sin confirmación. Úsalo solo con tareas bien definidas y de bajo riesgo, o cuando tengas guardrails configurados (Lab 02).

Ejercicio 3: Verbose mode

Repite con -v para ver los logs detallados:

architect run "Añade una función modulo(a, b) en src/calculator.py \
  que devuelva a % b. Si b es 0, lanza ValueError." \
  --config .architect.yaml \
  --confirm-mode yolo \
  -v

Qué observar en verbose:

Tokens consumidos por llamada
Tools disponibles
Prompts internos
Coste estimado

Resultado esperado

Al completar los tres ejercicios, tu proyecto debería tener:

src/calculator.py        → 6 funciones: add, subtract, multiply, divide, power, modulo
tests/test_calculator.py → Tests para todas las funciones
pytest                   → Todos los tests pasan

Resumen

Concepto	Descripción
`architect run`	Ejecuta una tarea única de principio a fin
`--config`	Archivo de configuración YAML
`--confirm-mode confirm`	Aprobación manual de cada escritura
`--confirm-mode yolo`	Sin confirmación, ejecución automática
`-v`	Verbose: muestra detalles internos

Siguiente lab

Lab 02: Guardrails Fundamentals — Aprende a proteger archivos y limitar lo que Architect puede hacer.