Conceptos básicos
Arkos Note no es un menú con botones ni un chatbot de árbol. Es un agente que razona sobre lo que le dijiste, decide qué herramienta usar y la ejecuta a tu nombre. Entender este modelo mental hace que las demás páginas del manual cobren sentido.
§ 1.4.1 Cómo decide qué hacer #
Por debajo corre con Google ADK (Agent Development Kit) más Gemini 2.5 Flash como modelo. Cada vez que escribes, Arkos arma un prompt con tu mensaje, tu zona horaria, tus preferencias guardadas y los últimos 20 turnos de la conversación, y se lo manda al modelo. El modelo decide:
- Responder directo. Si tu mensaje no requiere acción (saludo, pregunta de chitchat), contesta sin tocar ninguna herramienta.
- Llamar una tool de "core" que está siempre disponible: crear/listar/borrar recordatorios, agendar prompts futuros, guardar preferencias, cambiar zona horaria.
- Cargar una skill de dominio con
load_skill— calendar, baul, listas, gastos, saldo o contactos — y desde ahí invocar las tools especializadas.
Tools como capacidades cargables
Las skills se cargan por demanda en el mismo turno. Si le
dices "agrega leche a la lista y agéndame una junta el jueves",
en un solo turno carga listas y calendar,
ejecuta lo que toque, y te resume el resultado en una respuesta.
§ 1.4.2 Multimodal de entrada #
Arkos recibe cuatro tipos de entrada por WhatsApp:
- Texto. El caso por defecto.
- Audio. Las notas de voz se transcriben con Deepgram antes de pasar al agente. El audio no se persiste tras la transcripción.
- Imagen. Pasa por Gemini Vision: el modelo la ve directo, no solo el caption. Útil para fotos de menús, recibos, tickets, pizarrones.
- PDF. Igual que imagen — Gemini lo lee directo. Buenos casos: facturas, contratos, capturas de pantalla largas.
De salida la respuesta es texto en WhatsApp con su formato
(*negritas*, _cursivas_,
`monospace`). En algunos flujos manda media: archivos del
baúl, etc.
§ 1.4.3 Sesión y memoria #
Hay dos tipos de memoria, con propósitos distintos:
Sesión activa
Es el hilo conversacional reciente. Está en PostgreSQL y se archiva
automáticamente cuando lleva mucho tiempo idle (~8h por defecto)
o cuando mandas /nuevo. Mientras esté activa, Arkos
recuerda lo que dijiste hace cinco minutos sin necesidad de
repetirlo.
Baúl semántico de largo plazo
El baúl es lo que tú decides guardar a largo plazo:
fotos, audios, PDFs, notas. Cada item se describe con visión y se
indexa con embeddings de gemini-embedding-001 (768d)
en una tabla con pgvector. Por eso al día siguiente
puedes preguntar "¿cómo se llamaba el menú del arroz negro?"
y aparece — no busca por título, busca por significado.
El contenido binario vive en Cloudflare R2. La base de datos solo guarda metadata, embeddings y referencias.
§ 1.4.4 Tools y skills disponibles #
Esto es lo que Arkos puede invocar hoy. Cada skill tiene su propia página en el manual con ejemplos detallados.
| Skill | Cuándo carga | Tools clave |
|---|---|---|
Recordatorios y preferencias | siempre activos (core) | crearEvento · listarEventos · removeEvent · programarPrompt · guardarPreferencia |
calendar | agendas con duración o invitados | conectarCalendario · listarEventosCalendario · crearEventoCalendario |
baul | guardar/buscar fotos, audios, PDFs | guardarEnBaul · buscarEnBaul · listarBaul · borrarDelBaul |
listas | compras, pendientes, listados con check | crearLista · agregarItemsALista · marcarItemLista · mostrarLista |
gastos | registrar gasto, cuentas compartidas, reportes | 13 tools de dominio gastos |
saldo | consultar consumo del bot | tools de saldo prepaid |
contactos | agregar amigos, recordar a terceros | invitarContacto · crearRecordatorioParaContacto |
Hay alrededor de 50 tools repartidas entre core (siempre activas) y skills de dominio. El detalle exacto vive en cada página de capacidad.
§ 1.4.5 OAuth como llave de tu calendario #
Tu Google Calendar vive en tu cuenta Google, no en la nuestra. Para que Arkos lo toque necesita un token OAuth cifrado, que tú autorizas en el dashboard:
- Puedes conectar el calendario de Google o el de Outlook, o no conectar ninguno y usar la agenda interna de Arkos.
- Cuando una tool detecta que el calendario no está conectado, te ofrece el flujo de conexión en lugar de fallar silenciosamente.
- Revocar el acceso desde Google no borra tu cuenta de Arkos — solo apaga las tools que lo necesitaban.
§ 1.4.6 Modelo de cobro prepaid #
Arkos Note se cobra por consumo, sin suscripción: recargas saldo cuando quieres, se descuenta lo que cuesta cada interacción con proveedores externos (Gemini para LLM y embeddings, Deepgram para audio, WhatsApp Business API para mensajería) más un margen.
- Cuando se te acaba el saldo, te avisamos por chat con el link de recarga. La cuenta no se borra; solo se pausa.
-
Puedes preguntar en cualquier momento
"¿cuánto saldo tengo?"o"¿en qué se va mi saldo?"y Arkos carga la skillsaldopara responderte.
El detalle (cómo recargar, qué cuesta cada tipo de operación) vive en la página Recargas y saldo.
§ 1.4.7 WhatsApp vs chat web #
Hay dos canales y son el mismo agente:
- WhatsApp — el canal principal. Llega push, multimodal nativo, no requiere abrir una app distinta.
- Chat web en
https://panel-note.arkosmx.com/chat— útil cuando estás en la computadora, quieres copiar texto largo o pegar capturas. Misma sesión, misma memoria.
El identificador interno (sessionId) es compartido por
canal de usuario, así que escribir en uno actualiza el contexto del
otro.
§ 1.4.8 Privacidad: qué se envía a Gemini #
Una pregunta justa antes de meter datos sensibles. Esto es lo que realmente sale de tu cuenta:
| Va a Gemini (Google) | Qué pasa con eso |
|---|---|
| Tu mensaje + últimos turnos + fecha + zona horaria | Se procesa para generar la respuesta. Google no entrena con datos de API por contrato empresarial. |
| Imágenes/PDFs que mandas al baúl o pides analizar | Se envían a Gemini Vision/Files API solo durante el procesamiento. |
| Texto del baúl al hacer embedding | Se manda a la API de embeddings; el vector se guarda en pgvector dentro de nuestra DB. |
Audios van a Deepgram para transcripción y se descartan después. WhatsApp ve los mensajes inevitablemente (es su API). Stripe solo ve datos de pago si recargas con tarjeta. El detalle completo está en la política de privacidad.