docs: Fix formatting/spelling errors in Docs

CONTRIBUTING.md

@@ -7,7 +7,7 @@ share your patches and improvements with the project.
 
 Before you contribute, please take a moment to review the following:
 
-### 1. Sign our Contributor License Agreement { #sign-our-contributor-license-agreement }
+### 1. Sign our Contributor License Agreement
 
 Contributions to this project must be accompanied by a
 [Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
@@ -21,7 +21,7 @@ was for a different project), you probably don't need to do it again.
 Visit <https://cla.developers.google.com/> to see your current agreements or to
 sign a new one.
 
-### 2. Review Community Guidelines { #review-community-guidelines }
+### 2. Review Community Guidelines
 
 We adhere to [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
 Please familiarize yourself with these guidelines to ensure a positive and

docs/a2a/intro.md

@@ -200,7 +200,7 @@ retrieve product information from a separate **Product Catalog Agent**.
 ### Before A2A
 
 Initially, your Customer Service Agent might not have a direct, standardized
-way to query the Product Catalog Ageny, especially if it's a separate service
+way to query the Product Catalog Agent, especially if it's a separate service
 or managed by a different team.
 
 ```text

docs/a2a/quickstart-consuming.md

@@ -25,7 +25,7 @@ The A2A Basic sample consists of:
 
   The ADK comes with a built-in CLI command, `adk api_server --a2a` to expose your agent using the A2A protocol.
 
-  In the a2a_basic example, you will first need to expose the `check_prime_agent` via an A2A server, so that the local root agent can use it.
+  In the `a2a_basic` example, you will first need to expose the `check_prime_agent` via an A2A server, so that the local root agent can use it.
 
 ### 1. Getting the Sample Code { #getting-the-sample-code }
 
@@ -35,7 +35,7 @@ First, make sure you have the necessary dependencies installed:
 pip install google-adk[a2a]
 ```
 
-You can clone and navigate to the [**a2a_basic** sample](https://github.com/google/adk-python/tree/main/contributing/samples/a2a_basic) here:
+You can clone and navigate to the [**`a2a_basic`** sample](https://github.com/google/adk-python/tree/main/contributing/samples/a2a_basic) here:
 
 ```bash
 git clone https://github.com/google/adk-python.git
@@ -96,15 +96,15 @@ INFO:     Application startup complete.
 INFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)
 ```
 
-### 3. Look out for the required agent card (`agent.json`) of the remote agent { #look-out-for-the-required-agent-card-agent-json-of-the-remote-agent }
+### 3. Look out for the required agent card (`agent-card.json`) of the remote agent { #look-out-for-the-required-agent-card-agent-json-of-the-remote-agent }
 
 A2A Protocol requires that each agent must have an agent card that describes what it does.
 
-If someone else has already built the remote A2A agent that you are looking to consume in your agent, then you should confirm that they have an agent card (`agent.json`).
+If someone else has already built the remote A2A agent that you are looking to consume in your agent, then you should confirm that they have an agent card (`agent-card.json`).
 
 In the sample, the `check_prime_agent` already has an agent card provided:
 
-```json title="a2a_basic/remote_a2a/check_prime_agent/agent.json"
+```json title="a2a_basic/remote_a2a/check_prime_agent/agent-card.json"
 
 {
   "capabilities": {},
@@ -143,6 +143,9 @@ The main agent uses the `RemoteA2aAgent()` function to consume the remote agent
 ```python title="a2a_basic/agent.py"
 <...code truncated...>
 
+from google.adk.agents.remote_a2a_agent import AGENT_CARD_WELL_KNOWN_PATH
+from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
+
 prime_agent = RemoteA2aAgent(
     name="prime_agent",
     description="Agent that handles checking if numbers are prime.",
@@ -157,6 +160,9 @@ prime_agent = RemoteA2aAgent(
 Then, you can simply use the `RemoteA2aAgent` in your agent. In this case, `prime_agent` is used as one of the sub-agents in the `root_agent` below:
 
 ```python title="a2a_basic/agent.py"
+from google.adk.agents.llm_agent import Agent
+from google.genai import types
+
 root_agent = Agent(
     model="gemini-2.0-flash",
     name="root_agent",

docs/a2a/quickstart-exposing.md

@@ -129,7 +129,7 @@ INFO:     Uvicorn running on http://localhost:8001 (Press CTRL+C to quit)
 
 You can check that your agent is up and running by visiting the agent card that was auto-generated earlier as part of your `to_a2a()` function in `a2a_root/remote_a2a/hello_world/agent.py`:
 
-[http://localhost:8001/.well-known/agent.json](http://localhost:8001/.well-known/agent.json)
+[http://localhost:8001/.well-known/agent-card.json](http://localhost:8001/.well-known/agent-card.json)
 
 You should see the contents of the agent card, which should look like:
 

docs/api-reference/index.md

@@ -2,7 +2,7 @@
 
 The Agent Development Kit (ADK) provides comprehensive API references for both Python and Java, allowing you to dive deep into all available classes, methods, and functionalities.
 
-<div class.="grid cards" markdown>
+<div class="grid cards" markdown>
 
 -   :fontawesome-brands-python:{ .lg .middle } **Python API Reference**
 

docs/context/index.md

@@ -453,10 +453,10 @@ State is crucial for memory and data flow. When you modify state using `Callback
 
 *   **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"
-    
+
         ```python
         # Pseudocode: Tool 1 - Fetches user ID
         from google.adk.tools import ToolContext
@@ -478,9 +478,9 @@ State is crucial for memory and data flow. When you modify state using `Callback
             # ... logic to fetch orders using user_id ...
             return {"orders": ["order123", "order456"]}
         ```
-    
+
     === "Java"
-    
+
         ```java
         // Pseudocode: Tool 1 - Fetches user ID
         import com.google.adk.tools.ToolContext;

docs/observability/logging.md

@@ -37,6 +37,8 @@ When running agents using the ADK's built-in web or API servers, you can easily
 
 This provides a convenient way to set the logging level without modifying your agent's source code.
 
+> **Note:** The command-line setting always takes precedence over the programmatic configuration (like `logging.basicConfig`) for ADK's loggers. It's recommended to use `INFO` or `WARNING` in production and enable `DEBUG` only when troubleshooting.
+
 **Example using `adk web`:**
 
 To start the web server with `DEBUG` level logging, run:
@@ -46,59 +48,48 @@ adk web --log_level DEBUG path/to/your/agents_dir
 ```
 
 The available log levels for the `--log_level` option are:
+
 - `DEBUG`
 - `INFO` (default)
 - `WARNING`
 - `ERROR`
 - `CRITICAL`
 
-> For the `DEBUG` level, you can also use `-v` or `--verbose` as a a shortcut for `--log_level DEBUG`. For example:
-> 
+> You can also use `-v` or `--verbose` as a a shortcut for `--log_level DEBUG`.
+>
 > ```bash
 > adk web -v path/to/your/agents_dir
 > ```
 
-This command-line setting overrides any programmatic configuration (like `logging.basicConfig`) you might have in your code for the ADK's loggers.
-
 ### Log Levels
 
-ADK uses standard log levels to categorize the importance of a message:
-
--   `DEBUG`: The most verbose level. Used for fine-grained diagnostic information, such as the full prompt sent to the LLM, detailed state changes, and internal logic flow. **Crucial for debugging.**
--   `INFO`: General information about the agent's lifecycle. This includes events like agent startup, session creation, and tool execution.
--   `WARNING`: Indicates a potential issue or the use of a deprecated feature. The agent can continue to function, but the issue may require attention.
--   `ERROR`: A serious error occurred that prevented the agent from performing an operation.
+ADK uses standard log levels to categorize messages. The configured level determines what information gets logged.
 
-> **Note:** It is recommended to use `INFO` or `WARNING` in production environments and only enable `DEBUG` when actively troubleshooting an issue, as `DEBUG` logs can be very verbose and may contain sensitive information.
+| Level | Description | Type of Information Logged  |
+| :--- | :--- | :--- |
+| **`DEBUG`** | **Crucial for debugging.** The most verbose level for fine-grained diagnostic information. | <ul><li>**Full LLM Prompts:** The complete request sent to the language model, including system instructions, history, and tools.</li><li>Detailed API responses from services.</li><li>Internal state transitions and variable values.</li></ul> |
+| **`INFO`** | General information about the agent's lifecycle. | <ul><li>Agent initialization and startup.</li><li>Session creation and deletion events.</li><li>Execution of a tool, including its name and arguments.</li></ul> |
+| **`WARNING`** | Indicates a potential issue or deprecated feature use. The agent continues to function, but attention may be required. | <ul><li>Use of deprecated methods or parameters.</li><li>Non-critical errors that the system recovered from.</li></ul> |
+| **`ERROR`** | A serious error that prevented an operation from completing. | <ul><li>Failed API calls to external services (e.g., LLM, Session Service).</li><li>Unhandled exceptions during agent execution.</li><li>Configuration errors.</li></ul> |
 
-## What is Logged
-
-Depending on the configured log level, you can expect to see the following information:
-
-| Level     | Type of Information Logged                                                                                             |
-| :-------- | :--------------------------------------------------------------------------------------------------------------------- |
-| **DEBUG** | - **Full LLM Prompts:** The complete request sent to the language model, including system instructions, history, and tools. |
-|           | - Detailed API responses from services.                                                                                |
-|           | - Internal state transitions and variable values.                                                                      |
-| **INFO**  | - Agent initialization and startup.                                                                                    |
-|           | - Session creation and deletion events.                                                                                |
-|           | - Execution of a tool, including the tool name and arguments.                                                          |
-| **WARNING**| - Use of deprecated methods or parameters.                                                                             |
-|           | - Non-critical errors that the system can recover from.                                                                 |
-| **ERROR** | - Failed API calls to external services (e.g., LLM, Session Service).                                                  |
-|           | - Unhandled exceptions during agent execution.                                                                         |
-|           | - Configuration errors.                                                                                                |
+> **Note:** It is recommended to use `INFO` or `WARNING` in production environments. Only enable `DEBUG` when actively troubleshooting an issue, as `DEBUG` logs can be very verbose and may contain sensitive information.
 
 ## Reading and Understanding the Logs
 
-The `format` string in the `basicConfig` example determines the structure of each log message. Let's break down a sample log entry:
+The `format` string in the `basicConfig` example determines the structure of each log message.  
 
-`2025-07-08 11:22:33,456 - DEBUG - google_adk.google.adk.models.google_llm - LLM Request: contents { ... }`
+Here’s a sample log entry:
+
+```text
+2025-07-08 11:22:33,456 - DEBUG - google_adk.google.adk.models.google_llm - LLM Request: contents { ... }
+```
 
--   `2025-07-08 11:22:33,456`: `%(asctime)s` - The timestamp of when the log was recorded.
--   `DEBUG`: `%(levelname)s` - The severity level of the message.
--   `google_adk.google.adk.models.google_llm`: `%(name)s` - The name of the logger. This hierarchical name tells you exactly which module in the ADK framework produced the log. In this case, it's the Google LLM model wrapper.
--   `Request to LLM: contents { ... }`: `%(message)s` - The actual log message.
+| Log Segment                     | Format Specifier | Meaning                                        |
+| ------------------------------- | ---------------- | ---------------------------------------------- |
+| `2025-07-08 11:22:33,456`       | `%(asctime)s`    | Timestamp                                      |
+| `DEBUG`                         | `%(levelname)s`  | Severity level                                 |
+| `google_adk.models.google_llm`  | `%(name)s`       | Logger name (the module that produced the log) |
+| `LLM Request: contents { ... }` | `%(message)s`    | The actual log message                         |
 
 By reading the logger name, you can immediately pinpoint the source of the log and understand its context within the agent's architecture.
 

docs/plugins/index.md

@@ -67,8 +67,7 @@ in the repository.
 Start by extending the `BasePlugin` class and add one or more `callback`
 methods, as shown in the following code example:
 
-```
-# count_plugin.py
+```py title="count_plugin.py"
 from google.adk.agents.base_agent import BaseAgent
 from google.adk.agents.callback_context import CallbackContext
 from google.adk.models.llm_request import LlmRequest
@@ -111,8 +110,7 @@ multiple Plugins with this parameter. The following code example shows how to
 register the `CountInvocationPlugin` plugin defined in the previous section with
 a simple ADK agent.
 
-
-```
+```py
 from google.adk.runners import InMemoryRunner
 from google.adk import Agent
 from google.adk.tools.tool_context import ToolContext
@@ -169,8 +167,8 @@ if __name__ == "__main__":
 Run the plugin as you typically would. The following shows how to run the
 command line:
 
-```
-> python3 -m path.to.main
+```sh
+python3 -m path.to.main
 ```
 
 Plugins are not supported by the
@@ -181,7 +179,7 @@ interface.
 The output of this previously described agent should look similar to the
 following:
 
-```
+```log
 [Plugin] Agent run count: 1
 [Plugin] LLM request count: 1
 ** Got event from hello_world
@@ -326,7 +324,7 @@ giving you a chance to inspect or modify the initial input.\
 
 The following code example shows the basic syntax of this callback:
 
-```
+```py
 async def on_user_message_callback(
     self,
     *,
@@ -351,7 +349,7 @@ logic begins.
 
 The following code example shows the basic syntax of this callback:
 
-```
+```py
 async def before_run_callback(
     self, *, invocation_context: InvocationContext
 ) -> Optional[types.Content]:
@@ -411,7 +409,7 @@ normally.****
 
 The following code example shows the basic syntax of this callback:
 
-```
+```py
 async def on_model_error_callback(
     self,
     *,
@@ -458,7 +456,7 @@ works as follows:
 
 The following code example shows the basic syntax of this callback:
 
-```
+```py
 async def on_tool_error_callback(
     self,
     *,
@@ -485,7 +483,7 @@ before it's streamed to the client.
 
 The following code example shows the basic syntax of this callback:
 
-```
+```py
 async def on_event_callback(
     self, *, invocation_context: InvocationContext, event: Event
 ) -> Optional[Event]:
@@ -507,8 +505,8 @@ cleanup and final reporting.
 
 The following code example shows the basic syntax of this callback:
 
-```
+```py
 async def after_run_callback(
     self, *, invocation_context: InvocationContext
 ) -> Optional[None]:
-```
+```

docs/safety/index.md

@@ -4,7 +4,7 @@
 
 As AI agents grow in capability, ensuring they operate safely, securely, and align with your brand values is paramount. Uncontrolled agents can pose risks, including executing misaligned or harmful actions, such as data exfiltration, and generating inappropriate content that can impact your brand’s reputation. **Sources of risk include vague instructions, model hallucination, jailbreaks and prompt injections from adversarial users, and indirect prompt injections via tool use.**
 
-[Google Cloud's Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/overview) provides a multi-layered approach to mitigate these risks, enabling you to build powerful *and* trustworthy agents. It offers several mechanisms to establish strict boundaries, ensuring agents only perform actions you've explicitly allowed:
+[Google Cloud Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/overview) provides a multi-layered approach to mitigate these risks, enabling you to build powerful *and* trustworthy agents. It offers several mechanisms to establish strict boundaries, ensuring agents only perform actions you've explicitly allowed:
 
 1. **Identity and Authorization**: Control who the agent **acts as** by defining agent and user auth.
 2. **Guardrails to screen inputs and outputs:** Control your model and tool calls precisely.