Repositorio de prompts

La API de Prompts te permite almacenar, versionar y gestionar plantillas de prompts de forma centralizada. Cada cambio en la plantilla crea una versión inmutable, dándote un historial completo de cambios con la capacidad de revertir a cualquier versión anterior en cualquier momento. Las plantillas admiten marcadores de posición {{variable}} que se renderizan del lado del servidor cuando recuperas un prompt, por lo que puedes reutilizar la misma plantilla en diferentes contextos.

Crear un prompt

Crea un prompt con un nombre y una plantilla. La primera versión se crea automáticamente.

import { SDK } from '@meetkai/mka1';

const sdk = new SDK({ bearerAuth: 'Bearer <mka1-api-key>' });

const result = await sdk.llm.prompts.create({
  xOnBehalfOf: '<end-user-id>', // opcional — atribuye la solicitud a uno de tus usuarios finales
  createPromptRequest: {
    name: 'greeting',
    description: 'Una plantilla de saludo simple',
    template: 'Hello, {{name}}! Welcome to {{company}}.',
    metadata: { team: 'onboarding' },
  },
});

console.log(result.id);            // prompt_abc123...
console.log(result.activeVersion); // 1

const promptId = result.id; // usado en los ejemplos siguientes

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer <mka1-api-key>")

result = sdk.llm.prompts.create(
    name="greeting",
    description="Una plantilla de saludo simple",
    template="Hello, {{name}}! Welcome to {{company}}.",
    metadata={"team": "onboarding"},
)

print(result.id)              # prompt_abc123...
print(result.active_version)  # 1

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using MeetKai.MKA1.Types.Requests;

var sdk = new SDK(bearerAuth: "Bearer <mka1-api-key>");

var result = await sdk.Llm.Prompts.CreateAsync(
    new CreatePromptRequest
    {
        Name = "greeting",
        Description = "Una plantilla de saludo simple",
        Template = "Hello, {{name}}! Welcome to {{company}}.",
        Metadata = new Dictionary<string, object> { { "team", "onboarding" } },
    }
);

Console.WriteLine(result.CreatePromptResponseValue!.Id);            // prompt_abc123...
Console.WriteLine(result.CreatePromptResponseValue!.ActiveVersion); // 1

mka1 llm prompts create \
  --body '{
    "name": "greeting",
    "description": "Una plantilla de saludo simple",
    "template": "Hello, {{name}}! Welcome to {{company}}.",
    "metadata": { "team": "onboarding" }
  }' \
  -H 'X-On-Behalf-Of: <end-user-id>'

curl https://apigw.mka1.com/api/v1/llm/prompts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "greeting",
    "description": "Una plantilla de saludo simple",
    "template": "Hello, {{name}}! Welcome to {{company}}.",
    "metadata": { "team": "onboarding" }
  }'

Recuperar un prompt con variables renderizadas

Pasa variables como parámetro de consulta para renderizar la plantilla con tus valores. Los marcadores de posición no coincidentes se dejan tal cual. Opcionalmente, pasa version para recuperar (y renderizar) una versión específica. Si se omite, se devuelve la versión activa.

La respuesta siempre incluye active_template (activeTemplate en el SDK de TypeScript) — el texto sin procesar de la plantilla de la versión solicitada, con los {{placeholders}} intactos. Cuando pasas variables, la respuesta también incluye rendered_template (renderedTemplate) con el resultado sustituido; está ausente cuando no se proporcionan variables.

const prompt = await sdk.llm.prompts.get({
  xOnBehalfOf: '<end-user-id>',
  id: promptId,
  variables: JSON.stringify({ name: 'Alice', company: 'Acme' }),
});

console.log(prompt.renderedTemplate);
// "Hello, Alice! Welcome to Acme."

prompt = sdk.llm.prompts.get(
    id=prompt_id,
    variables='{"name": "Alice", "company": "Acme"}',
)

print(prompt.rendered_template)
# "Hello, Alice! Welcome to Acme."

var prompt = await sdk.Llm.Prompts.GetAsync(
    id: promptId,
    variables: "{\"name\":\"Alice\",\"company\":\"Acme\"}"
);

Console.WriteLine(prompt.GetPromptResponseValue!.RenderedTemplate);
// "Hello, Alice! Welcome to Acme."

mka1 llm prompts get \
  --id prompt_abc123 \
  --variables '{"name":"Alice","company":"Acme"}'

# Codifica en URL el JSON de variables
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123?variables=%7B%22name%22%3A%22Alice%22%2C%22company%22%3A%22Acme%22%7D" \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

Listar prompts

Recupera una lista paginada de todos los prompts. Usa after para paginación basada en cursor.

const list = await sdk.llm.prompts.list({
  xOnBehalfOf: '<end-user-id>',
  limit: 10,
  order: 'desc',
});

for (const prompt of list.data) {
  console.log(prompt.name, `v${prompt.activeVersion}`);
}

if (list.hasMore) {
  // Obtener la siguiente página usando el último ID como cursor
  const next = await sdk.llm.prompts.list({
    xOnBehalfOf: '<end-user-id>',
    limit: 10,
    after: list.lastId,
  });
}

prompts = sdk.llm.prompts.list()

for prompt in prompts.data:
    print(prompt.name, f"v{prompt.active_version}")

var prompts = await sdk.Llm.Prompts.ListAsync();

Console.WriteLine(prompts);

mka1 llm prompts list --limit 10 --order desc

curl "https://apigw.mka1.com/api/v1/llm/prompts?limit=10&order=desc" \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

Actualizar metadatos del prompt

Actualiza el nombre, la descripción o los metadatos de un prompt. Para cambiar la plantilla, crea una nueva versión en su lugar.

const updated = await sdk.llm.prompts.update({
  xOnBehalfOf: '<end-user-id>',
  id: promptId,
  requestBody: {
    name: 'welcome-greeting',
    description: 'Saludo actualizado para el flujo de bienvenida',
    metadata: { team: 'onboarding', reviewed: true },
  },
});

updated = sdk.llm.prompts.update(
    id=prompt_id,
    name="welcome-greeting",
    description="Saludo actualizado para el flujo de bienvenida",
    metadata={"team": "onboarding", "reviewed": True},
)

var updated = await sdk.Llm.Prompts.UpdateAsync(
    id: promptId,
    body: new UpdatePromptRequestBody
    {
        Name = "welcome-greeting",
        Description = "Saludo actualizado para el flujo de bienvenida",
        Metadata = new Dictionary<string, object>
        {
            { "team", "onboarding" },
            { "reviewed", true },
        },
    }
);

mka1 llm prompts update \
  --id prompt_abc123 \
  --body '{
    "name": "welcome-greeting",
    "description": "Saludo actualizado para el flujo de bienvenida",
    "metadata": { "team": "onboarding", "reviewed": true }
  }'

curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123" \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "welcome-greeting",
    "description": "Saludo actualizado para el flujo de bienvenida",
    "metadata": { "team": "onboarding", "reviewed": true }
  }'

Crear una nueva versión

Cada cambio en la plantilla crea una nueva versión. La nueva versión se activa automáticamente.

const version = await sdk.llm.prompts.createVersion({
  xOnBehalfOf: '<end-user-id>',
  id: promptId,
  requestBody: {
    template: 'Hi {{name}}! Welcome aboard at {{company}}. Your onboarding starts {{date}}.',
  },
});

console.log(version.version);  // 2
console.log(version.template); // El nuevo texto de la plantilla

version = sdk.llm.prompts.create_version(
    id=prompt_id,
    template="Hi {{name}}! Welcome aboard at {{company}}. Your onboarding starts {{date}}.",
)

print(version.version)   # 2
print(version.template)  # El nuevo texto de la plantilla

var version = await sdk.Llm.Prompts.CreateVersionAsync(
    id: promptId,
    body: new CreatePromptVersionRequestBody
    {
        Template = "Hi {{name}}! Welcome aboard at {{company}}. Your onboarding starts {{date}}.",
    }
);

Console.WriteLine(version.CreateVersionResponse!.Version);  // 2
Console.WriteLine(version.CreateVersionResponse!.Template); // El nuevo texto de la plantilla

mka1 llm prompts create-version \
  --id prompt_abc123 \
  --body '{
    "template": "Hi {{name}}! Welcome aboard at {{company}}. Your onboarding starts {{date}}."
  }'

curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/versions" \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "template": "Hi {{name}}! Welcome aboard at {{company}}. Your onboarding starts {{date}}."
  }'

Ver historial de versiones

Lista todas las versiones de un prompt para ver su historial completo de cambios.

const versions = await sdk.llm.prompts.listVersions({
  xOnBehalfOf: '<end-user-id>',
  id: promptId,
  order: 'desc',
});

for (const v of versions.data) {
  console.log(`v${v.version}: ${v.template.slice(0, 50)}...`);
}

versions = sdk.llm.prompts.list_versions(id=prompt_id)

for v in versions.data:
    print(f"v{v.version}: {v.template[:50]}...")

var versions = await sdk.Llm.Prompts.ListVersionsAsync(
    id: promptId,
    order: ListPromptVersionsOrder.Desc
);

foreach (var v in versions.ListVersionsResponse!.Data)
{
    Console.WriteLine($"v{v.Version}: {v.Template.Substring(0, 50)}...");
}

mka1 llm prompts list-versions --id prompt_abc123 --order desc

curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/versions?order=desc" \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

Recuperar una versión específica

Obtén una versión concreta por su número de versión.

const v1 = await sdk.llm.prompts.getVersion({
  xOnBehalfOf: '<end-user-id>',
  id: promptId,
  version: 1,
});

console.log(v1.template);

v1 = sdk.llm.prompts.get_version(id=prompt_id, version=1)

print(v1.template)

var v1 = await sdk.Llm.Prompts.GetVersionAsync(
    id: promptId,
    version: 1
);

Console.WriteLine(v1.CreateVersionResponse!.Template);

mka1 llm prompts get-version --id prompt_abc123 --version-param 1

curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/versions/1" \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

Revertir a una versión anterior

La reversión establece una versión anterior como la versión activa. Todas las versiones se conservan — la reversión no elimina las versiones más recientes, por lo que siempre puedes volver a avanzar.

// Actualmente en la versión 2, volver a la versión 1
const rolledBack = await sdk.llm.prompts.rollback({
  xOnBehalfOf: '<end-user-id>',
  id: promptId,
  requestBody: {
    version: 1,
  },
});

console.log(rolledBack.activeVersion);  // 1
console.log(rolledBack.latestVersion);  // 2 (sigue existiendo)

# Actualmente en la versión 2, volver a la versión 1
rolled_back = sdk.llm.prompts.rollback(id=prompt_id, version=1)

print(rolled_back.active_version)  # 1
print(rolled_back.latest_version)  # 2 (sigue existiendo)

// Actualmente en la versión 2, volver a la versión 1
var rolledBack = await sdk.Llm.Prompts.RollbackAsync(
    id: promptId,
    body: new RollbackPromptRequestBody { Version = 1 }
);

Console.WriteLine(rolledBack.UpdatePromptResponse!.ActiveVersion);  // 1
Console.WriteLine(rolledBack.UpdatePromptResponse!.LatestVersion);  // 2 (sigue existiendo)

# Actualmente en la versión 2, volver a la versión 1
mka1 llm prompts rollback --id prompt_abc123 --version-param 1

curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/rollback" \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{ "version": 1 }'

Eliminar un prompt

Eliminar un prompt lo elimina a él y a todas sus versiones de forma permanente.

const deleted = await sdk.llm.prompts.delete({
  xOnBehalfOf: '<end-user-id>',
  id: promptId,
});

console.log(deleted.deleted); // true

deleted = sdk.llm.prompts.delete(id=prompt_id)

print(deleted.deleted)  # True

var deleted = await sdk.Llm.Prompts.DeleteAsync(id: promptId);

Console.WriteLine(deleted.DeletePromptResponseValue!.Deleted); // True

mka1 llm prompts delete --id prompt_abc123

curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123" \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

Ejemplo completo: flujo de trabajo de versionado y reversión

Este ejemplo demuestra el ciclo de vida completo — crear un prompt, iterar sobre la plantilla, revisar el historial y revertir.

// 1. Crear un prompt con la plantilla inicial
const prompt = await sdk.llm.prompts.create({
  xOnBehalfOf: 'user-123',
  createPromptRequest: {
    name: 'support-reply',
    template: 'Hi {{customer}}, thanks for contacting us about {{issue}}.',
  },
});

console.log('Creado:', prompt.id, 'v1');

// 2. Publicar v2 con un tono más amigable
const v2 = await sdk.llm.prompts.createVersion({
  xOnBehalfOf: 'user-123',
  id: prompt.id,
  requestBody: {
    template: 'Hey {{customer}}! We got your message about {{issue}} and are on it.',
  },
});

console.log('Creada v2:', v2.version);

// 3. Recuperar el prompt — la versión activa ahora es v2
const current = await sdk.llm.prompts.get({
  xOnBehalfOf: 'user-123',
  id: prompt.id,
  variables: JSON.stringify({ customer: 'Alice', issue: 'billing' }),
});

console.log('Activo:', current.renderedTemplate);
// "Hey Alice! We got your message about billing and are on it."

// 4. Revisar el historial de versiones
const history = await sdk.llm.prompts.listVersions({
  xOnBehalfOf: 'user-123',
  id: prompt.id,
  order: 'asc',
});

for (const v of history.data) {
  console.log(`  v${v.version}: ${v.template}`);
}

// 5. Revertir a v1
const rolledBack = await sdk.llm.prompts.rollback({
  xOnBehalfOf: 'user-123',
  id: prompt.id,
  requestBody: {
    version: 1,
  },
});

console.log('Revertido a v' + rolledBack.activeVersion);
// activeVersion=1, latestVersion=2

// 6. Limpiar
await sdk.llm.prompts.delete({ xOnBehalfOf: 'user-123', id: prompt.id });

# 1. Crear un prompt con la plantilla inicial
prompt = sdk.llm.prompts.create(
    name="support-reply",
    template="Hi {{customer}}, thanks for contacting us about {{issue}}.",
)

print("Creado:", prompt.id, "v1")

# 2. Publicar v2 con un tono más amigable
v2 = sdk.llm.prompts.create_version(
    id=prompt.id,
    template="Hey {{customer}}! We got your message about {{issue}} and are on it.",
)

print("Creada v2:", v2.version)

# 3. Recuperar el prompt — la versión activa ahora es v2
current = sdk.llm.prompts.get(
    id=prompt.id,
    variables='{"customer": "Alice", "issue": "billing"}',
)

print("Activo:", current.rendered_template)
# "Hey Alice! We got your message about billing and are on it."

# 4. Revisar el historial de versiones
history = sdk.llm.prompts.list_versions(id=prompt.id)

for v in history.data:
    print(f"  v{v.version}: {v.template}")

# 5. Revertir a v1
rolled_back = sdk.llm.prompts.rollback(id=prompt.id, version=1)

print("Revertido a v" + str(rolled_back.active_version))
# active_version=1, latest_version=2

# 6. Limpiar
sdk.llm.prompts.delete(id=prompt.id)

// 1. Crear un prompt con la plantilla inicial
var prompt = await sdk.Llm.Prompts.CreateAsync(
    new CreatePromptRequest
    {
        Name = "support-reply",
        Template = "Hi {{customer}}, thanks for contacting us about {{issue}}.",
    }
);

var promptId = prompt.CreatePromptResponseValue!.Id;
Console.WriteLine($"Creado: {promptId} v1");

// 2. Publicar v2 con un tono más amigable
var v2 = await sdk.Llm.Prompts.CreateVersionAsync(
    id: promptId,
    body: new CreatePromptVersionRequestBody
    {
        Template = "Hey {{customer}}! We got your message about {{issue}} and are on it.",
    }
);

Console.WriteLine($"Creada v2: {v2.CreateVersionResponse!.Version}");

// 3. Recuperar el prompt con variables renderizadas
var current = await sdk.Llm.Prompts.GetAsync(
    id: promptId,
    variables: "{\"customer\":\"Alice\",\"issue\":\"billing\"}"
);

Console.WriteLine($"Activo: {current.GetPromptResponseValue!.RenderedTemplate}");

// 4. Revisar el historial de versiones
var history = await sdk.Llm.Prompts.ListVersionsAsync(
    id: promptId,
    order: ListPromptVersionsOrder.Asc
);

foreach (var v in history.ListVersionsResponse!.Data)
{
    Console.WriteLine($"  v{v.Version}: {v.Template}");
}

// 5. Revertir a v1
var rolledBack = await sdk.Llm.Prompts.RollbackAsync(
    id: promptId,
    body: new RollbackPromptRequestBody { Version = 1 }
);

Console.WriteLine($"Revertido a v{rolledBack.UpdatePromptResponse!.ActiveVersion}");

// 6. Limpiar
await sdk.Llm.Prompts.DeleteAsync(id: promptId);

# 1. Crear un prompt con la plantilla inicial
mka1 llm prompts create \
  --body '{
    "name": "support-reply",
    "template": "Hi {{customer}}, thanks for contacting us about {{issue}}."
  }'
# → { "id": "prompt_abc123", "active_version": 1, ... }

# 2. Publicar v2 con un tono más amigable
mka1 llm prompts create-version \
  --id prompt_abc123 \
  --body '{
    "template": "Hey {{customer}}! We got your message about {{issue}} and are on it."
  }'

# 3. Recuperar el prompt con variables renderizadas
mka1 llm prompts get \
  --id prompt_abc123 \
  --variables '{"customer":"Alice","issue":"billing"}'

# 4. Revisar el historial de versiones
mka1 llm prompts list-versions --id prompt_abc123 --order asc

# 5. Revertir a v1
mka1 llm prompts rollback --id prompt_abc123 --version-param 1

# 6. Limpiar
mka1 llm prompts delete --id prompt_abc123

# 1. Crear un prompt
curl https://apigw.mka1.com/api/v1/llm/prompts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: user-123' \
  --data '{
    "name": "support-reply",
    "template": "Hi {{customer}}, thanks for contacting us about {{issue}}."
  }'
# → { "id": "prompt_abc123", "active_version": 1, ... }

# 2. Crear v2 con un tono más amigable
curl https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/versions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: user-123' \
  --data '{
    "template": "Hey {{customer}}! We got your message about {{issue}} and are on it."
  }'

# 3. Obtener el prompt con variables renderizadas
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123?variables=%7B%22customer%22%3A%22Alice%22%2C%22issue%22%3A%22billing%22%7D" \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: user-123'

# 4. Ver historial de versiones
curl "https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/versions?order=asc" \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: user-123'

# 5. Revertir a v1
curl https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123/rollback \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: user-123' \
  --data '{ "version": 1 }'

# 6. Eliminar el prompt
curl https://apigw.mka1.com/api/v1/llm/prompts/prompt_abc123 \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: user-123'

Detalles de comportamiento

Aspecto	Detalle
Versionado	Inmutable — cada cambio en la plantilla crea una nueva versión que no puede ser modificada
Versión activa	Las nuevas versiones se activan automáticamente; usa la reversión para cambiar a otra versión
Reversión	No destructiva — establece `active_version` sin eliminar versiones más recientes
Paginación	Basada en cursor para listar prompts — usa el parámetro `after` con `first_id`/`last_id` de la respuesta
Renderizado de plantillas	Del lado del servidor — pasa el parámetro de consulta `variables`; los marcadores no coincidentes se conservan
Propiedad	Por clave de API — los prompts están aislados por contexto de autenticación
Concurrencia	Detección de conflictos — la creación concurrente de versiones devuelve 409

Próximos pasos

Generar una respuesta — usa prompts renderizados como entrada para la API de Respuestas
Extraer datos estructurados — combina prompts con extracción estructurada
Conversaciones — gestiona intercambios de varios turnos con prompts de sistema versionados

Comenzar

SDKs y CLI

Respuestas

APIs independientes

Agentes

Compute

Producción

Repositorio de prompts

Crear un prompt

Recuperar un prompt con variables renderizadas

Listar prompts

Actualizar metadatos del prompt

Crear una nueva versión

Ver historial de versiones

Recuperar una versión específica

Revertir a una versión anterior

Eliminar un prompt

Ejemplo completo: flujo de trabajo de versionado y reversión

Detalles de comportamiento

Próximos pasos

​Crear un prompt

​Recuperar un prompt con variables renderizadas

​Listar prompts

​Actualizar metadatos del prompt

​Crear una nueva versión

​Ver historial de versiones

​Recuperar una versión específica

​Revertir a una versión anterior

​Eliminar un prompt

​Ejemplo completo: flujo de trabajo de versionado y reversión

​Detalles de comportamiento

​Próximos pasos

Crear un prompt

Recuperar un prompt con variables renderizadas

Listar prompts

Actualizar metadatos del prompt

Crear una nueva versión

Ver historial de versiones

Recuperar una versión específica

Revertir a una versión anterior

Eliminar un prompt

Ejemplo completo: flujo de trabajo de versionado y reversión

Detalles de comportamiento

Próximos pasos