How do you build a prompt with Koog's prompt("id") { } DSL, and what is the id for?

## What the builder produces `prompt("some-id") { ... }` is a Kotlin type-safe builder. Inside the block you call message functions — `system(...)`, `user(...)`, `assistant(...)` — and the result is an immutable `Prompt` value: an ordered list of typed messages plus an id and parameters. The crucial point for anyone coming from string-templating libraries is that this is *structured*, not textual. You are not producing a big string with role markers in it; you are producing message objects that each client turns into the right wire representation for its vendor. That matters because vendors disagree about roles. Some carry system instructions as a separate top-level field, others as the first message; tool results are encoded differently again. Keeping messages typed until the last possible moment is what lets one `Prompt` be sent to more than one provider without rewriting it. ## The three message kinds `system(...)` carries instructions and persona: who the model is, what format to answer in, what it must never do. It is normally written once at the top. `user(...)` is the human turn — the actual request, plus whatever retrieved context or data you are injecting. `assistant(...)` is the one people misunderstand. It lets you place a *model* turn into the prompt yourself. Two uses dominate: few-shot examples, where you write alternating user/assistant pairs showing the exact answer shape you want, and conversation replay, where you rebuild a multi-turn dialogue from stored history so the model sees what it previously said. ## What the id is for The id is a label, not content. It never becomes text the model reads. Its value is operational: when a run appears in logs or in a trace, it is attributable to a named prompt, so you can ask "how is `ticket-triage` performing?" rather than trying to fingerprint prompt text. Give it a stable, human-meaningful name and keep it stable across edits to the body, because the whole point is to follow one prompt's behaviour over time. ## Parameters live beside the text, not inside it Sampling settings such as temperature are carried as `LLMParams` associated with the prompt rather than being smuggled into the message text. That keeps the knobs machine-readable — a trace can record the temperature actually used, and you can vary it per prompt without editing prose. ## Immutability and multi-turn flow A `Prompt` is a value. Adding a turn means producing a new prompt with an extra message, not mutating a shared object. For an agent this is exactly the right model: the growing conversation is data that the agent threads through its steps, and because it is plain data you can persist it, truncate it, summarise it, or inspect it in a test. It also means the executor stays stateless — nothing about the conversation lives inside the client or executor. ## Building is not sending Evaluating the builder block performs no I/O. There is no hidden network call, no key required, nothing suspends. You get an object. It reaches a model only when you pass it, together with an `LLModel`, to a `PromptExecutor`. This separation is why prompts are trivially unit-testable: construct one and assert on the messages it contains. ## Practical habits Keep the system message short and imperative; long systems drift and are hard to diff. Put variable data in the user turn, not the system turn, so the stable part stays stable. Use `assistant()` for few-shot rather than describing the desired output in prose — showing beats telling, and it keeps the system message small. Name ids by task, not by model, since the same prompt may run against different models. And do not encode secrets or per-user data in a system message you cache or reuse; the prompt is data that will end up in logs and traces if verbose capture is enabled. ## Common beginner mistakes Treating the id as something the model sees, so writing sentences into it. Building one giant `user()` string containing fake "System:" and "Assistant:" headers — that defeats the typed conversion and confuses tool-calling. Rebuilding the whole conversation from scratch on every turn while forgetting the earlier assistant replies, so the model loses the thread. And expecting the builder to call the model, then wondering why nothing happened.