# Quickstart: Agent DB — Clientes y contratos

**Feature**: `002-agent-db-clients-contracts`

## Prerequisites

- Laravel 12 + `ia_agent` running locally
- LLM configured (`LLM_PROVIDER`, API keys)
- BD operativa accesible vía `agent_db_secondary`

## Environment

Add to `.env`:

```env
AGENT_CAPABILITY_AGENT_DATABASE=true

AGENT_DB_CONNECTION=mysql
AGENT_DB_HOST=127.0.0.1
AGENT_DB_PORT=3306
AGENT_DB_DATABASE=tu_bd_operativa
AGENT_DB_USERNAME=usuario_solo_lectura
AGENT_DB_PASSWORD=***

# Optional
AGENT_DB_SEARCH_MAX_RESULTS=50
```

Validate connection:

```powershell
php artisan db:validate-secondary
# (extend or add artisan agent:validate-db for agent_db_secondary)
```

## Manual test (chat)

1. Start API: `php artisan serve`
2. Start queue if needed: `php artisan queue:work`
3. Login SPA or API → obtain JWT
4. POST `/api/v1/chat/message` with Bearer token:

```json
{ "message": "¿Qué contratos tiene el cliente con NIF B12345678?" }
```

5. POST follow-ups:

```text
Dame el detalle de la propuesta con referencia REF-2024-001
Lista los CUPs de la propuesta CodProCom 12345
```

## Expected behavior

- Intent classifier routes to `agent_database` capability
- LLM selects tool from catalog (e.g. `buscar_clientes` → `listar_propuestas_por_cliente`)
- Response in Spanish, no SQL/tool names exposed
- Empty results → clear message, no invented data

## Verify against spec

| Scenario | Test message |
|----------|--------------|
| US1 Cliente + contratos | "Contratos del cliente [nombre]" |
| US1 Contacto tipo 3 | "Propuestas del contacto [nombre]" |
| US2 Detalle | "Detalle propuesta RefProCom X" |
| US4 Sin datos | NIF inexistente → "no encontré registros" |

## Run tests

```powershell
php artisan test --filter=AgentCommercial
```

(Tests added during `/speckit-implement`.)