Notion declaró la disponibilidad general de sus Agent APIs el 2 de noviembre de 2026. Permiten conversar con agentes desde otras aplicaciones y gestionar agentes existentes. El cambio también abre el acceso al agente personal de Notion AI y depreca las rutas de la alpha privada. Recuperamos la novedad hoy, 5 de noviembre: la fecha del anuncio no es la de este artículo.

Para quien construye una aplicación interna, la decisión principal es con qué identidad actuará. Un token personal y una conexión de equipo no dan acceso a las mismas conversaciones. Elegir mal puede romper una integración aunque las peticiones estén bien formadas.

El agente personal tiene reglas propias

El identificador notion_ai representa al agente personal del usuario que autentica la petición. Solo funciona con un token de acceso personal, o PAT por sus siglas en inglés. Un token de conexión recibe un error 404 object_not_found al intentar acceder a ese identificador; eso no significa que las conexiones hayan dejado de funcionar para los agentes personalizados.

Con el agente personal se puede conversar, consultar sus datos de uso y cambiar su nombre o modelo. No admite control de estado, límite de créditos ni borrado mediante estas APIs. Los agentes personalizados, o Custom Agents, tienen otras operaciones. Deben existir previamente en Notion: la API descrita no los crea.

Un PAT pertenece a un espacio de trabajo y actúa con los permisos de la persona que lo creó. No es una credencial neutra para toda la empresa. Notion recomienda una conexión interna para automatizaciones que deban pertenecer al equipo y una conexión pública con autorización OAuth para productos usados por múltiples usuarios.

Leer una conversación no autoriza a escribir en ella

Una conexión necesita que el Custom Agent se comparta con ella. La capacidad View sessions and interact with agents permite leer y conversar; Edit selected agents habilita cambios en los agentes seleccionados. Tener solo la segunda no concede acceso a los endpoints de lectura y sesiones.

Además, la conexión solo puede leer y modificar las sesiones que ella misma creó. No obtiene acceso a los chats de la aplicación Notion por compartir el mismo agente. Las sesiones creadas con un PAT pertenecen al usuario y pueden continuarse en Notion; las de una conexión se continúan por la API.

Un ejemplo hipotético: una persona inicia una conversación en Notion y quiere retomarla desde una herramienta interna. Puede hacerlo con su PAT. Si el equipo añade después un servicio con token de conexión, ese servicio tendrá sus propias sesiones; no heredará aquella conversación. Un PAT puede leer otras sesiones de un Custom Agent cuando los permisos lo permitan, pero no por ello escribir o cancelar sesiones ajenas.

Esta separación merece pruebas específicas antes de dar acceso real. Nuestro antecedente sobre cómo evaluar resultados, acciones y fallos de un agente explica por qué una respuesta correcta no basta para validar los permisos.

La migración cambia rutas y objetos

La guía oficial de migración desde la alpha describe cambios que van más allá de sustituir una dirección:

  • El listado GET /v1/agents pasa a POST /v1/agents/query, con filtros en el cuerpo JSON.
  • Las conversaciones llamadas threads pasan a sessions; sus mensajes se consultan como eventos.
  • Las rutas chat y chatStream se sustituyen por POST /v1/sessions, con agent_id en el cuerpo.
  • La respuesta progresiva usa eventos del servidor, SSE, con Accept: text/event-stream, en lugar de líneas NDJSON.

También hay que adaptar los estados, incluidos queued, in_progress y terminated. Por separado, PATCH /v1/agents/{agent_id} reúne cambios de configuración y estado; el endpoint anterior Update agent status está deprecado. No todos esos campos se aplican al agente personal. La documentación consultada no fija aquí una fecha de apagado de las rutas alpha: deprecación no equivale a retirada inmediata.

Acceder por API no vuelve gratuita la ejecución de IA

Notion distingue las lecturas y escrituras ordinarias de contenido, que no consumen créditos, de ejecutar sus agentes. Según su política actual, el agente personal en Auto usa créditos Standard; elegir modelo usa Select. Los Custom Agents consumen por defecto Select de su propietario, con opciones de financiación y controles del espacio de trabajo.

Antes de automatizar conversaciones conviene revisar quién paga, qué presupuesto existe y qué permisos tiene cada identidad. No hemos ejecutado estas llamadas ni medido costes por conversación. La disponibilidad general confirma el estado de la API; no demuestra que cualquier integración tenga acceso, presupuesto suficiente o el mismo comportamiento que su alpha.

Fuentes

Sigue explorando

← Volver al blog