FAQ y troubleshooting

¿Cómo integro Emi en mi producto?

# 1. Pedir API key a EMA admin (queda en wrangler secret del producto cliente)
# 2. POST a emaemi con:

POST https://emaemi.cristian-ruiz-mti.workers.dev/api/chat
Authorization: Bearer <EMI_API_KEY>
X-Tenant-Id: <tenant>            # sólo si el producto es multi-tenant
Content-Type: application/json

{
  "messages": [
    { "role": "user", "content": "..." }
  ],
  "context": {
    "locale": "es",
    "metadata": { ... }            # patientId, encounterId, etc.
  }
}

La respuesta es { message, agent, turnCount }. El historial de la conversación lo administra el cliente (Emi es stateless).

¿Qué pasa si no envío `X-Tenant-Id` en emaclinic?

Retorna 400 con X-Tenant-Id header required. Sin tenant, las tools FHIR no pueden filtrar por scope y no se permite la consulta.

La request da timeout

El tool loop puede exceder el deadline de Cloudflare Workers cuando los queries a Aidbox o Supabase son lentos. MAX_TOOL_ITERATIONS = 5 previene loops infinitos pero no resuelve queries pesados.

Diagnóstico:

Revisar logs del worker (wrangler tail emaemi).
Identificar qué tool está tardando.
Optimizar la query (índices, paginación) o reducir el scope.

El modelo retorna 503

Anthropic responde 529 (overloaded) intermitentemente. runAgent ya reintenta 3 veces con backoff exponencial (1s, 2s, 3s). Si los 3 fallan, emaemi devuelve 503 al cliente.

Si pasa seguido, hay dos caminos:

Esperar — suele ser transitorio.
Verificar el rate limit del API key de Anthropic.

¿Cómo cambio un system prompt?

Hoy es manual:

Editar SYSTEM_PROMPT en el archivo del agente (src/agents/sales.ts, etc.).
npm run deploy.

No hay hot-swap. Phase 3 contempla mover prompts a un store versionado.

¿Las conversaciones se guardan?

No. Cada request es independiente. Si necesitás historial, lo guardás del lado del cliente. Esto es deliberado para Phase 1; Phase 3 contempla persistir conversaciones para auditoría.

Una tool no encuentra los datos del paciente

Verificar:

El patientId está en context.metadata de la request.
El X-Tenant-Id corresponde al tenant donde vive ese paciente.
El paciente realmente existe en Aidbox de ese tenant.

Si la tool falla por error técnico (red, query inválida), el agente retorna 503 y queda registrado en el log del worker.

¿Qué tools tiene SalesAgent?

Ninguna. SalesAgent es Q&A puro: responde basado únicamente en su system prompt. Si el usuario pregunta algo que requiere datos reales (ej. “cuántos clientes tienen”), el agente responde que no tiene acceso a esa información y deriva al formulario de contacto.

Diferencias entre Phase 1 / 2 / 3

Phase 1 ✅ — SalesAgent operativo, integración en emahealth.io.
Phase 2 ⏳ — SupportAgent y AnalyticsAgent con tools, pero AnalyticsAgent bloqueado hasta configurar VAULT_SUPABASE_URL/KEY.
Phase 3 📋 — DatabaseAgent dedicado, DocumentsAgent (PDFs), persistencia de conversaciones, prompts versionados.