diff --git a/docs/agents/custom-agents.md b/docs/agents/custom-agents.md
index 90cf3f2835..db5a875c4e 100644
--- a/docs/agents/custom-agents.md
+++ b/docs/agents/custom-agents.md
@@ -22,6 +22,10 @@ While the standard [Workflow Agents](workflow-agents/index.md) (`SequentialAgent
* **Dynamic Agent Selection:** Choosing which sub-agent(s) to run next based on dynamic evaluation of the situation or input.
* **Unique Workflow Patterns:** Implementing orchestration logic that doesn't fit the standard sequential, parallel, or loop structures.
+
+
+
+
## Implementing Custom Logic:
The heart of any custom agent is the `_run_async_impl` method. This is where you define its unique behavior.
diff --git a/docs/assets/adk-components.png b/docs/assets/adk-components.png
index 0e050f4da0..0290dc1146 100644
Binary files a/docs/assets/adk-components.png and b/docs/assets/adk-components.png differ
diff --git a/docs/assets/adk-lifecycle.png b/docs/assets/adk-lifecycle.png
new file mode 100644
index 0000000000..cbfb7f2d8d
Binary files /dev/null and b/docs/assets/adk-lifecycle.png differ
diff --git a/docs/assets/agent-tool-call.png b/docs/assets/agent-tool-call.png
index b977739ee3..880a278a83 100644
Binary files a/docs/assets/agent-tool-call.png and b/docs/assets/agent-tool-call.png differ
diff --git a/docs/assets/callback_flow.png b/docs/assets/callback_flow.png
new file mode 100644
index 0000000000..f3b691f412
Binary files /dev/null and b/docs/assets/callback_flow.png differ
diff --git a/docs/assets/custom-agent-flow.png b/docs/assets/custom-agent-flow.png
new file mode 100644
index 0000000000..f9abfe0009
Binary files /dev/null and b/docs/assets/custom-agent-flow.png differ
diff --git a/docs/assets/deploy-agent.png b/docs/assets/deploy-agent.png
index a44c1c3c41..ba438199f5 100644
Binary files a/docs/assets/deploy-agent.png and b/docs/assets/deploy-agent.png differ
diff --git a/docs/assets/evaluate_agent.png b/docs/assets/evaluate_agent.png
new file mode 100644
index 0000000000..237cc0be21
Binary files /dev/null and b/docs/assets/evaluate_agent.png differ
diff --git a/docs/assets/invocation-flow.png b/docs/assets/invocation-flow.png
index 771f5f8f2b..68022c3733 100644
Binary files a/docs/assets/invocation-flow.png and b/docs/assets/invocation-flow.png differ
diff --git a/docs/assets/quickstart-flow-tool.png b/docs/assets/quickstart-flow-tool.png
new file mode 100644
index 0000000000..29063a8af5
Binary files /dev/null and b/docs/assets/quickstart-flow-tool.png differ
diff --git a/docs/assets/quickstart-streaming-tool.png b/docs/assets/quickstart-streaming-tool.png
new file mode 100644
index 0000000000..b2bb5555b2
Binary files /dev/null and b/docs/assets/quickstart-streaming-tool.png differ
diff --git a/docs/callbacks/index.md b/docs/callbacks/index.md
index 26f0b94c4b..7426bee59e 100644
--- a/docs/callbacks/index.md
+++ b/docs/callbacks/index.md
@@ -10,6 +10,8 @@ Callbacks are a cornerstone feature of ADK, providing a powerful mechanism to ho
* Before sending a request to, or after receiving a response from, the Large Language Model (LLM).
* Before executing a tool (like a Python function or another agent) or after it finishes.
+
+
**Why use them?** Callbacks unlock significant flexibility and enable advanced agent capabilities:
* **Observe & Debug:** Log detailed information at critical steps for monitoring and troubleshooting.
diff --git a/docs/get-started/about.md b/docs/get-started/about.md
index c5e41f1e76..c60052af0b 100644
--- a/docs/get-started/about.md
+++ b/docs/get-started/about.md
@@ -96,6 +96,8 @@ agentic applications:
services, allowing agents to recall user information across multiple
sessions.
+
+
## Get Started
* Ready to build your first agent? [Try the quickstart](./quickstart.md)
diff --git a/docs/get-started/quickstart-streaming.md b/docs/get-started/quickstart-streaming.md
index 990344a4dd..1bf8a2f674 100644
--- a/docs/get-started/quickstart-streaming.md
+++ b/docs/get-started/quickstart-streaming.md
@@ -62,6 +62,8 @@ root_agent = Agent(
Notice how easily you integrated [grounding with Google Search](https://ai.google.dev/gemini-api/docs/grounding?lang=python#configure-search) capabilities. The `Agent` class and the `google_search` tool handle the complex interactions with the LLM and grounding with the search API, allowing you to focus on the agent's *purpose* and *behavior*.
+
+
Copy-paste the following code block to `__init__.py` and `main.py` files.
```py title="__init__.py"
diff --git a/docs/get-started/quickstart.md b/docs/get-started/quickstart.md
index 27a3db7858..2fea90811f 100644
--- a/docs/get-started/quickstart.md
+++ b/docs/get-started/quickstart.md
@@ -66,6 +66,10 @@ For `.env` below, just copy and paste the following code for now, as more instru
--8<-- "examples/python/snippets/get-started/multi_tool_agent/.env"
```
+
+
+
+
## 3. Setup the model {#setup-the-model}
Your agent's ability to understand user requests and generate responses is
diff --git a/docs/guides/evaluate-agents.md b/docs/guides/evaluate-agents.md
index 22525bcb08..2079f7bf0d 100644
--- a/docs/guides/evaluate-agents.md
+++ b/docs/guides/evaluate-agents.md
@@ -6,6 +6,8 @@ Due to the probabilistic nature of models, deterministic "pass/fail" assertions
This may seem like a lot of extra work to set up, but the investment of automating evaluations pays off quickly. If you intend to progress beyond prototype, this is a highly recommended best practice.
+
+
## Preparing for Agent Evaluations
Before automating agent evaluations, define clear objectives and success criteria:
diff --git a/docs/runtime/index.md b/docs/runtime/index.md
index 56f6312b2f..eb0280ff93 100644
--- a/docs/runtime/index.md
+++ b/docs/runtime/index.md
@@ -10,7 +10,7 @@ Think of the Runtime as the **"engine"** of your agentic application. You define
At its heart, the ADK Runtime operates on an **Event Loop**. This loop facilitates a back-and-forth communication between the `Runner` component and your defined "Execution Logic" (which includes your Agents, the LLM calls they make, Callbacks, and Tools).
-
+
In simple terms:
@@ -33,8 +33,8 @@ The `Runner` acts as the central coordinator for a single user invocation. Its r
1. **Initiation:** Receives the end user's query (`new_message`) and typically appends it to the session history via the `SessionService`.
2. **Kick-off:** Starts the event generation process by calling the main agent's execution method (e.g., `agent_to_run.run_async(...)`).
3. **Receive & Process:** Waits for the agent logic to `yield` an `Event`. Upon receiving an event, the Runner **promptly processes** it. This involves:
- * Using configured `Services` (`SessionService`, `ArtifactService`, `MemoryService`) to commit changes indicated in `event.actions` (like `state_delta`, `artifact_delta`).
- * Performing other internal bookkeeping.
+ * Using configured `Services` (`SessionService`, `ArtifactService`, `MemoryService`) to commit changes indicated in `event.actions` (like `state_delta`, `artifact_delta`).
+ * Performing other internal bookkeeping.
4. **Yield Upstream:** Forwards the processed event onwards (e.g., to the calling application or UI for rendering).
5. **Iterate:** Signals the agent logic that processing is complete for the yielded event, allowing it to resume and generate the *next* event.
@@ -112,41 +112,41 @@ Several components work together within the ADK Runtime to execute an agent invo
1. ### `Runner`
- * **Role:** The main entry point and orchestrator for a single user query (`run_async`).
- * **Function:** Manages the overall Event Loop, receives events yielded by the Execution Logic, coordinates with Services to process and commit event actions (state/artifact changes), and forwards processed events upstream (e.g., to the UI). It essentially drives the conversation turn by turn based on yielded events. (Defined in `google.adk.runners.runner.py`).
+ * **Role:** The main entry point and orchestrator for a single user query (`run_async`).
+ * **Function:** Manages the overall Event Loop, receives events yielded by the Execution Logic, coordinates with Services to process and commit event actions (state/artifact changes), and forwards processed events upstream (e.g., to the UI). It essentially drives the conversation turn by turn based on yielded events. (Defined in `google.adk.runners.runner.py`).
2. ### Execution Logic Components
- * **Role:** The parts containing your custom code and the core agent capabilities.
- * **Components:**
- * `Agent` (`BaseAgent`, `LlmAgent`, etc.): Your primary logic units that process information and decide on actions. They implement the `_run_async_impl` method which yields events.
- * `Tools` (`BaseTool`, `FunctionTool`, `AgentTool`, etc.): External functions or capabilities used by agents (often `LlmAgent`) to interact with the outside world or perform specific tasks. They execute and return results, which are then wrapped in events.
- * `Callbacks` (Functions): User-defined functions attached to agents (e.g., `before_agent_callback`, `after_model_callback`) that hook into specific points in the execution flow, potentially modifying behavior or state, whose effects are captured in events.
- * **Function:** Perform the actual thinking, calculation, or external interaction. They communicate their results or needs by **yielding `Event` objects** and pausing until the Runner processes them.
+ * **Role:** The parts containing your custom code and the core agent capabilities.
+ * **Components:**
+ * `Agent` (`BaseAgent`, `LlmAgent`, etc.): Your primary logic units that process information and decide on actions. They implement the `_run_async_impl` method which yields events.
+ * `Tools` (`BaseTool`, `FunctionTool`, `AgentTool`, etc.): External functions or capabilities used by agents (often `LlmAgent`) to interact with the outside world or perform specific tasks. They execute and return results, which are then wrapped in events.
+ * `Callbacks` (Functions): User-defined functions attached to agents (e.g., `before_agent_callback`, `after_model_callback`) that hook into specific points in the execution flow, potentially modifying behavior or state, whose effects are captured in events.
+ * **Function:** Perform the actual thinking, calculation, or external interaction. They communicate their results or needs by **yielding `Event` objects** and pausing until the Runner processes them.
3. ### `Event`
- * **Role:** The message passed back and forth between the `Runner` and the Execution Logic.
- * **Function:** Represents an atomic occurrence (user input, agent text, tool call/result, state change request, control signal). It carries both the content of the occurrence and the intended side effects (`actions` like `state_delta`). (Defined in `google.adk.events.event.py`).
+ * **Role:** The message passed back and forth between the `Runner` and the Execution Logic.
+ * **Function:** Represents an atomic occurrence (user input, agent text, tool call/result, state change request, control signal). It carries both the content of the occurrence and the intended side effects (`actions` like `state_delta`). (Defined in `google.adk.events.event.py`).
4. ### `Services`
- * **Role:** Backend components responsible for managing persistent or shared resources. Used primarily by the `Runner` during event processing.
- * **Components:**
- * `SessionService` (`BaseSessionService`, `InMemorySessionService`, etc.): Manages `Session` objects, including saving/loading them, applying `state_delta` to the session state, and appending events to the `event history`.
- * `ArtifactService` (`BaseArtifactService`, `InMemoryArtifactService`, `GcsArtifactService`, etc.): Manages the storage and retrieval of binary artifact data. Although `save_artifact` is called via context during execution logic, the `artifact_delta` in the event confirms the action for the Runner/SessionService.
- * `MemoryService` (`BaseMemoryService`, etc.): (Optional) Manages long-term semantic memory across sessions for a user.
- * **Function:** Provide the persistence layer. The `Runner` interacts with them to ensure changes signaled by `event.actions` are reliably stored *before* the Execution Logic resumes.
+ * **Role:** Backend components responsible for managing persistent or shared resources. Used primarily by the `Runner` during event processing.
+ * **Components:**
+ * `SessionService` (`BaseSessionService`, `InMemorySessionService`, etc.): Manages `Session` objects, including saving/loading them, applying `state_delta` to the session state, and appending events to the `event history`.
+ * `ArtifactService` (`BaseArtifactService`, `InMemoryArtifactService`, `GcsArtifactService`, etc.): Manages the storage and retrieval of binary artifact data. Although `save_artifact` is called via context during execution logic, the `artifact_delta` in the event confirms the action for the Runner/SessionService.
+ * `MemoryService` (`BaseMemoryService`, etc.): (Optional) Manages long-term semantic memory across sessions for a user.
+ * **Function:** Provide the persistence layer. The `Runner` interacts with them to ensure changes signaled by `event.actions` are reliably stored *before* the Execution Logic resumes.
5. ### `Session`
- * **Role:** A data container holding the state and history for *one specific conversation* between a user and the application.
- * **Function:** Stores the current `state` dictionary, the list of all past `events` (`event history`), and references to associated artifacts. It's the primary record of the interaction, managed by the `SessionService`. (Defined in `google.adk.sessions.session.py`).
+ * **Role:** A data container holding the state and history for *one specific conversation* between a user and the application.
+ * **Function:** Stores the current `state` dictionary, the list of all past `events` (`event history`), and references to associated artifacts. It's the primary record of the interaction, managed by the `SessionService`. (Defined in `google.adk.sessions.session.py`).
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`.
+ * **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`.
These players interact continuously through the Event Loop to process a user's request.
@@ -154,7 +154,7 @@ These players interact continuously through the Event Loop to process a user's r
Let's trace a simplified flow for a typical user query that involves an LLM agent calling a tool:
-
+
### Step-by-Step Breakdown