Glosario para agentes

Glosario para agentes AI de Abior

Terminos canonicos de Abior que un agente AI necesita entender para operar correctamente. Cada definicion esta orientada a como el termino afecta tu trabajo.

Identidad

Gafete: Tu identidad operativa dentro de Abior. Un agente AI actua como su propio Gafete: es el sujeto que crea, lee y modifica datos. El scoping y la firma de autoria (created_by) se resuelven por Gafete, no por usuario humano.; Para tu agente: Cuando filtres o crees datos, razona SIEMPRE por Gafete (el tuyo), nunca por usuario humano. Un mismo humano tiene varios Gafetes (uno por emprendimiento + uno por cada agente suyo); filtrar por user mezcla trabajos que no son tuyos.
Entidad: El "quien" detras de un Gafete. Puede ser personal (una persona fisica), comercial (un negocio o marca) o moral (una persona juridica). Define a quien pertenece y representa el Gafete.; Para tu agente: La Entidad es la unidad de scoping, cobro y propiedad de datos. Casi todo modelo cuelga de una Entidad; al crear registros no cruces datos entre entidades distintas.
Agente: Un Gafete operado por un modelo de IA (como Claude Code) en lugar de una persona. Tiene UUID propio, un responsable humano, un modo_confirmacion y un ApiToken con el que firma su trabajo.; Para tu agente: Tu eres un Agente. Firma tu trabajo con tu ApiToken (no el de un humano) e incluye el emprendimiento en el body para que el backend resuelva tu Gafete de agente y created_by quede como tu alias.
Responsable: La persona humana que supervisa a un agente. Configura, autoriza y puede pausar o revocar el token del agente; es el interlocutor para confirmaciones y decisiones de alcance.; Para tu agente: Ante una accion destructiva o fuera de alcance, el Responsable es a quien se pide confirmacion. No asumas autorizacion: pidela.
Credac: Credencial de acceso: el mecanismo de credenciales cifradas que un Gafete usa para hablar con proveedores externos (ej. la API key del LLM). Distinto del ApiToken de Abior.; Para tu agente: Credac guarda secretos cifrados de terceros; nunca los imprimas ni los pongas en logs. Distinto de tu ApiToken (que es tu acceso a Abior).
ApiToken: El token de acceso del agente (ABIOR_APITOKEN). Se envia como Authorization: Token <token> en MCP y REST. Sin el no puedes operar. El responsable puede pausarlo o revocarlo.; Para tu agente: Nunca escribas el token literal: usalo via la variable ${ABIOR_APITOKEN}. Si un endpoint devuelve 401/403, valida que el header Authorization vaya y que el token no este pausado antes de reintentar.
Personal Zero: El nivel de acceso gratuito de una entidad personal sin suscripcion paga: es usable dentro de topes duros (instancias + MB). Al topar, el backend bloquea crear nuevos elementos e invita a Premium. Nunca hay lockout global del app.; Para tu agente: Si al crear recibes 403 con code limite_zero_instancias o limite_zero_mb, la entidad topo su cupo gratis: no reintentes, reporta el limite y la invitacion a Premium. Lo ya creado sigue editable.

Estructura

Emprendimiento: El proyecto o iniciativa de negocio dentro del cual trabajas. Agrupa Estaciones, Artefactos y el trabajo asociado. Tu agente esta vinculado a un emprendimiento concreto.; Para tu agente: Incluye el emprendimiento en el body al crear la mayoria de registros: es lo que permite al backend resolver tu Gafete correcto y hacer el scoping.
Estacion: Una division o area de trabajo dentro de un emprendimiento. Organiza Artefactos y actividad por funcion o etapa.; Para tu agente: Usa la Estacion para ubicar trabajo por area; no es obligatoria en todo registro pero da contexto de donde vive el trabajo.
Artefacto: La unidad concreta de produccion: un codigo, documento, diseno u otro entregable sobre el que trabaja el agente. Tiene ficha, directrices y versiones (Arvers).; Para tu agente: Antes de generar trabajo sobre un Artefacto, lee sus Directrices (son reglas vigentes que prevalecen sobre tus asunciones).
Arver: Una version de un Artefacto (Artefacto-version). Captura el estado del artefacto en un momento dado; permite historial y evolucion controlada.; Para tu agente: Vincula Planes/HistoriasUsuario al Arver vigente para trazar en que version se hizo el trabajo.
ComponenteMolde: Plantilla o componente reutilizable que define la estructura/molde de una pantalla o parte de un artefacto, con criterios de aceptacion y ejemplos. Sirve como patron base para producir entregables consistentes.; Para tu agente: Para criterios de un ComponenteMolde usa el nombre bare "componentemolde" (NO "componente") -- es un footgun conocido del content_type_model.
Directriz: Regla o lineamiento vigente que un Artefacto impone sobre como debe producirse su contenido. Como agente debes leerlas y respetarlas antes de generar trabajo sobre ese artefacto.; Para tu agente: Consulta list_directrices_aplicables(artefacto) antes de codear. Las directrices prevalecen sobre tus asunciones y pueden cambiar sin aviso.

Flujo de trabajo

SolicitudDesar: La peticion de trabajo de desarrollo. Se crea con prompt_original = el mensaje del usuario verbatim. Es el primer paso del flujo canonico y el origen rastreable de lo que produces.; Para tu agente: Crea una SD ANTES de empezar cualquier trabajo, con prompt_original verbatim. Corre primero la guardia check-duplicado; si existe, reusa esa SD en vez de crear otra.
HistoriaUsuario: La necesidad expresada desde el punto de vista del usuario ("como X quiero Y para Z"). Se crea cuando la tarea representa una necesidad funcional, no solo una orden tecnica.; Para tu agente: Vincula el Plan a una HistoriaUsuario para trazar el motivo. La HU es la que posee el M2M planes/quehaceres/tareas: enlaza desde la HU (hu.planes.add).
Plan: El contenedor ejecutable que organiza el trabajo de una solicitud. Tiene status (sin_iniciar -> en_proceso -> terminado). Lo creas al arrancar y vas actualizando su estado.; Para tu agente: Nace sin_iniciar; pasalo a en_proceso JUSTO antes de tocar codigo y a terminado (no para_revision) al entregar. Lee spec_de_plan antes de codear.
Quehacer: Una unidad de trabajo dentro de un Plan: un bloque de actividad con objetivo propio. Un Plan se desglosa en varios Quehaceres.; Para tu agente: Igual que el Plan: nace sin_iniciar, en_proceso al empezarlo, terminado al cerrarlo. No pongas todos en en_proceso desde el inicio (miente sobre lo activo).
Tarea: El subpaso concreto y verificable dentro de un Quehacer. Es el nivel mas granular de ejecucion.; Para tu agente: Usa commit_ref/evidencia_url para ligar la Tarea cerrada a su commit/PR. Marcala terminado solo cuando el trabajo concreto este hecho.
Participacion: El registro de horas humanas invertidas en el trabajo. Se crea al cerrar, para reflejar la participacion real en la solicitud/plan.; Para tu agente: Al entregar el informe final del Plan, PREGUNTA al usuario cuantas horas invirtio y registra la Participacion vinculada. Si responde 0, no la crees.
Nota: Una anotacion libre asociada a un elemento de Abior (plan, artefacto, etc.). Util para dejar contexto, decisiones o pendientes.; Para tu agente: Usa Notas para dejar contexto duradero; soportan chips de mencion #@ para enlazar otros registros.
Enlace: Un vinculo o referencia (URL o relacion entre entidades) que conecta elementos dentro de Abior o hacia recursos externos.; Para tu agente: Usa Enlaces para relacionar registros o apuntar a recursos externos sin duplicar informacion.

Comportamiento

Scoping por gafete: Principio fundamental: filtra, consulta y razona siempre por Gafete (el tuyo o el de tu emprendimiento), nunca por usuario humano. Evita mezclar datos de gafetes distintos.; Para tu agente: Nunca uses Q(asignado_a__user=...) ni Q(created_by__user=...) sin filtrar agente__isnull: atrapa trabajo del agente del mismo humano. Materializa el set de Gafetes y filtra por __in.
created_by: El campo de autoria que firma cada elemento creado. Al operar con tu ApiToken, queda como tu alias de agente. Por eso debes crear elementos con tu token, no con el de un humano.; Para tu agente: No mandes created_by en el body: es read-only y lo auto-rellena el backend desde tu Gafete. Verifica que created_by_name salga como tu alias de agente.
modo_confirmacion: Politica de confirmacion del agente ante acciones destructivas. Valores: auto (ejecuta y avisa), confirma_destructivas (pide confirmacion antes de DELETE o UPDATE masivo) y confirma_todo (pide confirmacion antes de cualquier escritura).; Para tu agente: Respeta tu modo_confirmacion: en confirma_destructivas pide OK antes de borrar o de un update masivo; en confirma_todo pide OK antes de cualquier escritura.

Conexion

MCP / MCP Native: El protocolo (Model Context Protocol) por el que Abior expone sus tools al agente. El MCP nativo de Abior vive en https://abior.art/api/mcp/ (JSON-RPC 2.0 sobre HTTP+SSE) y se autentica con Authorization: Token ${ABIOR_APITOKEN}. Es la via preferida; la API REST es el respaldo.; Para tu agente: Prefiere las tools MCP sobre llamadas REST crudas: ya aplican scoping y created_by correctos. Si una tool no existe, cae a REST con tu ApiToken.
manual_search: Tool de busqueda full-text sobre los manuales orientados a agentes. Llamala antes de implementar para alinearte con las convenciones de Abior. Via REST: GET /api/artefa/manuales/search/?q=<termino>&audience=ai_agent&top_k=5.; Para tu agente: Llama manual_search con el prompt_original del usuario ANTES de crear la SD y reporta los top-3 hits en notas_proceso. Es paso obligatorio del flujo.
Manual / Capitulo / Hoja: La documentacion estructurada de Abior. Un Manual se organiza en Capitulos, y cada capitulo en Hojas (las unidades de contenido). El Manual del Agente AI es publico y se consulta con get_manual o manual_search.; Para tu agente: Al agregar/cambiar una funcion, documenta en los 3 manuales (Usuario / Agente / Desarrolladores). Si un manual esta incompleto, actualizalo (PATCH a la Hoja).

Mas documentacion para agentes

Conecta tu agente a Abior y aprende el flujo completo en la documentacion tecnica para agentes AI.

Documentacion para agentes Hub de documentacion