UpdateContext.md (#1844)

* UpdateContext.md

* Update index.md

* Update index.md

noticed that the hierarchy of bullet points was not correct

* Update context and callbackcontext.md

Author: zyantw

docs/context/index.md

@@ -108,15 +108,28 @@ The central piece holding all this information together for a single, complete u
     }
     ```
 
-## The Different types of Context
+## Types of context
 
-While `InvocationContext` acts as the comprehensive internal container, ADK provides specialized context objects tailored to specific situations. This ensures you have the right tools and permissions for the task at hand without needing to handle the full complexity of the internal context everywhere. Here are the different "flavors" you'll encounter:
+ADK uses the `Context` class as the central mechanism to manage an agent's environment, state, and resources. While `Context` serves as the foundational base for all agent interactions, it manifests in specialized "flavors" designed to provide the right balance of capabilities and permissions depending on where they are used in the agent's execution flow.
+If you use these specific context types, ADK ensures that your agent has access to necessary information, such as memory, session state, or credentials, exactly when and where you need them.
+Here are the primary context flavors you will encounter:
 
-1.  **`InvocationContext`**
-    *   **Where Used:** Received as the `ctx` argument directly within an agent's core implementation methods (`_run_async_impl`, `_run_live_impl`).
-    *   **Purpose:** Provides access to the *entire* state of the current invocation. This is the most comprehensive context object.
-    *   **Key Contents:** Direct access to `session` (including `state` and `events`), the current `agent` instance, `invocation_id`, initial `user_content`, references to configured services (`artifact_service`, `memory_service`, `session_service`), and fields related to live/streaming modes.
-    *   **Use Case:** Primarily used when the agent's core logic needs direct access to the overall session or services, though often state and artifact interactions are delegated to callbacks/tools which use their own contexts. Also used to control the invocation itself (e.g., setting `ctx.end_invocation = True`).
+- **`InvocationContext`**: Used during core agent runs (`_run_async_impl`, `_run_live_impl`) to provide a comprehensive view of the entire invocation, including service references and lifecycle management.
+  
+- **`ReadonlyContext`**: A lightweight, restricted view of fundamental contextual details used in scenarios where mutation is disallowed, such as within instruction providers.
+  
+- **`Context`**: Used in agent lifecycle and model callbacks. It provides a robust set of features for reading/writing session state, managing artifacts, and injecting data into the memory service.
+  
+- **`ToolContext`**: Tailored for tool execution and tool-related callbacks. In addition to the capabilities of Context, it includes specialized methods for authentication flows, memory searching, and artifact discovery.
+
+!!! note
+    **About compatibility**: In Python and TypeScript, `CallbackContext` and `ToolContext` have been replaced by the `Context` type. The `CallbackContext` class is maintained as an alias for `Context` to ensure backward compatibility. While you may encounter `CallbackContext` in existing codebases, **you should use the `Context` class** for all new development to take advantage of the full, unified feature set.
+
+### `InvocationContext`
+- **Where Used:** Received as the `ctx` argument directly within an agent's core implementation methods (`_run_async_impl`, `_run_live_impl`).
+- **Purpose:** Provides access to the entire state of the current invocation. This is the most comprehensive context object.
+- **Key Contents:** Direct access to `session` (including `state` and `events`), the current `agent` instance, `invocation_id`, initial `user_content`, references to configured services (`artifact_service`, `memory_service`, `session_service`), and fields related to live/streaming modes.
+- **Use Case:** Primarily used when the agent's core logic needs direct access to the overall session or services, though often state and artifact interactions are delegated to callbacks/tools which use their own contexts. Also used to control the invocation itself (e.g., setting `ctx.end_invocation = True`).
 
     === "Python"
 
@@ -136,7 +149,7 @@ While `InvocationContext` acts as the comprehensive internal container, ADK prov
                 # ... agent logic using ctx ...
                 yield # ... event ...
         ```
-
+        
     === "TypeScript"
 
         ```typescript
@@ -189,10 +202,10 @@ While `InvocationContext` acts as the comprehensive internal container, ADK prov
         }
         ```
 
-2.  **`ReadonlyContext`**
-    *   **Where Used:** Provided in scenarios where only read access to basic information is needed and mutation is disallowed (e.g., `InstructionProvider` functions). It's also the base class for other contexts.
-    *   **Purpose:** Offers a safe, read-only view of fundamental contextual details.
-    *   **Key Contents:** `invocation_id`, `agent_name`, and a read-only *view* of the current `state`.
+### `ReadonlyContext`
+- **Where Used:** Provided in scenarios where only read access to basic information is needed and mutation is disallowed (e.g., `InstructionProvider` functions). It's also the base class for other contexts.
+- **Purpose:** Offers a safe, read-only view of fundamental contextual details.
+- **Key Contents:** `invocation_id`, `agent_name`, and a read-only *view* of the current `state`.
 
     === "Python"
 
@@ -246,15 +259,17 @@ While `InvocationContext` acts as the comprehensive internal container, ADK prov
         }
         ```
 
-3.  **`CallbackContext`**
-    *   **Where Used:** Passed as `callback_context` to agent lifecycle callbacks (`before_agent_callback`, `after_agent_callback`) and model interaction callbacks (`before_model_callback`, `after_model_callback`).
-    *   **Purpose:** Facilitates inspecting and modifying state, interacting with artifacts, and accessing invocation details *specifically within callbacks*.
-    *   **Key Capabilities (Adds to `ReadonlyContext`):**
-        *   **Mutable `state` Property:** Allows reading *and writing* to session state. Changes made here (`callback_context.state['key'] = value`) are tracked and associated with the event generated by the framework after the callback.
-        *   **Artifact Methods:** `load_artifact(filename)` and `save_artifact(filename, part)` methods for interacting with the configured `artifact_service`.
-        *   Direct `user_content` access.
-        
-    *(Note: In TypeScript, `CallbackContext` and `ToolContext` are unified into a single `Context` type.)*
+### `CallbackContext` and `Context`
+
+- **Where Used:** Passed as `callback_context` to agent lifecycle callbacks (`before_agent_callback`, `after_agent_callback`) and model interaction callbacks (`before_model_callback`, `after_model_callback`).
+- **Purpose:** Facilitates inspecting and modifying state, interacting with artifacts, and accessing invocation details *specifically within callbacks*.
+- **Key Capabilities (Adds to `ReadonlyContext`):**
+    - **Mutable `state` Property:** Allows reading and writing to session state. Changes made here (`callback_context.state['key'] = value`) are tracked and associated with the event generated by the framework after the callback.
+    - **Artifact Methods:** `load_artifact(filename)` and `save_artifact(filename, part)` methods for interacting with the configured `artifact_service`.
+    - Direct `user_content` access.
+
+!!! note
+  In Python and TypeScript, `CallbackContext` and `ToolContext` have been replaced by the `Context` type.
 
     === "Python"
 
@@ -327,15 +342,15 @@ While `InvocationContext` acts as the comprehensive internal container, ADK prov
         }
         ```
 
-4.  **`ToolContext`**
-    *   **Where Used:** Passed as `tool_context` to the functions backing `FunctionTool`s and to tool execution callbacks (`before_tool_callback`, `after_tool_callback`).
-    *   **Purpose:** Provides everything `CallbackContext` does, plus specialized methods essential for tool execution, like handling authentication, searching memory, and listing artifacts.
-    *   **Key Capabilities (Adds to `CallbackContext`):**
-        *   **Authentication Methods:** `request_credential(auth_config)` to trigger an auth flow, and `get_auth_response(auth_config)` to retrieve credentials provided by the user/system.
-        *   **Artifact Listing:** `list_artifacts()` to discover available artifacts in the session.
-        *   **Memory Search:** `search_memory(query)` to query the configured `memory_service`.
-        *   **`function_call_id` Property:** Identifies the specific function call from the LLM that triggered this tool execution, crucial for linking authentication requests or responses back correctly.
-        *   **`actions` Property:** Direct access to the `EventActions` object for this step, allowing the tool to signal state changes, auth requests, etc.
+### `ToolContext`
+- **Where Used:** Passed as `tool_context` to the functions backing `FunctionTool`s and to tool execution callbacks (`before_tool_callback`, `after_tool_callback`).
+- **Purpose:** Provides everything `CallbackContext` does, plus specialized methods essential for tool execution, like handling authentication, searching memory, and listing artifacts.
+- **Key Capabilities (Adds to `CallbackContext`):**
+    - **Authentication Methods:** `request_credential(auth_config)` to trigger an auth flow, and `get_auth_response(auth_config)` to retrieve credentials provided by the user/system.
+    - **Artifact Listing:** `list_artifacts()` to discover available artifacts in the session.
+    - **Memory Search:** `search_memory(query)` to query the configured `memory_service`.
+    - **`function_call_id` Property:** Identifies the specific function call from the LLM that triggered this tool execution, crucial for linking authentication requests or responses back correctly.
+    - **`actions` Property:** Direct access to the `EventActions` object for this step, allowing the tool to signal state changes, auth requests, etc.
 
     === "Python"
 
@@ -434,15 +449,15 @@ While `InvocationContext` acts as the comprehensive internal container, ADK prov
 Understanding these different context objects and when to use them is key to effectively managing state, accessing services, and controlling the flow of your ADK application. The next section will detail common tasks you can perform using these contexts.
 
 
-## Common Tasks Using Context
+## Common tasks using context
 
 Now that you understand the different context objects, let's focus on how to use them for common tasks when building your agents and tools.
 
-### Accessing Information
+### Access information
 
 You'll frequently need to read information stored within the context.
 
-*   **Reading Session State:** Access data saved in previous steps or user/app-level settings. Use dictionary-like access on the `state` property.
+*   **Read session state:** Access data saved in previous steps or user/app-level settings. Use dictionary-like access on the `state` property.
 
     === "Python"
 
@@ -544,7 +559,7 @@ You'll frequently need to read information stored within the context.
         }
         ```
 
-*   **Getting Current Identifiers:** Useful for logging or custom logic based on the current operation.
+*   **Get current identifiers:** Useful for logging or custom logic based on the current operation.
 
     === "Python"
 
@@ -597,7 +612,7 @@ You'll frequently need to read information stored within the context.
         }
         ```
 
-*   **Accessing the Initial User Input:** Refer back to the message that started the current invocation.
+*   **Access the initial user input:** Refer back to the message that started the current invocation.
 
     === "Python"
 
@@ -665,13 +680,13 @@ You'll frequently need to read information stored within the context.
         }
         ```
 
-### Managing State
+### Manage 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**
+*  **Pass data between tools**
 
     === "Python"
 
@@ -761,7 +776,7 @@ State is crucial for memory and data flow. When you modify state using `Callback
         }
         ```
 
-*   **Updating User Preferences:**
+*   **Update user preferences:**
 
     === "Python"
 
@@ -815,13 +830,13 @@ State is crucial for memory and data flow. When you modify state using `Callback
         }
         ```
 
-*   **State Prefixes:** While basic state is session-specific, prefixes like `app:` and `user:` can be used with persistent `SessionService` implementations (like `DatabaseSessionService` or `VertexAiSessionService`) to indicate broader scope (app-wide or user-wide across sessions). `temp:` can denote data only relevant within the current invocation.
+*   **State prefixes:** While basic state is session-specific, prefixes like `app:` and `user:` can be used with persistent `SessionService` implementations (like `DatabaseSessionService` or `VertexAiSessionService`) to indicate broader scope (app-wide or user-wide across sessions). `temp:` can denote data only relevant within the current invocation.
 
-### Working with Artifacts
+### Work with artifacts
 
 Use artifacts to handle files or large data blobs associated with the session. Common use case: processing uploaded documents.
 
-*   **Document Summarizer Example Flow:**
+*   **Document summarizer example flow:**
 
     1.  **Ingest Reference (e.g., in a Setup Tool or Callback):** Save the *path or URI* of the document, not the entire content, as an artifact.
 
@@ -1082,7 +1097,7 @@ Use artifacts to handle files or large data blobs associated with the session. C
             }
             ```
 
-*   **Listing Artifacts:** Discover what files are available.
+*   **List Artifacts:** Discover what files are available.
 
     === "Python"
 
@@ -1144,7 +1159,7 @@ Use artifacts to handle files or large data blobs associated with the session. C
         }
         ```
 
-### Handling Tool Authentication
+### Handle tool authentication
 
 <div class="language-support-tag">
     <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v0.1.0</span><span class="lst-typescript">TypeScript v0.2.0</span><span class="lst-java">Java v0.2.0</span>