aia-tool

Motor determinístico para ejecutar automatizaciones definidas en JSON (formato AIA): recorre acciones en orden, resuelve variables {{nombre}} contra un contexto y delega en funciones que vos registrás (tools). No usa modelos de lenguaje en la ejecución.

Inicio con plantillas (agente / MCP)

Sin ruido en npm install. Cuando quieras, generá en tu proyecto AGENTS.md, ejemplos de config, tools, MCP y un runner:

npx --yes aia-tool init

Si el comando no resuelve el bin, usá explícitamente:

npx --yes --package=aia-tool aia init

Con el paquete ya en devDependencies / dependencies:

npx aia init

Opcional: npx aia init --dir ./mi-proyecto --force.

Luego abrí y seguí AGENTS.md (idealmente junto con tu agente de IA en Cursor, Claude Code, etc.) para implementar tools reales y, si aplica, el MCP del producto.

Instalación

npm install aia-tool

Uso rápido

import { executeAIA } from "aia-tool";

const config = {
  aia_version: "1.0",
  actions: [
    {
      type: "send_email",
      params: {
        to: "{{user_email}}",
        subject: "Hola {{user_name}}",
      },
    },
  ],
};

const tools = {
  send_email: async ({ to, subject }) => {
    // integración real (API, cola, etc.)
    return { ok: true, to, subject };
  },
};

const context = {
  user_email: "[email protected]",
  user_name: "Ana",
};

const results = await executeAIA(config, tools, context);
// results: un elemento por acción ejecutada

Reglas

• Variables en strings: {{variable}} (espacios alrededor del nombre permitidos).
• Si falta una clave en context al resolver, se lanza error.
• Si tools[type] no existe o no es función, se lanza error.
• Las acciones se ejecutan en orden, en serie (await por acción).

API exportada

| Export | Descripción | |--------|-------------| | executeAIA(config, tools, context?) | Ejecuta todas las acciones. | | resolveParams(value, context) | Sustituye {{}} en strings y estructuras anidadas. | | validateAIAConfig(config) | Valida forma mínima del config (sin ejecutar). | | listMissingToolTypes(config, tools) | Lista type de acciones sin función en tools. | | mockTools / mockToolNames | Registry mock (p. ej. send_email sin efectos reales). |

Ejemplo en el repo del paquete

Tras clonar o en desarrollo local:

npm install
node test.js
npm run example:pilot

El piloto examples/pilot-barberia/ simula el envío de un correo tras un turno.

MCP (Model Context Protocol)

Incluye un servidor stdio para clientes como Cursor, útil para validar configs, resolver placeholders, comprobar tools y ejecutar con registry mock.

Binario: aia-mcp

Cursor (ejemplo)

"aia-tool": {
  "command": "npx",
  "args": ["--yes", "--package=aia-tool", "aia-mcp"]
}

Herramientas expuestas:

• aia_validate_config
• aia_resolve_params
• aia_list_missing_tools
• aia_execute_mock (solo tools mock; hoy incluye send_email simulado)

Requisitos

• Node.js 18+
• Proyecto con "type": "module" (o bundler que entienda ESM) al importar el paquete.

Licencia

MIT