Crear una acción desde cero create-action-from-scratch

Utilice esta guía para añadir una capacidad que la plataforma no ha creado. Definirá la acción en LLM Apps, escribirá su controlador en el repositorio vinculado, agregará un widget si es necesario, lo probará e implementará.

Recorrido: Planifique la acción → crear sus metadatos → escribir el controlador → conectar el widget → probar localmente → implementar y probar el complemento.

Para tu primera aplicación, comienza con Crea tu primera aplicación automáticamente.

Antes de empezar

Necesita:

Planificar la acción

Una acción debe realizar una tarea de borrado de usuario. Antes de abrir la interfaz de usuario de, defina:

Por ejemplo, una acción Buscar productos podría usar:

Intent: Find products matching a category or search phrase
Inputs:
  category: optional string
  query: optional string
Result:
  content: text summary
  structuredContent: products and total count
Behavior: read-only, idempotent, open-world
Widget: product cards

Mantenga las tareas relacionadas pero diferentes separadas. La búsqueda de productos y la compra de productos no deben ser una acción única, ya que tienen diferentes entradas, riesgos y requisitos de confirmación.

Creación de metadatos de acción

Abra la aplicación, seleccione Acciones y luego seleccione Crear acción.

El editor contiene las fichas Acción y Metadatos de widget.

Introducir información básica

Escriba

Una descripción útil es específica:

Search the product catalog by category or keyword. Returns matching
products with their names, prices, categories, and image URLs.

Evite descripciones vagas como Obtiene información del producto. La plataforma LLM utiliza la descripción para elegir entre acciones.

Seleccionar anotaciones

Las anotaciones describen el comportamiento de la acción:

Seleccione solo las anotaciones que sean verdaderas. Por ejemplo, la búsqueda de productos suele ser de solo lectura, idempotente y de mundo abierto.

Añadir metadatos de OpenAI

Introduzca los mensajes cortos que se muestran mientras se ejecuta la acción y después de que se complete:

Invoking: Searching products...
Invoked: Products found

Para acciones con widgets, agregue Descripción del widget. Esto es diferente a la descripción de la acción:

LLM Apps aplica esto como metadatos de componente. No lo devuelva desde el controlador.

Configuración de visibilidad

Deshabilite la visibilidad del widget cuando la acción devuelva solo texto.

Añadir parámetros de entrada

Agregue un parámetro para cada valor que acepte el controlador. Todos los parámetros necesitan:

Para Buscar productos:

category
  Type: String
  Required: No
  Description: Product category used to narrow the catalog.

query
  Type: String
  Required: No
  Description: Product name or search phrase.

Utilice nombres de parámetros estables. Para cambiar un nombre también es necesario cambiar el controlador y sus pruebas.

Configurar Analytics

Habilite Recopilar la intención del usuario cuando quiera que Analytics incluya un resumen de la conversación que provocó la acción.

Para ver las definiciones de campo completas, consulte Campos de acción y widget.

Configuración del widget

Omita esta sección para una acción de solo texto.

Abrir metadatos de widget.

Configuración de:

Las direcciones URL habituales son:

Script URL:
https://main--<repo>--<owner>.aem.live/scripts/aem-embed.js

Widget URL:
https://main--<repo>--<owner>.aem.live/<widget-page>

Conceda solo los permisos de explorador y los dominios CSP necesarios.

Si el proyecto EDS o la página del widget aún no existen, complete Traiga su propio proyecto EDS y vuelva a la acción.

Guardar la acción

Seleccione Crear nueva acción. La acción aparece en la página Acciones con el distintivo No implementado.

En este punto, los metadatos existen, pero la acción todavía necesita un controlador.

Implementar el controlador

Clone el repositorio de controladores vinculado e instale sus dependencias:

npm install

Crear:

actions/
└── search-products/
    └── index.js

El nombre de la carpeta debe coincidir con el identificador de código de la acción que se muestra en el editor de acciones.

Para obtener el contrato de resultados completo y la relación controlador-widget, consulte Personalizar un controlador generado.

Contrato de controlador

Exporte una función asíncrona:

module.exports = async (args) => {
  return {
    content: [
      { type: 'text', text: 'Response for the LLM platform.' }
    ],
    structuredContent: {
      // Data for the widget.
    }
  };
};

El controlador recibe los parámetros definidos en la interfaz de usuario.

Devolver content

content es la reserva de texto leída por la plataforma LLM:

content: [
  { type: 'text', text: 'Found 3 matching products.' }
]

Siempre devuelve content útil, incluso cuando la acción tiene un widget.

Devolver structuredContent

structuredContent es un objeto sin formato consumido por el widget:

structuredContent: {
  products: [
    { id: 'P-100', name: 'Product A', price: '$20' }
  ],
  total: 1
}

La forma debe coincidir con lo que lee el bloque EDS de bridge.toolResult.

Conexión de una API

Mantenga el acceso a la API protegida en el controlador del lado del servidor. Cargue la configuración desde el entorno de tiempo de ejecución y utilice un origen HTTPS fijo.

const API_ORIGIN = process.env.PRODUCT_API_ORIGIN;
const API_TOKEN = process.env.PRODUCT_API_TOKEN;

module.exports = async ({ query = '' } = {}) => {
  const normalizedQuery = String(query).trim();
  if (!normalizedQuery || normalizedQuery.length > 200) {
    return {
      content: [{ type: 'text', text: 'Enter a valid product search.' }],
      structuredContent: { products: [], total: 0 }
    };
  }

  if (!API_ORIGIN || !API_TOKEN) {
    throw new Error('Product API configuration is unavailable.');
  }

  const origin = new URL(API_ORIGIN);
  if (origin.protocol !== 'https:') {
    throw new Error('Product API configuration must use HTTPS.');
  }

  const url = new URL('/v1/products', origin);
  url.searchParams.set('query', normalizedQuery);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${API_TOKEN}` },
    signal: AbortSignal.timeout(8000)
  });

  if (!response.ok) {
    throw new Error('Product service request failed.');
  }

  const payload = await response.json();
  if (!payload || !Array.isArray(payload.products)
      || !payload.products.every((product) =>
        product
        && typeof product.id === 'string'
        && typeof product.name === 'string'
        && typeof product.price === 'string')) {
    throw new Error('Product service returned an unexpected response.');
  }

  const products = payload.products.map((product) => ({
    id: product.id,
    name: product.name,
    price: product.price
  }));

  return {
    content: [
      { type: 'text', text: `Found ${products.length} matching products.` }
    ],
    structuredContent: {
      products,
      total: products.length
    }
  };
};

No coloque credenciales de API en el código fuente, metadatos de acción, JavaScript de widget, registros o errores de cara al usuario.

Para el código de producción, valide la respuesta ascendente completa antes de asignar los campos aprobados a structuredContent.

Agregar pruebas de controlador

Cree la prueba coincidente:

test/
└── actions/
    └── search-products.test.js

Probar al menos:

Ejecutar:

npm test

Para obtener información sobre el diseño del proyecto y las pruebas de MCP local, vea Desarrollo y prueba de controladores locales.

Prueba de la acción localmente

Ejecutar:

npm run dev:local

Sin un actions.json local, el servidor detecta el controlador con metadatos mínimos y sin validación de esquema de entrada.

Use el Inspector MCP o curl para:

Conexión y prueba del widget

Si la acción tiene un widget:

Consulte Traer su propio proyecto EDS.

Implementación y prueba

Si los metadatos existen sin un controlador coincidente, la implementación registra la acción con un código auxiliar predeterminado. Agregue el controlador antes de poner la acción a disposición de los usuarios.