WellFred — Services in Costa Rica

npx add-mcp 'https://app.wellfred.com/api/agent/mcp'

Guía del agente WellFred

WellFred conecta a clientes con servicios y proveedores en Costa Rica. Los agentes públicos pueden buscar, explorar, inspeccionar ofertas, enviar solicitudes de cotización de invitados y preparar solicitudes de reserva sin una clave de integración.

Resumen para clientes: Uso de asistentes de IA en WellFred.

Índice de descubrimiento de habilidades de agentes publica la habilidad descargable wellfred-services usando descubrimiento v0.2.0 y un resumen de artefacto SHA-256.

Lea el contrato primero

Descubrimiento de autenticación y registro documenta el acceso de agentes anónimos, el aprovisionamiento de clientes y el uso de credenciales para la transferencia de verificación por correo electrónico.

JSON de OpenAPI contiene los esquemas de solicitud y respuesta generados a partir del código de la aplicación. Referencia de API muestra ese mismo contrato. Combine su URL de servidor con cada ruta de operación. Estos endpoints públicos se encuentran bajo /api/agent. Envíe Accept: application/json; los cuerpos POST usan Content-Type: application/json.

Catálogo de API (/.well-known/api-catalog, RFC 9727 application/linkset+json) enlaza el contrato, la documentación y el endpoint de estado de esta API para descubrimiento automatizado.

Descubrimiento ACP enumera los servicios REST públicos: descubrimiento de servicios, solicitudes de cotización de invitados e intenciones de reserva. Use el contrato OpenAPI vinculado para sus formatos de solicitud y respuesta. Las sesiones de pago ACP y el procesamiento de pagos no son compatibles; las intenciones de reserva requieren confirmación del cliente en WellFred.

Use solo las operaciones enumeradas en este contrato público. El descubrimiento y las RFQ no requieren cuenta; las intenciones de reserva devuelven un enlace de confirmación para el cliente.

Agentes de navegador (WebMCP)

Las páginas de WellFred exponen las mismas operaciones públicas a los navegadores compatibles a través de document.modelContext (o navigator.modelContext donde ese sea el lugar del navegador para ello). No se necesita clave de integración ni conexión de cuenta. Las entradas de herramientas provienen del contrato OpenAPI generado. El document.modelContext.executeTool() nativo serializa el objeto de resultado de la devolución de llamada en una cadena JSON; analícelo una vez para leer el resultado de API existente más httpStatus y, cuando se proporcione, retryAfter.

Herramienta	Operación pública
wellfred_search_services	POST /search
wellfred_list_categories	GET /categories
wellfred_resolve_location	GET /locations
wellfred_list_providers	GET /providers
wellfred_search_providers	GET /providers/search
wellfred_get_provider	POST /providers/profile
wellfred_check_availability	POST /availability
wellfred_get_quote_questions	POST /rfq/questions
wellfred_request_quotes	POST /rfqs
wellfred_prepare_booking	POST /booking-intents

WebMCP usa el mismo acceso público incluso cuando alguien ha iniciado sesión. No expone reservas privadas, herramientas de cuenta, pagos ni creación directa de reservas. La búsqueda de proveedores acepta un arreglo ids; el adaptador maneja la codificación de consultas HTTP. Las solicitudes de cotización requieren un idempotencyKey. Obtenga el permiso del cliente antes de enviar su solicitud; devuelva los enlaces de confirmación de reserva para que el cliente los complete en WellFred. Estas herramientas no navegan ni completan la confirmación en nombre del cliente.

La cancelación detiene la solicitud del navegador pero no puede deshacer el trabajo ya recibido por el servidor. Si una respuesta de escritura no está disponible, su resultado es desconocido: siga las pautas de reintento a continuación. El adaptador nunca reintenta automáticamente. Los navegadores sin WebMCP continúan usando el sitio web regular y la API REST.

Encontrar un servicio

Búsqueda de descubrimiento A2A

La Tarjeta de agente A2A anuncia la interfaz JSON-RPC en /api/agent/a2a. Use su URL supportedInterfaces y versión de protocolo. Envíe A2A-Version: 1.0 y Content-Type: application/json con una solicitud JSON-RPC SendMessage que contenga un id único y params.message (messageId, role: "ROLE_USER" y parts). Una parte de texto como {"text":"massage"} proporciona la consulta de búsqueda; una parte de datos lleva las restricciones de búsqueda estructuradas a continuación. Los resultados se devuelven en result.message.parts, con datos estructurados y una recomendación de texto.

Esta interfaz admite búsqueda de descubrimiento síncrona. Las operaciones de catálogo, RFQ e intenciones de reserva usan las operaciones REST a continuación. No se admiten transmisión, notificaciones push ni tarjetas de agente extendidas.

Búsqueda de descubrimiento REST

• GET /categories: IDs de categoría y subcategoría para navegar.
• GET /locations?query=Uvita: lugares candidatos con coordenadas. Resuelva la ambigüedad con el cliente. El centro de una ciudad es adecuado para la búsqueda, no una dirección exacta de reserva.
• POST /search: ofertas de servicios clasificadas, sus proveedores, precios estructurados y una breve recomendación. Omita query para navegar con filtros de categoría/ubicación.
• GET /providers y GET /providers/search: explore proveedores o resuelva nombres/IDs de proveedores.
• POST /providers/profile: inspeccione un proveedor público por UUID de negocio.
• POST /availability: inspeccione los espacios disponibles de un servicio para una fecha explícita. Los servicios basados en solicitudes pueden requerir una RFQ o seguimiento del proveedor en lugar de exponer espacios.

Interprete el lenguaje natural en restricciones explícitas antes de buscar. La búsqueda de texto/semántica existente de WellFred clasifica la necesidad del servicio; no extrae de manera confiable fechas, monedas o recuentos de personas de la prosa. Para "masaje móvil en Uvita mañana para 2 personas, menos de ₡40k cada uno", resuelva la ubicación y la fecha de mañana en America/Costa_Rica, luego envíe:

{
  "query": "massage",
  "delivery": "in-home",
  "partySize": 2,
  "maxPrice": 40000,
  "currency": "CRC",
  "priceUnit": "person",
  "limit": 5
}

Agregue lat, lng de la ubicación seleccionada y date como YYYY-MM-DD. No hay fecha de muestra ni coordenadas adivinadas como valores predeterminados. Informe al cliente la fecha real que usó.

Los filtros de moneda coinciden con la moneda de la oferta; no convierten precios. priceUnit distingue precios por persona de precios por sesión. price es el mismo precio inicial que muestra la página de la oferta, por lo que citarlo no contradirá la página que enlaza; para una oferta con opciones es la opción más barata, y maxPrice filtra contra ese mismo número. Un precio inicial no es una cotización final. Las verificaciones de fecha no establecen la capacidad del grupo, y los proveedores cercanos no son prueba de cobertura para una dirección exacta. Explique los requisitos no resueltos en lugar de afirmar que cada restricción ha sido verificada. Una búsqueda examina un conjunto limitado de candidatos clasificados; un resultado filtrado vacío no es prueba de que no exista ningún proveedor.

La búsqueda devuelve hasta limit entradas de negocio distintas. Cada entrada conserva su oferta representativa y un arreglo alternativeOfferings con como máximo una oferta principal coincidente adicional de ese negocio. Cada oferta tiene su propio ID, URL, precio, unidad y nextAction; estos son servicios separados, no opciones de precios de la representativa. Las búsquedas por fecha verifican la oferta adicional de forma independiente. Si su verificación falla, se omite en lugar de reemplazarse con otro candidato.

matchQuality usa la clasificación del mercado: strong significa principal, loose significa relacionado y discovery significa sugerencias de navegación/categoría. Esto describe coincidencia, no idoneidad, disponibilidad o calificación de reseñas. Presente las ofertas principales antes de las sugerencias relacionadas claramente etiquetadas. strongResultCount cuenta las ofertas principales realmente devueltas, incluidas las alternativas; no es un total de catálogo ni un recuento de negocios.

Devuelva algunas opciones relevantes con sus URL canónicas. Siga nextAction: los servicios con opciones deben abrirse en su página de oferta para la selección de opciones; los servicios de oferta única compatibles pueden usar intenciones de reserva. Nunca invente IDs, cotizaciones ni disponibilidad.

Solicitudes de cotización de invitados

Una RFQ no necesita cuenta de cliente:

1. POST /rfq/questions con requestedService o subcategoryUuid. Use las claves/opciones de preguntas devueltas, los IDs de taxonomía y las respuestas del usuario. Sin conjunto de preguntas, use captura de texto libre, no "servicio no disponible".
2. Recopile nombre, código de país de teléfono y número de teléfono, trabajo solicitado, ubicación y horario. El correo electrónico y el presupuesto son opcionales. Un presupuesto proporcionado requiere una moneda explícita.
3. Muestre el resumen de la solicitud y obtenga permiso para enviarla a WellFred para seguimiento del proveedor.
4. POST /rfqs. Preserve requestedService, la taxonomía resuelta, las respuestas y cualquier preferredProviderUuid. Proporcione un idempotencyKey y reutilice la misma clave y carga útil en los reintentos.
5. Dé al cliente la referencia devuelta. Una RFQ inicia el seguimiento de cotización asistido por personal; no es una cita confirmada.

Ejemplo de solicitud de texto libre después de que el cliente haya proporcionado estos detalles y autorizado el envío:

{
  "requestedService": "Repair a leaking kitchen pipe",
  "location": "Uvita",
  "timing": "The explicit date range agreed with the customer",
  "contactName": "Customer-provided name",
  "contactPhoneCountryCode": "+506",
  "contactPhoneNumber": "Customer-provided phone number",
  "idempotencyKey": "A unique identifier for this request"
}

Reemplace los marcadores de posición descriptivos con valores reales proporcionados por el usuario. Las respuestas exitosas de RFQ contienen success, message, rfqUuid, reference y created en el nivel superior. created: false significa que el envío se reprodujo.

Reserva con verificación de correo electrónico

1. Elija una oferta y una hora específica. Obtenga aprobación para la solicitud y el precio/moneda conocidos.
2. POST /booking-intents con serviceId, startIso (ISO 8601 con desplazamiento de zona horaria), partySize opcional y las coordenadas exactas origin del cliente para visitas a domicilio. Una intención es una solicitud que caduca, no una reserva ni un espacio retenido. La preparación repetida crea intenciones separadas: reutilice el enlace de confirmación devuelto en lugar de preparar repetidamente.
3. Devuelva confirmUrl al cliente. En WellFred, un cliente verificado existente puede confirmar directamente. De lo contrario, el cliente proporciona su nombre/correo electrónico y recibe el enlace de inicio de sesión seguro por correo electrónico existente. Se crea una cuenta gratuita si es necesario, con divulgación en el formulario.
4. El enlace de correo electrónico regresa a la solicitud guardada. Solo el cliente verificado puede enviarla. WellFred vuelve a verificar hora y precio y usa el servicio de reserva normal. La confirmación repetida de la misma intención devuelve el mismo resultado de reserva.
5. La página de confirmación informa el resultado. Una solicitud pendiente aún necesita aceptación del proveedor. Esta API no recopila pagos.

No pida contraseñas ni afirme que proporcionar un correo electrónico prueba la propiedad. La API pública nunca devuelve un token de inicio de sesión ni expone el historial de reservas del cliente. El correo electrónico y los pasos finales de confirmación ocurren en WellFred; no se requiere conexión de cuenta de ChatGPT para esta transferencia.

Las reglas de reserva existentes aún aplican, incluidos los requisitos de teléfono verificado después de la primera reserva. Si una intención caduca, los precios cambian o la oferta necesita selección de opciones, regrese a la oferta o prepare una nueva solicitud y obtenga aprobación para los nuevos detalles. No sustituya silenciosamente servicios o precios.

Errores y reintentos

Cada operación responde en el mismo sobre: success más message, con los propios campos de la operación junto a ellos en el nivel superior. Un fallo establece success: false y nombra la razón en error_code — lea eso, no la prosa en message, al tomar decisiones.

Lea los errores de validación JSON en 422 y corrija solo las entradas inválidas. Respete las respuestas 429 y Retry-After. Las solicitudes tienen tamaños limitados y límites de velocidad. Un 503 con error_code: CONCIERGE_DAILY_CAP_REACHED significa que las operaciones de descubrimiento y preguntas de cotización están en pausa por el día; el resto de la API aún responde, y el cliente puede continuar en el sitio web. Inspeccione success y los campos de resultado específicos de la operación, así como el estado HTTP, antes de informar éxito. Nunca reintente una escritura con una clave de RFQ diferente o una intención de reserva nueva solo porque la respuesta original se perdió.