Improve Prompts documentation based on feedback (#1302)

## Motivation and Context

These changes were made based on comments in this PR #1287

## Breaking Changes

---

#### Type of the changes
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Tests improvement
- [ ] Refactoring

#### Checklist
- [ ] The pull request has a description of the proposed change
- [ ] I read the [Contributing
Guidelines](https://github.com/JetBrains/koog/blob/main/CONTRIBUTING.md)
before opening the pull request
- [ ] The pull request uses **`develop`** as the base branch
- [ ] Tests for the changes have been added
- [ ] All new and existing tests passed

##### Additional steps for pull requests adding a new feature
- [ ] An issue describing the proposed change exists
- [ ] The pull request includes a link to the issue
- [ ] The change was discussed and approved in the issue
- [ ] Docs have been added / updated

Author: innateteniuk

docs/docs/basic-agents.md

@@ -32,15 +32,15 @@ To use the `AIAgent` functionality, include all necessary dependencies in your b
 
 ```
 dependencies {
-    implementation("ai.koog:koog-agents:$koog_version")
+    implementation("ai.koog:koog-agents:VERSION")
 }
 ```
 
 For all available installation methods, see [Install Koog](getting-started.md#install-koog).
 
 ### 2. Create an agent 
 
-To create an agent, create an instance of the `AIAgent` class and provide the `executor` and `llmModel` parameters:
+To create an agent, create an instance of the `AIAgent` class and provide the `promptExecutor` and `llmModel` parameters:
 
 <!--- INCLUDE
 import ai.koog.agents.core.agent.AIAgent

docs/docs/llm-parameters.md

@@ -31,7 +31,7 @@ val prompt = prompt(
 ```
 <!--- KNIT example-llm-parameters-01.kt -->
 
-For more information about prompt creation, see [Prompts](prompts/structured-prompts.md).
+For more information about prompt creation, see [Prompts](prompts/prompt-creation/index.md).
 
 - When creating a subgraph:
 

docs/docs/llm-providers.md

@@ -53,7 +53,7 @@ Koog lets you work with LLM providers on two levels:
     It can switch between providers
     and optionally fall back to a configured provider and LLM using the corresponding client.
     You can either create your own executor or use a pre-defined prompt executor for a specific provider.
-    For details, see [Prompt executors](prompts/llm-clients.md).
+    For details, see [Prompt executors](prompts/prompt-executors.md).
 
 
 Using a prompt executor offers a higher‑level layer over one or more LLMClients. 

docs/docs/prompts/handling-failures.md

@@ -41,22 +41,15 @@ val response = resilientClient.execute(prompt, OpenAIModels.Chat.GPT4o)
 
 ### Configuring retry behavior
 
-Koog provides several predefined retry configurations:
-
-| Configuration              | Max attempts | Initial delay | Max delay | Use case                |
-|----------------------------|--------------|---------------|-----------|-------------------------|
-| `RetryConfig.DISABLED`     | 1 (no retry) | -             | -         | Development and testing |
-| `RetryConfig.CONSERVATIVE` | 3            | 2s            | 30s       | Normal production use   |
-| `RetryConfig.AGGRESSIVE`   | 5            | 500ms         | 20s       | Critical operations     |
-| `RetryConfig.PRODUCTION`   | 3            | 1s            | 20s       | Recommended default     |
-
-You can use them directly or create custom configurations:
+By default, `RetryingLLMClient` configures an LLM client with the maximum of 3 retry attempts, a 1-second initial delay,
+and a 30-second maximum delay.
+You can specify a different retry configuration using a `RetryConfig` passed to `RetryingLLMClient`.
+For example:
 
 <!--- INCLUDE
 import ai.koog.prompt.executor.clients.openai.OpenAILLMClient
 import ai.koog.prompt.executor.clients.retry.RetryConfig
 import ai.koog.prompt.executor.clients.retry.RetryingLLMClient
-import kotlin.time.Duration.Companion.seconds
 
 val apiKey = System.getenv("OPENAI_API_KEY")
 val client = OpenAILLMClient(apiKey)
@@ -67,7 +60,30 @@ val conservativeClient = RetryingLLMClient(
     delegate = client,
     config = RetryConfig.CONSERVATIVE
 )
+```
+<!--- KNIT example-handling-failures-02.kt -->
+
+Koog provides several predefined retry configurations:
+
+| Configuration              | Max attempts | Initial delay | Max delay | Use case                                                                                                 |
+|----------------------------|--------------|---------------|-----------|----------------------------------------------------------------------------------------------------------|
+| `RetryConfig.DISABLED`     | 1 (no retry) | -             | -         | Development, testing, and debugging.                                                                     |
+| `RetryConfig.CONSERVATIVE` | 3            | 2s            | 30s       | Background or scheduled tasks where reliability is more important than speed.                            |
+| `RetryConfig.AGGRESSIVE`   | 5            | 500ms         | 20s       | Critical operations where fast recovery from transient errors is more important than reducing API calls. |
+| `RetryConfig.PRODUCTION`   | 3            | 1s            | 20s       | General production use.                                                                                  |
 
+You can use them directly or create custom configurations:
+
+<!--- INCLUDE
+import ai.koog.prompt.executor.clients.openai.OpenAILLMClient
+import ai.koog.prompt.executor.clients.retry.RetryConfig
+import ai.koog.prompt.executor.clients.retry.RetryingLLMClient
+import kotlin.time.Duration.Companion.seconds
+
+val apiKey = System.getenv("OPENAI_API_KEY")
+val client = OpenAILLMClient(apiKey)
+-->
+```kotlin
 // Or create a custom configuration
 val customClient = RetryingLLMClient(
     delegate = client,
@@ -80,7 +96,7 @@ val customClient = RetryingLLMClient(
     )
 )
 ```
-<!--- KNIT example-handling-failures-02.kt -->
+<!--- KNIT example-handling-failures-03.kt -->
 
 ### Retry error patterns
 
@@ -102,7 +118,7 @@ You can use the following pattern types and combine any number of them:
 * `RetryablePattern.Regex`: Matches a regular expression in the error message.
 * `RetryablePattern.Custom`: Matches a custom logic using a lambda function.
 
-If any pattern returns `true`, the error is considered retryable, and the LLM client can retry the request.
+If any pattern returns `true`, the error is considered retryable, and the LLM client retries the request.
 
 #### Default patterns
 
@@ -150,7 +166,7 @@ val config = RetryConfig(
     )
 )
 ```
-<!--- KNIT example-handling-failures-03.kt -->
+<!--- KNIT example-handling-failures-04.kt -->
 
 You can also append custom patterns to the default `RetryConfig.DEFAULT_PATTERNS`:
 
@@ -165,7 +181,7 @@ val config = RetryConfig(
     )
 )
 ```
-<!--- KNIT example-handling-failures-04.kt -->
+<!--- KNIT example-handling-failures-05.kt -->
 
 
 ### Streaming with retry
@@ -199,11 +215,12 @@ val config = RetryConfig(
 val client = RetryingLLMClient(baseClient, config)
 val stream = client.executeStreaming(prompt, OpenAIModels.Chat.GPT4o)
 ```
-<!--- KNIT example-handling-failures-05.kt -->
+<!--- KNIT example-handling-failures-06.kt -->
 
 !!!note
     Streaming retries only apply to connection failures that occur before the first token is received.
-    After streaming has started, any errors will be passed through.
+    Once streaming has started, the retry logic is disabled.
+    If an error occurs during streaming, the operation is terminated.
 
 ### Retry with prompt executors
 
@@ -250,13 +267,23 @@ val multiExecutor = MultiLLMPromptExecutor(
     ),
 )
 ```
-<!--- KNIT example-handling-failures-06.kt -->
+<!--- KNIT example-handling-failures-07.kt -->
 
 ## Timeout configuration
 
 All LLM clients support timeout configuration to prevent hanging requests.
 You can specify timeout values for network connections when creating the client using
-the [`ConnectionTimeoutConfig`](https://api.koog.ai/prompt/prompt-executor/prompt-executor-clients/ai.koog.prompt.executor.clients/-connection-timeout-config/index.html) class:
+the [`ConnectionTimeoutConfig`](https://api.koog.ai/prompt/prompt-executor/prompt-executor-clients/ai.koog.prompt.executor.clients/-connection-timeout-config/index.html) class.
+
+`ConnectionTimeoutConfig` has the following properties:
+
+| Property               | Default Value        | Description                                                   |
+|------------------------|----------------------|---------------------------------------------------------------|
+| `connectTimeoutMillis` | 60 seconds (60,000)  | Maximum time to establish a connection to the server.         |
+| `requestTimeoutMillis` | 15 minutes (900,000) | Maximum time for the entire request to complete.              |
+| `socketTimeoutMillis`  | 15 minutes (900,000) | Maximum time to wait for data over an established connection. |
+
+You can customize these values for your specific needs. For example:
 
 <!--- INCLUDE
 import ai.koog.prompt.executor.clients.ConnectionTimeoutConfig
@@ -277,7 +304,7 @@ val client = OpenAILLMClient(
     )
 )
 ```
-<!--- KNIT example-handling-failures-07.kt -->
+<!--- KNIT example-handling-failures-08.kt -->
 
 !!! tip
     For long-running or streaming calls, set higher values for `requestTimeoutMillis` and `socketTimeoutMillis`.
@@ -342,4 +369,4 @@ fun main() {
     }
 }
 ```
-<!--- KNIT example-handling-failures-08.kt -->
+<!--- KNIT example-handling-failures-09.kt -->

docs/docs/prompts/index.md

@@ -6,42 +6,38 @@ This section describes how to create and run prompts with Koog.
 
 ## Creating prompts
 
-In Koog, all prompts are represented as [**Prompt**](https://api.koog.ai/prompt/prompt-model/ai.koog.prompt.dsl/-prompt/index.html)
-objects. A Prompt object contains:
+In Koog, prompts are instances of the [**Prompt**](https://api.koog.ai/prompt/prompt-model/ai.koog.prompt.dsl/-prompt/index.html) 
+data class with the following properties:
 
-- **ID**: A unique identifier for the prompt.
-- **Messages**: A list of messages that represent the conversation with the LLM.
-- **Parameters**: Optional [LLM configuration parameters](https://api.koog.ai/prompt/prompt-model/ai.koog.prompt.params/-l-l-m-params/index.html)
-  (such as temperature, tool choice, and others).
+- `id`: A unique identifier for the prompt.
+- `messages`: A list of messages that represent the conversation with the LLM.
+- `params`: Optional [LLM configuration parameters](prompt-creation/index.md#prompt-parameters) (such as temperature, tool choice, and others).
 
-All Prompt objects are structured prompts defined using the Kotlin DSL, which lets you specify the structure of the conversation.
+Although you can instantiate the `Prompt` class directly,
+the recommended way to create prompts is by using the [Kotlin DSL](prompt-creation/index.md), 
+which provides a structured way to define the conversation.
+
+<!--- INCLUDE
+import ai.koog.prompt.dsl.prompt
+-->
+```kotlin
+val myPrompt = prompt("hello-koog") {
+    system("You are a helpful assistant.")
+    user("What is Koog?")
+}
+```
+<!--- KNIT example-prompts-01.kt -->
 
 !!! note
-    AI agents let you provide a simple text prompt instead of creating a Prompt object.
+    AI agents can take a simple text prompt as input.
     They automatically convert the text prompt to the Prompt object and send it to the LLM for execution.
-    This is useful for a [basic agent](basic-agents.md) that only needs to run a single request.
-
-
-<div class="grid cards" markdown>
-
--   :material-code-braces:{ .lg .middle } [**Structured prompts**](structured-prompts.md)
-
-    ---
-
-    Create type-safe structured prompts for complex multi-turn conversations.
-
--   :material-multimedia:{ .lg .middle } [**Multimodal inputs**](multimodal-inputs.md)
-
-    ---
-
-    Send images, audio, video, and documents along with text in your structured prompts.
-
-</div>
+    This is useful for a [basic agent](../basic-agents.md)
+    that only needs to run a single request and does not require complex conversation logic.
 
 ## Running prompts
 
 Koog provides two levels of abstraction for running prompts against LLMs: LLM clients and prompt executors.
-They only accept Prompt objects and can be used for direct prompt execution, without an AI agent.
+Both accept Prompt objects and can be used for direct prompt execution, without an AI agent.
 The execution flow is the same for both clients and executors:
 
 ```mermaid
@@ -76,28 +72,45 @@ flowchart TB
 
 </div>
 
-If you want to run a simple text prompt, wrap it in a Prompt object using the Kotlin DSL,
-or use an AI agent, which automatically does this for you.
-Here is the execution flow for the agent:
+## Optimizing performance and handling failures
 
-```mermaid
-flowchart TB
-    A([Your application])
-    B{{Configured AI agent}}
-    C["Text prompt"]
-    D["Prompt object"]
-    E{{Prompt executor}}
-    F[LLM provider]
+Koog allows you to optimize performance and handle failures when running prompts.
 
-    A -->|"run() with text"| B
-    B -->|"takes"| C
-    C -->|"converted to"| D
-    D -->|"sent via"| E
-    E -->|"calls"| F
-    F -->|"responds to"| E
-    E -->|"result to"| B
-    B -->|"result to"| A
-```
+<div class="grid cards" markdown>
+
+-   :material-cached:{ .lg .middle } [**LLM response caching**](llm-response-caching.md)
+
+    ---
+
+    Cache LLM responses to optimize performance and reduce costs for repeated requests.
+
+-   :material-shield-check:{ .lg .middle } [**Handling failures**](handling-failures.md)
+
+    ---
+
+    Use built-in retries, timeouts, and other error handling mechanisms in your application.
+
+</div>
+
+## Prompts in AI agents
+
+In Koog, AI agents maintain and manage prompts during their lifecycle.
+While LLM clients or executors are used to run prompts, agents handle the flow of prompt updates, ensuring the 
+conversation history remains relevant and consistent.
+
+The prompt lifecycle in an agent usually includes several stages:
+
+1. Initial prompt setup.
+2. Automatic prompt updates.
+3. Context window management.
+4. Manual prompt management.
+
+### Initial prompt setup
+
+When you [initialize an agent](../getting-started/#create-and-run-an-agent), you define 
+a [system message](prompt-creation/index.md#system-message) that sets the agent's behavior.
+Then, when you call the agent's `run()` method, you typically provide an initial [user message](prompt-creation/index.md#user-messages)
+as input. Together, these messages form the agent's initial prompt. For example: 
 
 <!--- INCLUDE
 import ai.koog.agents.core.agent.AIAgent
@@ -116,30 +129,56 @@ fun main() = runBlocking {
 // Create an agent
 val agent = AIAgent(
     promptExecutor = simpleOpenAIExecutor(apiKey),
+    systemPrompt = "You are a helpful assistant.",
     llmModel = OpenAIModels.Chat.GPT4o
 )
 
 // Run the agent
 val result = agent.run("What is Koog?")
 ```
-<!--- KNIT example-prompts-01.kt -->
+<!--- KNIT example-prompts-02.kt -->
 
-## Optimizing performance and handling failures
+In the example, the agent automatically converts the text prompt to the Prompt object and sends it to the prompt executor:
 
-Koog allows you to optimize performance and handle failures when running prompts.
+```mermaid
+flowchart TB
+    A([Your application])
+    B{{Configured AI agent}}
+    C["Text prompt"]
+    D["Prompt object"]
+    E{{Prompt executor}}
+    F[LLM provider]
 
-<div class="grid cards" markdown>
+    A -->|"run() with text"| B
+    B -->|"takes"| C
+    C -->|"converted to"| D
+    D -->|"sent via"| E
+    E -->|"calls"| F
+    F -->|"responds to"| E
+    E -->|"result to"| B
+    B -->|"result to"| A
+```
 
--   :material-cached:{ .lg .middle } [**LLM response caching**](llm-response-caching.md)
+For more [advanced configurations](../complex-workflow-agents.md#4-configure-the-agent), you can also use 
+[AIAgentConfig](https://api.koog.ai/agents/agents-core/ai.koog.agents.core.agent.config/-a-i-agent-config/index.html)
+to define the agent's initial prompt.
 
-    ---
+### Automatic prompt updates
 
-    Cache LLM responses to optimize performance and reduce costs for repeated requests.
+As the agent runs its strategy, [predefined nodes](../nodes-and-components.md) automatically update the prompt.
+For example:
 
--   :material-shield-check:{ .lg .middle } [**Handling failures**](handling-failures.md)
+- [`nodeLLMRequest`](../nodes-and-components/#nodellmrequest): Appends a user message to the prompt and captures the LLM response.
+- [`nodeLLMSendToolResult`](../nodes-and-components/#nodellmsendtoolresult): Appends tool execution results to the conversation.
+- [`nodeAppendPrompt`](../nodes-and-components/#nodeappendprompt): Inserts specific messages into the prompt at any point in the workflow.
 
-    ---
+### Context window management
 
-    Use built-in retries, timeouts, and other error handling mechanisms in your application.
+To avoid exceeding the LLM context window in long-running interactions, agents can use the
+[history compression](../history-compression.md) feature.
 
-</div>
+### Manual prompt management
+
+For complex workflows, you can manage the prompt manually using [LLM sessions](../sessions.md).
+In an agent strategy or custom node, you can use `llm.writeSession` to access and change the `Prompt` object.
+This lets you add, remove, or reorder messages as needed.