fix: docs clarify temp namespace (#612)

This commit clarifies the behavior of the `temp:` namespace in the documentation.

The following changes were made:
- Updated `docs/sessions/state.md` to provide a more detailed explanation of the `temp:` namespace.
- Updated `docs/context/index.md` to improve the clarity of an example related to passing data between tools.
- Updated `docs/runtime/index.md` to add a note about the scope of `temp:` variables.
- Updated `docs/agents/multi-agents.md` and `docs/agents/workflow-agents/sequential-agents.md` to clarify how the `temp:` namespace is propagated to sub-agents.
- Updated `docs/tools/function-tools.md` to explain how to use the `temp:` namespace to pass data between tool calls.

fixes #160

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
Co-authored-by: Joe Fernandez <[email protected]>

Author: google-labs-jules[bot]

docs/agents/multi-agents.md

@@ -236,6 +236,9 @@ The most fundamental way for agents operating within the same invocation (and th
 * **Nature:** Asynchronous, passive communication. Ideal for pipelines orchestrated by `SequentialAgent` or passing data across `LoopAgent` iterations.
 * **See Also:** [State Management](../sessions/state.md)
 
+!!! note "Invocation Context and `temp:` State"
+    When a parent agent invokes a sub-agent, it passes the same `InvocationContext`. This means they share the same temporary (`temp:`) state, which is ideal for passing data that is only relevant for the current turn.
+
 === "Python"
 
     ```python

docs/agents/workflow-agents/sequential-agents.md

@@ -37,6 +37,9 @@ SequentialAgent(sub_agents=[CodeWriterAgent, CodeReviewerAgent, CodeRefactorerAg
 
 This ensures the code is written, *then* reviewed, and *finally* refactored, in a strict, dependable order. **The output from each sub-agent is passed to the next by storing them in state via [Output Key](../llm-agents.md#structuring-data-input_schema-output_schema-output_key)**.
 
+!!! note "Shared Invocation Context"
+    The `SequentialAgent` passes the same `InvocationContext` to each of its sub-agents. This means they all share the same session state, including the temporary (`temp:`) namespace, making it easy to pass data between steps within a single turn.
+
 ???+ "Code"
 
     === "Python"

docs/context/index.md

@@ -447,12 +447,13 @@ You'll frequently need to read information stored within the context.
         }
         ```
 
-### Managing Session State
+### Managing State
 
 State is crucial for memory and data flow. When you modify state using `CallbackContext` or `ToolContext`, the changes are automatically tracked and persisted by the framework.
 
 *   **How it Works:** Writing to `callback_context.state['my_key'] = my_value` or `tool_context.state['my_key'] = my_value` adds this change to the `EventActions.state_delta` associated with the current step's event. The `SessionService` then applies these deltas when persisting the event.
-*   **Passing Data Between Tools:**
+
+#### Passing Data Between Tools
 
     === "Python"
 

docs/runtime/index.md

@@ -260,7 +260,7 @@ Several components work together within the ADK Runtime to execute an agent invo
 6. ### `Invocation`
 
       * **Role:** A conceptual term representing everything that happens in response to a *single* user query, from the moment the `Runner` receives it until the agent logic finishes yielding events for that query.
-      * **Function:** An invocation might involve multiple agent runs (if using agent transfer or `AgentTool`), multiple LLM calls, tool executions, and callback executions, all tied together by a single `invocation_id` within the `InvocationContext`.
+      * **Function:** An invocation might involve multiple agent runs (if using agent transfer or `AgentTool`), multiple LLM calls, tool executions, and callback executions, all tied together by a single `invocation_id` within the `InvocationContext`. State variables prefixed with `temp:` are strictly scoped to a single invocation and discarded afterwards.
 
 These players interact continuously through the Event Loop to process a user's request.
 

docs/sessions/state.md

@@ -58,13 +58,17 @@ Prefixes on state keys define their scope and persistence behavior, especially w
     * **Use Cases:** Global settings (e.g., `'app:api_endpoint'`), shared templates.
     * **Example:** `session.state['app:global_discount_code'] = 'SAVE10'`
 
-* **`temp:` Prefix (Temporary Session State):**
+* **`temp:` Prefix (Temporary Invocation State):**
 
-    * **Scope:** Specific to the *current* session processing turn.
-    * **Persistence:** **Never Persistent.** Guaranteed to be discarded, even with persistent services.
-    * **Use Cases:** Intermediate results needed only immediately, data you explicitly don't want stored.
+    * **Scope:** Specific to the current **invocation** (the entire process from an agent receiving user input to generating the final output for that input).
+    * **Persistence:** **Not Persistent.** Discarded after the invocation completes and does not carry over to the next one.
+    * **Use Cases:** Storing intermediate calculations, flags, or data passed between tool calls within a single invocation.
+    * **When Not to Use:** For information that must persist across different invocations, such as user preferences, conversation history summaries, or accumulated data.
     * **Example:** `session.state['temp:raw_api_response'] = {...}`
 
+!!! note "Sub-Agents and Invocation Context"
+    When a parent agent calls a sub-agent (e.g., using `SequentialAgent` or `ParallelAgent`), it passes its `InvocationContext` to the sub-agent. This means the entire chain of agent calls shares the same invocation ID and, therefore, the same `temp:` state.
+
 **How the Agent Sees It:** Your agent code interacts with the *combined* state through the single `session.state` collection (dict/ Map). The `SessionService` handles fetching/merging state from the correct underlying storage based on prefixes.
 
 ### Accessing Session State in Agent Instructions

docs/tools/function-tools.md

@@ -104,6 +104,15 @@ Strive to make your return values as descriptive as possible. *For example,* ins
 
 The docstring of your function serves as the tool's **description** and is sent to the LLM. Therefore, a well-written and comprehensive docstring is crucial for the LLM to understand how to use the tool effectively. Clearly explain the purpose of the function, the meaning of its parameters, and the expected return values.
 
+### Passing Data Between Tools
+
+When an agent calls multiple tools in a sequence, you might need to pass data from one tool to another. The recommended way to do this is by using the `temp:` prefix in the session state.
+
+A tool can write data to a `temp:` variable, and a subsequent tool can read it. This data is only available for the current invocation and is discarded afterwards.
+
+!!! note "Shared Invocation Context"
+    All tool calls within a single agent turn share the same `InvocationContext`. This means they also share the same temporary (`temp:`) state, which is how data can be passed between them.
+
 ### Example
 
 ??? "Example"