System prompts

Where a prompt comes from

A model-driven node will name its system prompt in its settings:

# nodes/summarize.node.ael
node summarize(input: Request) -> Summary {
    config {
        prompt: file("prompts/summarize.md");
        model: binding("primary_model");
    }
    return write_summary(input);
}

A prompt will come from one of four sources:

• A file(…) path will be relative to the project root, wherever the source file that names it sits: in src/nodes/summarize.node.ael, file("prompts/summarize.md") names prompts/summarize.md at the root of the project, beside main.ael.
• A file source will have to stay inside the project; a path that leads outside it will be an error.
• An environment source will read only the variable you name. AEL will never read the environment as a whole.
• Keeping prompts in a prompts/ folder will be a convention, not a rule.

file(…) will be the file source. How the inline, environment and configuration sources are written will be confirmed when the syntax is final.

Ordered fallback

You will be able to give one source, or several in the order you want them tried. At the start of a run, AEL will take the first source that has a usable prompt:

• If a file is missing, a variable is unset, a source is unavailable or its text is only white space, AEL will move on to the next source.
• A source that is present but wrong will stop the run with an error, and never fall back: text that is not valid UTF-8, a template error, an unknown template variable or a path outside the project.
• Every fallback will be recorded in your logs with the kind of source and the reason, never with the prompt's text or a secret value.

The order will always be the one you wrote. No hidden precedence will decide which prompt a run uses.

Running on input alone

If no source provides a system prompt, the node will send the model its input alone, with no system prompt: it will run "input-only". That will be the default, and it is useful when the input already says everything the model needs.

A missing or invalid model binding will be a separate error: running input-only will never remove the need for a model. A deterministic node will have no prompt and no model binding, so none of this will apply to it.

Instructions and input will stay apart

• The system prompt will go to the model as instructions, and the run's input as ordinary input, each in its own channel.
• Input, tool results, retrieved documents and memory will stay data. None of them will ever be promoted to instructions.
• A prompt template will be able to use only the variables you declare, filled from typed values. An undeclared variable will be an error.

Building the model's input

An input builder, a helper function you write, will turn a node's typed input into what the model receives. The result may be text, or other parts such as images, audio or files when the model accepts them; text will not be required. Typed inputs and outputs describes input builders.

One prompt per run

• Each run will resolve its prompt once, before any model call, and keep it to the end.
• Changing a prompt file, an environment variable or a configuration value will affect the runs that start afterwards, never a run already under way.
• Each run will record which prompt it used, together with its model binding and configuration, so you can tell which version produced a result. The record will identify the prompt without storing its text in your logs.
• A caller will be able to replace a run's prompt only if your deployment allows it and the caller is authorized.

Evaluations and prompt releases describes how to test a prompt change and promote it.

What a prompt cannot do

A system prompt, or any other text, will not be able to grant a permission, raise a limit or change who the caller is. A rule that must always hold, such as a limit on a payment amount, belongs in your code as well, as a typed check at the tool that makes the payment. See Effects and capabilities.

Keep secrets out of prompt files: they will be packaged with your build. A value that must stay secret belongs in a configuration secret reference.