For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegación principal
Theme

Generación de prompts

Genera prompts y esquemas en Playground.

Con el botón Generar de Playground, basta con describir tu tarea para generar prompts, funciones y esquemas. En esta guía verás paso a paso cómo funciona.

Descripción general

Crear prompts y esquemas desde cero puede llevar tiempo. Generarlos puede ayudarte a empezar más rápido. El botón Generar utiliza dos métodos principales:

  1. Prompts: usamos metaprompts que incorporan buenas prácticas para generar o mejorar prompts.
  2. Esquemas: usamos metaesquemas para generar JSON válido y funciones con la sintaxis correcta.

Actualmente usamos metaprompts y metaesquemas. En el futuro podríamos incorporar técnicas más avanzadas, como DSPy y el “descenso de gradiente”.

Prompts

Un metaprompt le indica al modelo cómo crear un buen prompt a partir de la descripción de tu tarea o cómo mejorar uno existente. Los metaprompts de Playground se basan en nuestras buenas prácticas de ingeniería de prompts y en nuestra experiencia directa con los usuarios.

Usamos metaprompts específicos para distintos tipos de salida, como el audio, para que los prompts generados se ajusten al formato esperado.

Metaprompts

Metaprompt para texto
import OpenAI from "openai";

const client = new OpenAI();

const metaPrompt = `Given a task description or existing prompt, produce a detailed system prompt to guide a language model in completing the task effectively.

# Guidelines

- Understand the Task: Grasp the main objective, goals, requirements, constraints, and expected output.
- Minimal Changes: If an existing prompt is provided, improve it only if it's simple. For complex prompts, enhance clarity and add missing elements without altering the original structure.
- Reasoning Before Conclusions**: Encourage reasoning steps before any conclusions are reached. ATTENTION! If the user provides examples where the reasoning happens afterward, REVERSE the order! NEVER START EXAMPLES WITH CONCLUSIONS!
    - Reasoning Order: Call out reasoning portions of the prompt and conclusion parts (specific fields by name). For each, determine the ORDER in which this is done, and whether it needs to be reversed.
    - Conclusion, classifications, or results should ALWAYS appear last.
- Examples: Include high-quality examples if helpful, using placeholders [in brackets] for complex elements.
   - What kinds of examples may need to be included, how many, and whether they are complex enough to benefit from placeholders.
- Clarity and Conciseness: Use clear, specific language. Avoid unnecessary instructions or bland statements.
- Formatting: Use markdown features for readability. DO NOT USE \`\`\` CODE BLOCKS UNLESS SPECIFICALLY REQUESTED.
- Preserve User Content: If the input task or prompt includes extensive guidelines or examples, preserve them entirely, or as closely as possible. If they are vague, consider breaking down into sub-steps. Keep any details, guidelines, examples, variables, or placeholders provided by the user.
- Constants: DO include constants in the prompt, as they are not susceptible to prompt injection. Such as guides, rubrics, and examples.
- Output Format: Explicitly the most appropriate output format, in detail. This should include length and syntax (e.g. short sentence, paragraph, JSON, etc.)
    - For tasks outputting well-defined or structured data (classification, JSON, etc.) bias toward outputting a JSON.
    - JSON should never be wrapped in code blocks (\`\`\`) unless explicitly requested.

The final prompt you output should adhere to the following structure below. Do not include any additional commentary, only output the completed system prompt. SPECIFICALLY, do not include any additional messages at the start or end of the prompt. (e.g. no "---")

[Concise instruction describing the task - this should be the first line in the prompt, no section header]

[Additional details as needed.]

[Optional sections with headings or bullet points for detailed steps.]

# Steps [optional]

[optional: a detailed breakdown of the steps necessary to accomplish the task]

# Output Format

[Specifically call out how the output should be formatted, be it response length, structure e.g. JSON, markdown, etc]

# Examples [optional]

[Optional: 1-3 well-defined examples with placeholders if necessary. Clearly mark where examples start and end, and what the input and output are. User placeholders as necessary.]
[If the examples are shorter than what a realistic example is expected to be, make a reference with () explaining how real examples should be longer / shorter / different. AND USE PLACEHOLDERS! ]

# Notes [optional]

[optional: edge cases, details, and an area to call or repeat out specific important considerations]`;

async function generatePrompt(taskOrPrompt) {
  const completion = await client.chat.completions.create({
    model: "gpt-6-astra",
    messages: [
      { role: "system", content: metaPrompt },
      {
        role: "user",
        content: "Task, Goal, or Current Prompt:\n" + taskOrPrompt,
      },
    ],
  });

  return completion.choices[0].message.content;
}

console.log(
  await generatePrompt("Write a concise product launch announcement.")
);

Edición de prompts

Para editar prompts, usamos un metaprompt ligeramente modificado. Aplicar cambios concretos es sencillo, pero cuando la solicitud de revisión es más abierta, puede ser difícil determinar qué cambiar. Por eso incluimos una sección de razonamiento al principio de la respuesta. Esta sección ayuda al modelo a determinar qué cambios hacen falta. Para ello, el modelo evalúa la claridad del prompt existente, el orden de los pasos de la cadena de pensamiento, la estructura general y el nivel de detalle, entre otros factores. La sección de razonamiento contiene sugerencias de mejora y se elimina al procesar la respuesta final.

Metaprompt para editar prompts de texto
import OpenAI from "openai";

const client = new OpenAI();

const metaPrompt = `Given a current prompt and a change description, produce a detailed system prompt to guide a language model in completing the task effectively.

Your final output will be the full corrected prompt verbatim. However, before that, at the very beginning of your response, use <reasoning> tags to analyze the prompt and determine the following, explicitly:
<reasoning>
- Simple Change: (yes/no) Is the change description explicit and simple? (If so, skip the rest of these questions.)
- Reasoning: (yes/no) Does the current prompt use reasoning, analysis, or chain of thought?
    - Identify: (max 10 words) if so, which section(s) utilize reasoning?
    - Conclusion: (yes/no) is the chain of thought used to determine a conclusion?
    - Ordering: (before/after) is the chain of though located before or after
- Structure: (yes/no) does the input prompt have a well defined structure
- Examples: (yes/no) does the input prompt have few-shot examples
    - Representative: (1-5) if present, how representative are the examples?
- Complexity: (1-5) how complex is the input prompt?
    - Task: (1-5) how complex is the implied task?
    - Necessity: ()
- Specificity: (1-5) how detailed and specific is the prompt? (not to be confused with length)
- Prioritization: (list) what 1-3 categories are the MOST important to address.
- Conclusion: (max 30 words) given the previous assessment, give a very concise, imperative description of what should be changed and how. this does not have to adhere strictly to only the categories listed
</reasoning>

# Guidelines

- Understand the Task: Grasp the main objective, goals, requirements, constraints, and expected output.
- Minimal Changes: If an existing prompt is provided, improve it only if it's simple. For complex prompts, enhance clarity and add missing elements without altering the original structure.
- Reasoning Before Conclusions**: Encourage reasoning steps before any conclusions are reached. ATTENTION! If the user provides examples where the reasoning happens afterward, REVERSE the order! NEVER START EXAMPLES WITH CONCLUSIONS!
    - Reasoning Order: Call out reasoning portions of the prompt and conclusion parts (specific fields by name). For each, determine the ORDER in which this is done, and whether it needs to be reversed.
    - Conclusion, classifications, or results should ALWAYS appear last.
- Examples: Include high-quality examples if helpful, using placeholders [in brackets] for complex elements.
   - What kinds of examples may need to be included, how many, and whether they are complex enough to benefit from placeholders.
- Clarity and Conciseness: Use clear, specific language. Avoid unnecessary instructions or bland statements.
- Formatting: Use markdown features for readability. DO NOT USE \`\`\` CODE BLOCKS UNLESS SPECIFICALLY REQUESTED.
- Preserve User Content: If the input task or prompt includes extensive guidelines or examples, preserve them entirely, or as closely as possible. If they are vague, consider breaking down into sub-steps. Keep any details, guidelines, examples, variables, or placeholders provided by the user.
- Constants: DO include constants in the prompt, as they are not susceptible to prompt injection. Such as guides, rubrics, and examples.
- Output Format: Explicitly the most appropriate output format, in detail. This should include length and syntax (e.g. short sentence, paragraph, JSON, etc.)
    - For tasks outputting well-defined or structured data (classification, JSON, etc.) bias toward outputting a JSON.
    - JSON should never be wrapped in code blocks (\`\`\`) unless explicitly requested.

The final prompt you output should adhere to the following structure below. Do not include any additional commentary, only output the completed system prompt. SPECIFICALLY, do not include any additional messages at the start or end of the prompt. (e.g. no "---")

[Concise instruction describing the task - this should be the first line in the prompt, no section header]

[Additional details as needed.]

[Optional sections with headings or bullet points for detailed steps.]

# Steps [optional]

[optional: a detailed breakdown of the steps necessary to accomplish the task]

# Output Format

[Specifically call out how the output should be formatted, be it response length, structure e.g. JSON, markdown, etc]

# Examples [optional]

[Optional: 1-3 well-defined examples with placeholders if necessary. Clearly mark where examples start and end, and what the input and output are. User placeholders as necessary.]
[If the examples are shorter than what a realistic example is expected to be, make a reference with () explaining how real examples should be longer / shorter / different. AND USE PLACEHOLDERS! ]

# Notes [optional]

[optional: edge cases, details, and an area to call or repeat out specific important considerations]
[NOTE: you must start with a <reasoning> section. the immediate next token you produce should be <reasoning>]`;

async function generatePrompt(taskOrPrompt) {
  const completion = await client.chat.completions.create({
    model: "gpt-6-astra",
    messages: [
      { role: "system", content: metaPrompt },
      {
        role: "user",
        content: "Task, Goal, or Current Prompt:\n" + taskOrPrompt,
      },
    ],
  });

  return completion.choices[0].message.content;
}

console.log(
  await generatePrompt("Make this support prompt more concise and empathetic.")
);

Esquemas

Los esquemas de resultados estructurados y los esquemas de funciones son objetos JSON, así que usamos resultados estructurados para generarlos. Para ello, necesitamos definir un esquema que describa el resultado deseado, que en este caso también es un esquema. Usamos un esquema que se describe a sí mismo, llamado metaesquema.

Como el campo parameters de un esquema de función también es un esquema, usamos el mismo metaesquema para generar funciones.

Definición de un metaesquema con restricciones

Los resultados estructurados admiten dos modos: strict=true y strict=false. Ambos usan el mismo modelo, entrenado para seguir el esquema proporcionado, pero solo el “modo estricto” garantiza el cumplimiento exacto del esquema mediante un muestreo restringido.

Nuestro objetivo es usar el modo estricto para generar esquemas compatibles con ese mismo modo. Sin embargo, los metaesquemas oficiales de la especificación JSON Schema dependen de características que el modo estricto aún no admite. Esto plantea dificultades tanto para el esquema de entrada como para el de salida.

  1. Esquema de entrada: no podemos usar características no admitidas en el esquema de entrada para describir el esquema de salida.
  2. Esquema de salida: el esquema generado no debe incluir características no admitidas.

Como necesitamos generar claves nuevas en el esquema de salida, el metaesquema de entrada debe usar additionalProperties. Por eso, por ahora no podemos usar el modo estricto para generar esquemas. Aun así, queremos que el esquema generado cumpla las restricciones de ese modo.

Para superar esta limitación, definimos un pseudometaesquema. Se trata de un metaesquema que utiliza características que el modo estricto no admite para describir únicamente las que sí admite. Así podemos definir el metaesquema fuera del modo estricto y, al mismo tiempo, garantizar que los esquemas generados cumplan las restricciones de ese modo.

Deep dive
Cómo diseñamos el pseudometaesquema

Depuración de la salida

El modo estricto garantiza el cumplimiento exacto del esquema. Como no podemos usarlo durante la generación, necesitamos validar y transformar la salida una vez generada.

Después de generar un esquema, seguimos estos pasos:

  1. Asignamos a additionalProperties el valor false en todos los objetos.
  2. Marcamos todas las propiedades como obligatorias.
  3. Para los esquemas de resultados estructurados, colocamos el esquema dentro de un objeto json_schema.
  4. Para las funciones, colocamos la función dentro de un objeto function.

El objeto de función de la Realtime API difiere ligeramente del que usa la API para completar chats, pero ambos usan el mismo esquema.

Metaesquemas

Cada metaesquema tiene un prompt asociado que incluye unos pocos ejemplos. Al combinar estos prompts con la fiabilidad de los resultados estructurados, pudimos generar esquemas incluso sin usar el modo estricto.

Metaesquema de resultados estructurados
import OpenAI from "openai";

const client = new OpenAI();

const schemaDefinition = {
  type: "object",
  properties: {
    description: { type: "string" },
    type: {
      type: "string",
      enum: ["object", "array", "string", "number", "boolean", "null"],
    },
    properties: {
      type: "object",
      additionalProperties: { $ref: "#/$defs/schema_definition" },
    },
    items: {
      anyOf: [
        { $ref: "#/$defs/schema_definition" },
        { type: "array", items: { $ref: "#/$defs/schema_definition" } },
      ],
    },
    required: { type: "array", items: { type: "string" } },
    additionalProperties: { type: "boolean" },
    enum: { type: "array", minItems: 1, uniqueItems: true },
    $ref: { type: "string" },
    $defs: {
      type: "object",
      additionalProperties: { $ref: "#/$defs/schema_definition" },
    },
    anyOf: {
      type: "array",
      minItems: 1,
      items: { $ref: "#/$defs/schema_definition" },
    },
  },
  additionalProperties: false,
  if: { required: ["type"], properties: { type: { const: "object" } } },
  then: { required: ["properties"] },
};

const metaSchema = {
  name: "metaschema",
  schema: {
    ...schemaDefinition,
    required: ["type"],
    properties: {
      name: { type: "string", description: "The name of the schema" },
      ...schemaDefinition.properties,
    },
    $defs: {
      schema_definition: {
        ...schemaDefinition,
        anyOf: [
          { required: ["type"] },
          { required: ["$ref"] },
          { required: ["anyOf"] },
        ],
      },
    },
  },
};

const metaPrompt = `# Instructions
Return a valid schema for the described JSON.

You must also make sure:
- all fields in an object are set as required
- I REPEAT, ALL FIELDS MUST BE MARKED AS REQUIRED
- all objects must have additionalProperties set to false
    - because of this, some cases like "attributes" or "metadata" properties that would normally allow additional properties should instead have a fixed set of properties
- all objects must have properties defined
- field order matters. any form of "thinking" or "explanation" should come before the conclusion
- $defs must be defined under the schema param

Notable keywords NOT supported include:
- For objects: unevaluatedProperties, propertyNames, minProperties, maxProperties
- For arrays: unevaluatedItems, contains, minContains, maxContains, uniqueItems

Other notes:
- definitions and recursion are supported
- only if necessary to include references e.g. "$defs", it must be inside the "schema" object

# Examples
Input: Generate a math reasoning schema with steps and a final answer.
Output: {
    "name": "math_reasoning",
    "type": "object",
    "properties": {
        "steps": {
            "type": "array",
            "description": "A sequence of steps involved in solving the math problem.",
            "items": {
                "type": "object",
                "properties": {
                    "explanation": {
                        "type": "string",
                        "description": "Description of the reasoning or method used in this step."
                    },
                    "output": {
                        "type": "string",
                        "description": "Result or outcome of this specific step."
                    }
                },
                "required": [
                    "explanation",
                    "output"
                ],
                "additionalProperties": false
            }
        },
        "final_answer": {
            "type": "string",
            "description": "The final solution or answer to the math problem."
        }
    },
    "required": [
        "steps",
        "final_answer"
    ],
    "additionalProperties": false
}

Input: Give me a linked list
Output: {
    "name": "linked_list",
    "type": "object",
    "properties": {
        "linked_list": {
            "$ref": "#/$defs/linked_list_node",
            "description": "The head node of the linked list."
        }
    },
    "$defs": {
        "linked_list_node": {
            "type": "object",
            "description": "Defines a node in a singly linked list.",
            "properties": {
                "value": {
                    "type": "number",
                    "description": "The value stored in this node."
                },
                "next": {
                    "anyOf": [
                        {
                            "$ref": "#/$defs/linked_list_node"
                        },
                        {
                            "type": "null"
                        }
                    ],
                    "description": "Reference to the next node; null if it is the last node."
                }
            },
            "required": [
                "value",
                "next"
            ],
            "additionalProperties": false
        }
    },
    "required": [
        "linked_list"
    ],
    "additionalProperties": false
}

Input: Dynamically generated UI
Output: {
    "name": "ui",
    "type": "object",
    "properties": {
        "type": {
            "type": "string",
            "description": "The type of the UI component",
            "enum": [
                "div",
                "button",
                "header",
                "section",
                "field",
                "form"
            ]
        },
        "label": {
            "type": "string",
            "description": "The label of the UI component, used for buttons or form fields"
        },
        "children": {
            "type": "array",
            "description": "Nested UI components",
            "items": {
                "$ref": "#"
            }
        },
        "attributes": {
            "type": "array",
            "description": "Arbitrary attributes for the UI component, suitable for any element",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "The name of the attribute, for example onClick or className"
                    },
                    "value": {
                        "type": "string",
                        "description": "The value of the attribute"
                    }
                },
                "required": [
                    "name",
                    "value"
                ],
                "additionalProperties": false
            }
        }
    },
    "required": [
        "type",
        "label",
        "children",
        "attributes"
    ],
    "additionalProperties": false
}`;

async function generateSchema(description) {
  const completion = await client.chat.completions.create({
    model: "gpt-5.6-terra",
    response_format: { type: "json_schema", json_schema: metaSchema },
    messages: [
      { role: "system", content: metaPrompt },
      { role: "user", content: "Description:\n" + description },
    ],
  });

  const content = completion.choices[0].message.content;
  if (!content) throw new Error("The model did not return a schema.");
  return JSON.parse(content);
}

console.log(
  JSON.stringify(await generateSchema("Describe a calendar event."), null, 2)
);