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

Añada una capacidad que la plataforma no haya creado. Defina la acción en LLM Apps, escriba su controlador en el repositorio vinculado y agregue un widget si es necesario.

En esta guía: Aprenda a definir una acción, implementar su controlador y conectar un widget opcional. Pruebe la acción localmente, implemente la aplicación e intente la acción en una plataforma LLM compatible.

Para tu primera aplicación, comienza con Configuración de infraestructura y luego Crea acciones. La guía Crear acciones explica la generación automática a partir de un sitio web y la creación manual.

Antes de empezar

Necesita:

Planificar la acción

Diseñe cada acción en torno a una tarea de usuario clara. Antes de abrir la interfaz de usuario de, defina:

Por ejemplo, use este plan para una acción de Buscar productos:

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. Utilice acciones independientes para la búsqueda de productos y la compra de productos porque las tareas 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 cuadro de diálogo de creación contiene las fichas Acción y Metadatos de widget. Expanda cada sección para configurar sus campos.

Introducir información básica

Escriba

El cuadro de diálogo deriva un identificador de código del nombre, como search-products. El identificador se fija después de la creación y debe ser único dentro de la aplicación. Utilice el identificador exacto de la carpeta de controladores.

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. La descripción del widget difiere de la descripción de la acción:

LLM Apps aplica la descripción del widget como metadatos de componente. No devuelva la descripción desde el controlador.

Configuración de visibilidad

Para una acción de solo texto, también selecciona Sin widget en Metadatos de widget > Tipo. Los controles de visibilidad no eligen el tipo de widget de la acción.

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.

La recopilación de intención de usuario está habilitada de forma predeterminada. Revise Descripción de la intención del usuario, que contiene las instrucciones para solicitar el resumen. Limite las instrucciones a intenciones no confidenciales y anónimas y describa la recopilación de datos en la política de privacidad. La descripción acepta hasta 2000 caracteres.

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

Configuración del widget

Para una acción de solo texto, abre Metadatos de widget y establece Type en Ningún widget. A continuación, omita los ajustes de widget restantes.

Abrir metadatos de widget.

Configuración de:

Expanda URL de plantilla e introduzca:

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.

Expanda Permisos (específicos de MCP) solo si el widget necesita funciones del explorador como la geolocalización. Deje los permisos sin utilizar desactivados.

En Configuración de CSP, agregue los orígenes necesarios para los recursos y las solicitudes de red. Es posible que un widget que carga recursos externos no se represente si su CSP está incompleto.

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.

Al guardar, se crean los metadatos, pero la acción sigue necesitando un controlador.

Cuando vuelva a abrir la acción guardada, el editor tiene Detalles del widget LLM, Detalles de la acción y Analytics fichas. Para guardar las ediciones posteriores, seleccione Guardar cambios. El cuadro de diálogo de creación y el editor de acciones guardadas tienen diferentes diseños.

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

La plataforma LLM lee content como texto de reserva:

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

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

Devolver structuredContent

El widget consume structuredContent como objeto sin formato:

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 las llamadas de API en el controlador del lado del servidor. Este ejemplo llama a una API de producto pública. Configure el origen HTTPS de la API en una variable de aplicación llamada PRODUCT_API_ORIGIN. El ejemplo acepta los parámetros query y category definidos anteriormente, requiere al menos un parámetro y no requiere credenciales.

const { getVariable } = require('@adobe/llm-apps-runtime');

module.exports = async ({ query = '', category = '' } = {}, extra) => {
  const normalizedQuery = typeof query === 'string' ? query.trim() : '';
  const normalizedCategory = typeof category === 'string' ? category.trim() : '';
  if (typeof query !== 'string' || typeof category !== 'string'
      || (!normalizedQuery && !normalizedCategory)
      || normalizedQuery.length > 200 || normalizedCategory.length > 100) {
    return {
      isError: true,
      content: [{ type: 'text', text: 'Enter a valid product search.' }],
      structuredContent: { products: [], total: 0 }
    };
  }

  const apiOrigin = getVariable(extra, 'PRODUCT_API_ORIGIN');
  if (!apiOrigin) {
    throw new Error('Product API configuration is unavailable.');
  }

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

  const url = new URL('/v1/products', origin);
  if (normalizedQuery) {
    url.searchParams.set('query', normalizedQuery);
  }
  if (normalizedCategory) {
    url.searchParams.set('category', normalizedCategory);
  }

  const response = await fetch(url, {
    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. Actualmente, la interfaz de usuario Variables y secretos solo admite variables no confidenciales, no secretos. No almacene un token de API en una variable. Si la API ascendente requiere credenciales, organice un mecanismo de credenciales del lado del servidor aprobado antes de conectarlo.

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.