From 61af2ae445c58cc3d4701e506f9bb7a578b8e1d7 Mon Sep 17 00:00:00 2001 From: Zyan Date: Mon, 15 Jun 2026 17:35:19 -0600 Subject: [PATCH 1/4] UpdateContext.md --- docs/context/index.md | 42 +++++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/docs/context/index.md b/docs/context/index.md index 971c45dbb6..6393521cc5 100644 --- a/docs/context/index.md +++ b/docs/context/index.md @@ -108,9 +108,21 @@ 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: + +- **`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 on compatibility: The `CallbackContext` class is maintained as an alias for `Context` to ensure backward compatibility. While you may encounter `CallbackContext` in existing codebases, **we recommend using the `Context` class** for all new development to take advantage of the full, unified feature set. 1. **`InvocationContext`** * **Where Used:** Received as the `ctx` argument directly within an agent's core implementation methods (`_run_async_impl`, `_run_live_impl`). @@ -434,15 +446,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 +556,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 +609,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 +677,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 +773,7 @@ State is crucial for memory and data flow. When you modify state using `Callback } ``` -* **Updating User Preferences:** +* **Update user preferences:** === "Python" @@ -815,13 +827,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 +1094,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 +1156,7 @@ Use artifacts to handle files or large data blobs associated with the session. C } ``` -### Handling Tool Authentication +### Handle tool authentication
Supported in ADKPython v0.1.0TypeScript v0.2.0Java v0.2.0 From 841b350680fabfddf1ad44902ff3348356dc4ae1 Mon Sep 17 00:00:00 2001 From: Zyan Date: Wed, 17 Jun 2026 17:34:13 -0600 Subject: [PATCH 2/4] Update index.md --- docs/context/index.md | 61 +++++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 29 deletions(-) diff --git a/docs/context/index.md b/docs/context/index.md index 6393521cc5..ac71ca1262 100644 --- a/docs/context/index.md +++ b/docs/context/index.md @@ -122,13 +122,14 @@ Here are the primary context flavors you will encounter: - **`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 on compatibility: The `CallbackContext` class is maintained as an alias for `Context` to ensure backward compatibility. While you may encounter `CallbackContext` in existing codebases, **we recommend using the `Context` class** for all new development to take advantage of the full, unified feature set. +!!! 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, **we recommend using the `Context` class** for all new development to take advantage of the full, unified feature set. -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` +- **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" @@ -148,7 +149,7 @@ Here are the primary context flavors you will encounter: # ... agent logic using ctx ... yield # ... event ... ``` - + === "TypeScript" ```typescript @@ -201,10 +202,10 @@ Here are the primary context flavors you will encounter: } ``` -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" @@ -258,15 +259,17 @@ Here are the primary context flavors you will encounter: } ``` -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" @@ -339,15 +342,15 @@ Here are the primary context flavors you will encounter: } ``` -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" From 7a7fa0d6d04581bd68f7c3a834781f56e1ddf7d3 Mon Sep 17 00:00:00 2001 From: Zyan Date: Wed, 17 Jun 2026 17:41:55 -0600 Subject: [PATCH 3/4] Update index.md noticed that the hierarchy of bullet points was not correct --- docs/context/index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/context/index.md b/docs/context/index.md index ac71ca1262..7d300c1f03 100644 --- a/docs/context/index.md +++ b/docs/context/index.md @@ -264,9 +264,9 @@ Here are the primary context flavors you will encounter: - **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. + - **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. @@ -346,11 +346,11 @@ Here are the primary context flavors you will encounter: - **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. + - **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" From 570d3bc6061361c78ab3c11f77486fc90a840912 Mon Sep 17 00:00:00 2001 From: Zyan Date: Mon, 22 Jun 2026 15:56:22 -0600 Subject: [PATCH 4/4] Update context and callbackcontext.md --- docs/context/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/context/index.md b/docs/context/index.md index 7d300c1f03..9d29fd000c 100644 --- a/docs/context/index.md +++ b/docs/context/index.md @@ -123,7 +123,7 @@ Here are the primary context flavors you will encounter: - **`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, **we recommend using the `Context` class** for all new development to take advantage of the full, unified feature set. + **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`).