Búsqueda · Descubrimiento de productos · Agentes
Protocolos compatibles.
SuggestAPI expone los mismos trabajos de búsqueda y descubrimiento de productos (encontrar, consultar, comparar, recomendar) sobre los protocolos que los agentes y las tiendas ya hablan. Esta página es el mapa humano de esas superficies.
Última actualización:
Dos hosts, un trabajo de descubrimiento
Los compradores usan la API de aceleración de búsqueda. Los agentes usan Knowledge Gateway. Ambos se sitúan delante del motor de búsqueda que ya utilizas (Algolia, Typesense, Elastic o Meilisearch) y devuelven resultados de catálogo estructurados en lugar de HTML raspado.
| Host | Audiencia | Para qué sirve | Empieza aquí |
|---|---|---|---|
| api.suggestapi.com | Tiendas, aplicaciones, ingesta | API de autocompletado, typeahead, índices, merchandising y catálogo | openapi.json |
| agent.suggestapi.com | Agentes, plugins, registros | Búsqueda por tenant, consulta de productos, comparación, recomendación y descubrimiento de protocolos | okg.json |
El índice de servicios del gateway es https://agent.suggestapi.com. Las notas humanas de protocolos están en AGENTS.md.
Habilidades compartidas de descubrimiento de productos
A2A y MCP exponen las mismas cuatro herramientas de comercio. Cada herramienta es un envoltorio de protocolo fino sobre una llamada REST de Knowledge Gateway. El tenant es el dominio del comercio (por ejemplo, demo.suggestapi.com).
| Habilidad / herramienta | Parámetros requeridos | Opcionales | Backend |
|---|---|---|---|
| search | tenant, query | retrieval_mode (typeahead, autocomplete, search, hybrid), limit | POST /v1/agent/search |
| recommend | tenant, query | — | POST /v1/agent/recommend |
| compare | tenant, ids (≥2) | — | POST /v1/agent/compare |
| product_lookup | tenant, id | — | GET /v1/agent/product/{id} |
Endpoints de protocolo de Knowledge Gateway
Host agent.suggestapi.com. Los documentos de descubrimiento viven en /.well-known/. El JSON-RPC en tiempo de ejecución está en /a2a y /mcp. UCP y ACP son contratos REST de comercio en el mismo host. El descubrimiento PAP está limitado al tenant en /oks/{tenant}/.well-known/pap.
| Protocolo | Método | Ruta | Qué es |
|---|---|---|---|
| A2A | GET | /.well-known/agent-card.json | Agent Card (protocolo 0.2.0, cuatro habilidades) |
| A2A | POST | /a2a | JSON-RPC: agent/card, message/send, tasks/get, tasks/cancel |
| AID | GET | /.well-known/agent | Documento de fallback AID (aid2, proto a2a) |
| AID | GET | /.well-known/ai | Índice de agentes AID (agents[] con suggestapi) |
| DNS-AID | GET | /.well-known/dns-aid.json | Índice de agentes A2A + MCP; capSha256 de A2A es base64url de la tarjeta |
| MCP | POST | /mcp | JSON-RPC sobre HTTP transmitible (protocolo 2025-06-18) |
| WebMCP | GET | /.well-known/webmcp | Manifiesto de herramientas más endpoints REST para cada herramienta de comercio |
| MCP | GET | /.well-known/mcp-manifest.json | Alias del manifiesto/herramientas MCP |
| MCP | GET | /.well-known/mcp-server | Documento de servidor MCP well-known (estilo draft-serra) |
| MCP | GET | /.well-known/mcp/server.json | Esquema de servidor del registro MCP (remote streamable-http) |
| MCP | GET | /.well-known/api-catalog | Linkset RFC 9727 a WebMCP + MCP |
| UCP | GET | /.well-known/ucp | Perfil de Universal Commerce Protocol; la búsqueda de catálogo está limitada al tenant |
| ACP | GET | /.well-known/acp | Perfil de Agent Commerce Protocol; el feed y las sesiones de checkout están limitados al tenant |
| PAP | GET | /oks/{tenant}/.well-known/pap | Perfil experimental de Principal Agent Protocol (draft-baur-pap-02). Solo búsqueda de catálogo de invitado opt-in; el campo de cumplimiento es false. |
Copias en vivo: Agent Card,/a2a,/mcp,WebMCP,AID,Índice AID,DNS-AID,api-catalog,UCP,ACP,PAP.
Runtimes A2A y MCP
A2A es Agent-to-Agent: obtén la tarjeta y envía un mensaje que nombre una habilidad. Las tareas se almacenan unos 30 minutos para que un cliente pueda consultarlas o cancelarlas. MCP es Model Context Protocol sobre HTTP transmitible: handshake, listar herramientas, llamar a una herramienta. Ambos despachan a las mismas habilidades del gateway.
A2A JSON-RPC
| Método | Rol |
|---|---|
| agent/card | Devuelve el Agent Card |
| message/send | Ejecuta una habilidad; almacena la tarea ~30 min |
| tasks/get | Obtiene una tarea almacenada |
| tasks/cancel | Marca una tarea almacenada como cancelada |
MCP JSON-RPC
| Método | Rol |
|---|---|
| initialize | Handshake + versión del protocolo |
| notifications/initialized | Confirma que el cliente está listo |
| ping | Vitalidad |
| tools/list | Cuatro herramientas de comercio |
| tools/call | Despacho mediante habilidades del gateway |
| resources/list, prompts/list | Listas vacías (compatibles, sin uso) |
Los metadatos del registro MCP también están en /.well-known/mcp.json.
Para qué sirve cada protocolo
Los protocolos de descubrimiento dicen a un agente qué existe. Los protocolos de tiempo de ejecución le permiten buscar en el catálogo. SuggestAPI publica ambos para que no quedes atado a un único stack de agentes.
| Protocolo | Trabajo | Rol en búsqueda / descubrimiento de productos |
|---|---|---|
| A2A | Tiempo de ejecución | Otro agente llama a SuggestAPI como especialista de comercio: buscar, consultar, comparar, recomendar. |
| MCP | Tiempo de ejecución | Los asistentes de código y de compra conectan /mcp y obtienen las cuatro herramientas de catálogo. Consulta las notas sobre MCP y WebMCP. |
| WebMCP | Descubrimiento + REST | Los agentes de navegador y de sitio leen una lista de herramientas que también nombra las URLs REST detrás de cada herramienta. Consulta las notas sobre MCP y WebMCP. |
| AID / DNS-AID | Descubrimiento | Encuentra el agente A2A (y MCP) en este host sin codificar rutas. DNS-AID incluye un hash del Agent Card. |
| ARD | Descubrimiento | Catálogo Google Agentic Resource Discovery de capacidades de comercio. No ejecuta búsquedas por sí mismo. Consulta ARD. |
| UCP | Tiempo de ejecución (REST) | Búsqueda de catálogo de Universal Commerce Protocol, limitada al tenant. Consulta /.well-known/ucp. |
| ACP | Tiempo de ejecución (REST) | Feed de productos y transferencia de sesión de checkout de Agent Commerce Protocol, limitados al tenant. Las sesiones permanecen en not_ready_for_payment; SuggestAPI no captura pagos. Consulta /.well-known/acp. |
| PAP | Tiempo de ejecución (HTTP, experimental) | Búsqueda de catálogo de invitado opt-in bajo una cadena de mandato firmada. Solo catálogo público, sin carrito ni checkout, y sin declaración de conformidad. Consulta las notas sobre PAP. |
| OKF / OKS | Conocimiento + búsqueda de plugins | Conocimiento portable más /oks/{tenant}/search para tiendas que mantienen su catálogo existente. Consulta OKF. |
| HTTP QUERY | Tiempo de ejecución (HTTP) | Cuerpos de búsqueda seguros e idempotentes de RFC 10008 en autocompletado, typeahead y búsqueda para agentes. Consulta las notas sobre QUERY. |
| REST + OpenAPI | Tiempo de ejecución | HTTP directo para aplicaciones que no hablan A2A ni MCP. Gateway: openapi.yaml. API: openapi.json. |
| Agent Skills | Manuales para agentes de código | Carpetas SKILL.md que enseñan a Claude, Codex, Antigravity, Cursor y clientes similares a llamar a api.suggestapi.com. Instala suggestapi/skills con npx skills add suggestapi/skills. Índice de dominio: /.well-known/agent-skills/index.json. |
Knowledge Gateway REST (búsqueda y catálogo)
Úsalos cuando quieras JSON sobre HTTP sin JSON-RPC. La búsqueda de plugins por tenant es la vía de adopción para tiendas existentes.
| Método | Ruta | Propósito |
|---|---|---|
| POST / QUERY | /v1/agent/search | Búsqueda orientada a tareas en una superficie de conocimiento del tenant |
| GET | /v1/agent/product/{id} | Consulta canónica de producto |
| POST | /v1/agent/compare | Compara productos por id |
| POST | /v1/agent/recommend | Recomendaciones a partir de consulta + contexto |
| GET / QUERY | /oks/{tenant}/search | Búsqueda estilo plugin (q, mode) |
| POST | /oks/{tenant}/catalog/search | Búsqueda de catálogo UCP para ese comercio |
| GET | /oks/{tenant}/feeds/default/products | Feed de productos ACP para ese comercio |
| POST | /oks/{tenant}/checkout_sessions | Sesión de checkout ACP (solo transferencia; no se ofrece pago completado) |
| GET | /.well-known/ai-catalog.json | Catálogo de capacidades ARD |
Existen ayudantes de transferencia (/v1/agent/cart, guía de checkout) para el checkout controlado por el comercio. No son una API de pagos. Resumen de capacidades: documentación de Agent Discovery.
API de aceleración de búsqueda
https://api.suggestapi.com es la API HTTP para typeahead de tienda, autocompletado, índices, ingesta y recomendaciones tipo grafo. No es el host A2A/MCP. Los agentes que necesitan herramientas de comercio por tenant deben usar Knowledge Gateway.
| Método | Ruta | Propósito |
|---|---|---|
| GET / QUERY | /v1/autocomplete | Sugerencias clasificadas por intención para la barra de búsqueda |
| GET / QUERY | /v1/typeahead | Typeahead rápido por prefijo desde una tabla precalculada |
| GET / POST | /v1/indexes… | Crear, ingerir, merchandising, esquema, exportar |
| GET / POST | /v1/graph/recommendations… | Recomendaciones estructurales, de series, de aplicaciones y de especificaciones |
| GET | /health | Vitalidad |
| GET | /openapi.json | Contrato completo legible por máquinas |
Los agentes de código que deben implementar contra esta API: instala suggestapi/skills (npx skills add suggestapi/skills). Adaptadores de ingeniería y esquema de respuesta: Trae tu propio buscador. Enrutamiento de consultas: Abstracción de recuperación.
¿Qué protocolo debería usar?
| Si estás… | Usa |
|---|---|
| Conectando una barra de búsqueda de tienda | GET https://api.suggestapi.com/v1/autocomplete o typeahead |
| Creando un cliente MCP (Cursor, Claude, personalizado) | POST https://agent.suggestapi.com/mcp |
| Un agente de código (Claude, Codex, Antigravity, Cursor) que implementa contra la API de búsqueda | npx skills add suggestapi/skills → https://api.suggestapi.com |
| Llamando desde otro agente A2A | Obtén el Agent Card y luego POST https://agent.suggestapi.com/a2a |
| Indexando capacidades sin una lista de herramientas codificada | ARD ai-catalog.json, AID o DNS-AID |
| Implementando la búsqueda de catálogo de compras UCP | POST /oks/{tenant}/catalog/search |
| Ejecutando una búsqueda de catálogo de invitado PAP | GET /oks/{tenant}/.well-known/pap, luego el handshake de seis pasos. Experimental y opt-in por tenant. |
| Implementando el feed de catálogo ACP y la transferencia al checkout | GET /oks/{tenant}/.well-known/acp, luego el feed del tenant y las sesiones de checkout. La finalización permanece en la tienda del comercio. |
| Manteniendo el sitio del comercio como fuente de la verdad | Búsqueda de plugin OKS /oks/{tenant}/search |
ARD
Descubrimiento de Recursos para Agentes
Cómo los agentes encuentran las capacidades de comercio de SuggestAPI sin herramientas codificadas.
OKF
Formato de Conocimiento Abierto
Paquetes de conocimiento portables que los agentes pueden navegar con el catálogo.
Recuperación
Enrutamiento de consultas
Recuperación léxica vs embeddings y mapeo de intención a API.