AzterDocs

Empezar

Conceptos

Un vocabulario pequeño y preciso gobierna todo lo que Azter expone. Estos conceptos se aplican igual en el runtime del agente, en el servidor MCP y en las interfaces que vienen.

Capability

Una operación canónica con contrato explícito. Cada capability define su schema de entrada y salida, los scopes que exige, su clase de riesgo y su comportamiento ante reintentos. Existe una única implementación por capability: las interfaces la invocan, no la duplican.

capability (forma pública)
{
  "name": "inventory.check",
  "version": "1.0.0",
  "execution": "query",
  "riskClass": "read",
  "requiredScopes": ["inventory:read"],
  "consistency": { "level": "best_effort" }
}

Query vs Command

query

Obtiene información sin efectos secundarios. Puede reintentarse de forma segura y su respuesta incluye provenance.

command

Produce side effects (actualizar un contacto, cobrar, emitir un documento). Exige idempotencia, nunca se reintenta a ciegas y ante un timeout ambiguo queda en estado unknown en lugar de afirmarse como fallido o exitoso.

Scopes

Los scopes son permisos granulares por dominio: catalog:read, customers:write, payments:create. Una credential solo puede invocar capabilities cuyos scopes tenga concedidos; el resto se rechaza sin revelar su existencia.

  • Una capability puede exigir todos los scopes listados (allOf) o bastar con uno de ellos (anyOf).
  • El access token de OAuth hereda los permisos que el usuario concedió en el consentimiento.
  • Las API keys se emiten con scopes explícitos desde la consola.

Idempotencia

La identidad de una operación mutativa es el intento lógico, no el contenido del mensaje: un agente identifica cada llamada con su run y tool call; una integración REST podrá usar un header Idempotency-Key. Repetir el mismo intento devuelve el resultado previo sin re-ejecutar; reutilizar una key con un payload distinto se rechaza como conflicto.

ciclo de un intento
reserved → executing → confirmed
                 ↘ unknown (timeout ambiguo: el lock se conserva
                     y el intento se resuelve antes de re-ejecutar)

Provenance

Toda respuesta respaldada por un sistema externo explica de dónde viene: fuente, momento de observación, frescura (live, fresh, stale), si es autoritativa y si se usó un fallback. Un agente siempre puede saber si está decidiendo con información actualizada.

Conexiones

Un connector es un tipo de proveedor (Shopify, WhatsApp, un gateway de pagos). Una connection es una instancia autenticada de ese proveedor para una empresa: Shopify Chile y Shopify Perú son dos connections del mismo connector. Este modelo permite conectar varias cuentas del mismo sistema sin duplicar lógica.

En desarrollo

El registro formal de connectors con metadata machine-readable llega con la Integration Platform. Hoy las conexiones se administran desde la consola.

Eventos

Un evento es un hecho observable de la plataforma: un mensaje recibido, una cotización emitida, un pago confirmado. Los webhooks salientes entregan estos hechos a tus sistemas con firma HMAC y reintentos con backoff.

Ver también

AnteriorQuickstartSiguiente Capabilities