chore: fixing metadata for adk doc

docs/en/sdks/python-sdk/adk/index.md

@@ -0,0 +1,279 @@
+---
+title: "Adk"
+type: docs
+weight: 8
+description: >
+  MCP Toolbox ADK SDK for integrating functionalities of MCP Toolbox into your apps.
+---
+
+## Overview
+
+The `toolbox-adk` package provides a Python interface to the MCP Toolbox service, enabling you to load and invoke tools from your own applications.
+
+## Installation
+
+```bash
+pip install toolbox-adk
+```
+
+## Usage
+
+The primary entry point is the `ToolboxToolset`, which loads tools from a remote Toolbox server and adapts them for use with ADK agents.
+
+{{< notice note>}}
+The `ToolboxToolset` in this package mirrors the `ToolboxToolset` in the [`adk-python`](https://github.com/google/adk-python) package. The `adk-python` version is a shim that delegates all functionality to this implementation.
+{{< /notice >}}
+
+```python
+from toolbox_adk import ToolboxToolset
+from google.adk.agents import Agent
+
+# Create the Toolset
+toolset = ToolboxToolset(
+    server_url="http://127.0.0.1:5000" 
+)
+
+# Use in your ADK Agent
+agent = Agent(tools=[toolset])
+```
+
+## Transport Protocols
+
+The SDK supports multiple transport protocols for communicating with the Toolbox server. By default, the client uses the latest supported version of the **Model Context Protocol (MCP)**.
+
+You can explicitly select a protocol using the `protocol` option during toolset initialization. This is useful if you need to use the native Toolbox HTTP protocol or pin the client to a specific legacy version of MCP.
+
+{{< notice note>}}
+* **Native Toolbox Transport**: This uses the service's native **REST over HTTP** API.
+* **MCP Transports**: These options use the **Model Context Protocol over HTTP**.
+{{< /notice >}}
+
+### Supported Protocols
+
+| Constant | Description |
+| :--- | :--- |
+| `Protocol.MCP` | **(Default)** Alias for the default MCP version (currently `2025-06-18`). |
+| `Protocol.TOOLBOX` | The native Toolbox HTTP protocol. |
+| `Protocol.MCP_v20251125` | MCP Protocol version 2025-11-25. |
+| `Protocol.MCP_v20250618` | MCP Protocol version 2025-06-18. |
+| `Protocol.MCP_v20250326` | MCP Protocol version 2025-03-26. |
+| `Protocol.MCP_v20241105` | MCP Protocol version 2024-11-05. |
+
+### Example
+
+If you wish to use the native Toolbox protocol:
+
+```python
+from toolbox_adk import ToolboxToolset
+from toolbox_core.protocol import Protocol
+
+toolset = ToolboxToolset(
+    server_url="http://127.0.0.1:5000",
+    protocol=Protocol.TOOLBOX
+)
+```
+
+If you want to pin the MCP Version 2025-03-26:
+
+```python
+from toolbox_adk import ToolboxToolset
+from toolbox_core.protocol import Protocol
+
+toolset = ToolboxToolset(
+    server_url="http://127.0.0.1:5000",
+    protocol=Protocol.MCP_v20250326
+)
+```
+
+{{< notice tip>}}
+By default, it uses **Toolbox Identity** (no authentication), which is suitable for local development.
+
+For production environments (Cloud Run, GKE) or accessing protected resources, see the [Authentication](#authentication) section for strategies like Workload Identity or OAuth2.
+{{< /notice >}}
+
+## Authentication
+
+The `ToolboxToolset` requires credentials to authenticate with the Toolbox server. You can configure these credentials using the `CredentialStrategy` factory methods.
+
+The strategies handle two main types of authentication:
+*   **Client-to-Server**: Securing the connection to the Toolbox server (e.g., Workload Identity, API keys).
+*   **User Identity**: Authenticating the end-user for specific tools (e.g., 3-legged OAuth).
+
+### 1. Workload Identity (ADC)
+*Recommended for Cloud Run, GKE, or local development with `gcloud auth login`.*
+
+Uses the agent's Application Default Credentials (ADC) to generate an OIDC token. This is the standard way for one service to authenticate to another on Google Cloud.
+
+```python
+from toolbox_adk import CredentialStrategy, ToolboxToolset
+
+# target_audience: The URL of your Toolbox server
+creds = CredentialStrategy.workload_identity(target_audience="https://my-toolbox-service.run.app")
+
+toolset = ToolboxToolset(
+    server_url="https://my-toolbox-service.run.app",
+    credentials=creds
+)
+```
+
+### 2. User Identity (OAuth2)
+*Recommended for tools that act on behalf of the user.*
+
+Configures the ADK-native interactive 3-legged OAuth flow to get consent and credentials from the end-user at runtime. This strategy is passed to the `ToolboxToolset` just like any other credential strategy.
+
+```python
+from toolbox_adk import CredentialStrategy, ToolboxToolset
+
+creds = CredentialStrategy.user_identity(
+    client_id="YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+    scopes=["https://www.googleapis.com/auth/cloud-platform"]
+)
+
+# The toolset will now initiate OAuth flows when required by tools
+toolset = ToolboxToolset(
+    server_url="...",
+    credentials=creds
+)
+```
+
+### 3. API Key
+*Use a static API key passed in a specific header (default: `X-API-Key`).*
+
+```python
+from toolbox_adk import CredentialStrategy
+
+# Default header: X-API-Key
+creds = CredentialStrategy.api_key(key="my-secret-key")
+
+# Custom header
+creds = CredentialStrategy.api_key(key="my-secret-key", header_name="X-My-Header")
+```
+
+### 4. HTTP Bearer Token
+*Manually supply a static bearer token.*
+
+```python
+from toolbox_adk import CredentialStrategy
+
+creds = CredentialStrategy.manual_token(token="your-static-bearer-token")
+```
+
+### 5. Manual Google Credentials
+*Use an existing `google.auth.credentials.Credentials` object.*
+
+```python
+from toolbox_adk import CredentialStrategy
+import google.auth
+
+creds_obj, _ = google.auth.default()
+creds = CredentialStrategy.manual_credentials(credentials=creds_obj)
+```
+
+### 6. Toolbox Identity (No Auth)
+*Use this if your Toolbox server does not require authentication (e.g., local development).*
+
+```python
+from toolbox_adk import CredentialStrategy
+
+creds = CredentialStrategy.toolbox_identity()
+```
+
+### 7. Native ADK Integration
+*Convert ADK-native `AuthConfig` or `AuthCredential` objects.*
+
+```python
+from toolbox_adk import CredentialStrategy
+
+# From AuthConfig
+creds = CredentialStrategy.from_adk_auth_config(auth_config)
+
+# From AuthCredential + AuthScheme
+creds = CredentialStrategy.from_adk_credentials(auth_credential, scheme)
+```
+
+### 8. Tool-Specific Authentication
+*Resolve authentication tokens dynamically for specific tools.*
+
+Some tools may define their own authentication requirements (e.g., Salesforce OAuth, GitHub PAT) via `authSources` in their schema. You can provide a mapping of getters to resolve these tokens at runtime.
+
+```python
+async def get_salesforce_token():
+    # Fetch token from secret manager or reliable source
+    return "sf-access-token"
+
+toolset = ToolboxToolset(
+    server_url="...",
+    auth_token_getters={
+        "salesforce-auth": get_salesforce_token,   # Async callable
+        "github-pat": lambda: "my-pat-token"       # Sync callable or static lambda
+    }
+)
+```
+
+## Advanced Configuration
+
+### Additional Headers
+
+You can inject custom headers into every request made to the Toolbox server. This is useful for passing tracing IDs, API keys, or other metadata.
+
+```python
+toolset = ToolboxToolset(
+    server_url="...",
+    additional_headers={
+        "X-Trace-ID": "12345",
+        "X-My-Header": lambda: get_dynamic_header_value() # Can be a callable
+    }
+)
+```
+
+### Global Parameter Binding
+
+Bind values to tool parameters globally across all loaded tools. These values will be **fixed** and **hidden** from the LLM.
+
+*   **Schema Hiding**: The bound parameters are removed from the tool schema sent to the model, simplifying the context window.
+*   **Auto-Injection**: The values are automatically injected into the tool arguments during execution.
+
+```python
+toolset = ToolboxToolset(
+    server_url="...",
+    bound_params={
+        # 'region' will be removed from the LLM schema and injected automatically
+        "region": "us-central1",
+        "api_key": lambda: get_api_key() # Can be a callable
+    }
+)
+```
+
+### Usage with Hooks
+
+You can attach `pre_hook` and `post_hook` functions to execute logic before and after every tool invocation.
+
+{{< notice note>}}
+ The `pre_hook` can modify `context.arguments` to dynamically alter the inputs passed to the tool.
+{{< /notice >}}
+
+```python
+from google.adk.tools.tool_context import ToolContext
+from typing import Any, Dict, Optional
+
+async def log_start(context: ToolContext, args: Dict[str, Any]):
+    print(f"Starting tool with args: {args}")
+    # context is the ADK ToolContext
+    # Example: Inject or modify arguments
+    # args["user_id"] = "123"
+
+async def log_end(context: ToolContext, args: Dict[str, Any], result: Optional[Any], error: Optional[Exception]):
+    print("Finished tool execution")
+    # Inspect result or error
+    if error:
+        print(f"Tool failed: {error}")
+    else:
+        print(f"Tool succeeded with result: {result}")
+
+toolset = ToolboxToolset(
+    server_url="...",
+    pre_hook=log_start,
+    post_hook=log_end
+)
+```

docs/en/sdks/python-sdk/llamaindex/index.md

@@ -1,386 +0,0 @@
----
-title: "LlamaIndex"
-type: docs
-weight: 8
-description: >
-  MCP Toolbox LlamaIndex SDK for integrating functionalities of MCP Toolbox into your LlamaIndex apps.
----
-
-## Overview
-
-The `toolbox-llamaindex` package provides a Python interface to the MCP Toolbox service, enabling you to load and invoke tools from your own applications.
-
-## Installation
-
-```bash
-pip install toolbox-llamaindex
-```
-
-## Quickstart
-
-Here's a minimal example to get you started using
-[LlamaIndex](https://docs.llamaindex.ai/en/stable/#getting-started):
-
-```py
-import asyncio
-
-from llama_index.llms.google_genai import GoogleGenAI
-from llama_index.core.agent.workflow import AgentWorkflow
-
-from toolbox_llamaindex import ToolboxClient
-
-async def run_agent():
-  async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
-    tools = toolbox.load_toolset()
-
-    vertex_model = GoogleGenAI(
-        model="gemini-2.0-flash-001",
-        vertexai_config={"project": "project-id", "location": "us-central1"},
-    )
-    agent = AgentWorkflow.from_tools_or_functions(
-        tools,
-        llm=vertex_model,
-        system_prompt="You are a helpful assistant.",
-    )
-    response = await agent.run(user_msg="Get some response from the agent.")
-    print(response)
-
-asyncio.run(run_agent())
-```
-
-{{< notice tip >}}
-For a complete, end-to-end example including setting up the service and using an SDK, see the full tutorial: [Toolbox Quickstart Tutorial](getting-started/local_quickstart)
-{{< /notice >}}
-
-## Usage
-
-Import and initialize the toolbox client.
-
-```py
-from toolbox_llamaindex import ToolboxClient
-
-# Replace with your Toolbox service's URL
-async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
-```
-
-## Loading Tools
-
-### Load a toolset
-
-A toolset is a collection of related tools. You can load all tools in a toolset
-or a specific one:
-
-```py
-# Load all tools
-tools = toolbox.load_toolset()
-
-# Load a specific toolset
-tools = toolbox.load_toolset("my-toolset")
-```
-
-### Load a single tool
-
-```py
-tool = toolbox.load_tool("my-tool")
-```
-
-Loading individual tools gives you finer-grained control over which tools are
-available to your LLM agent.
-
-## Use with LlamaIndex
-
-LlamaIndex's agents can dynamically choose and execute tools based on the user
-input. Include tools loaded from the Toolbox SDK in the agent's toolkit:
-
-```py
-from llama_index.llms.google_genai import GoogleGenAI
-from llama_index.core.agent.workflow import AgentWorkflow
-
-vertex_model = GoogleGenAI(
-    model="gemini-2.0-flash-001",
-    vertexai_config={"project": "project-id", "location": "us-central1"},
-)
-
-# Initialize agent with tools
-agent = AgentWorkflow.from_tools_or_functions(
-    tools,
-    llm=vertex_model,
-    system_prompt="You are a helpful assistant.",
-)
-
-# Query the agent
-response = await agent.run(user_msg="Get some response from the agent.")
-print(response)
-```
-
-### Maintain state
-
-To maintain state for the agent, add context as follows:
-
-```py
-from llama_index.core.agent.workflow import AgentWorkflow
-from llama_index.core.workflow import Context
-from llama_index.llms.google_genai import GoogleGenAI
-
-vertex_model = GoogleGenAI(
-    model="gemini-2.0-flash-001",
-    vertexai_config={"project": "project-id", "location": "us-central1"},
-)
-agent = AgentWorkflow.from_tools_or_functions(
-    tools,
-    llm=vertex_model,
-    system_prompt="You are a helpful assistant.",
-)
-
-# Save memory in agent context
-ctx = Context(agent)
-response = await agent.run(user_msg="Give me some response.", ctx=ctx)
-print(response)
-```
-
-## Manual usage
-
-Execute a tool manually using the `call` method:
-
-```py
-result = tools[0].call(name="Alice", age=30)
-```
-
-This is useful for testing tools or when you need precise control over tool
-execution outside of an agent framework.
-
-## Client to Server Authentication
-
-This section describes how to authenticate the ToolboxClient itself when
-connecting to a Toolbox server instance that requires authentication. This is
-crucial for securing your Toolbox server endpoint, especially when deployed on
-platforms like Cloud Run, GKE,  or any environment where unauthenticated access is restricted.
-
-This client-to-server authentication ensures that the Toolbox server can verify
-the identity of the client making the request before any tool is loaded or
-called. It is different from [Authenticating Tools](#authenticating-tools),
-which deals with providing credentials for specific tools within an already
-connected Toolbox session.
-
-### When is Client-to-Server Authentication Needed?
-
-You'll need this type of authentication if your Toolbox server is configured to
-deny unauthenticated requests. For example:
-
-- Your Toolbox server is deployed on Cloud Run and configured to "Require authentication."
-- Your server is behind an Identity-Aware Proxy (IAP) or a similar
-  authentication layer.
-- You have custom authentication middleware on your self-hosted Toolbox server.
-
-Without proper client authentication in these scenarios, attempts to connect or
-make calls (like `load_tool`) will likely fail with `Unauthorized` errors.
-
-### How it works
-
-The `ToolboxClient` allows you to specify functions (or coroutines for the async
-client) that dynamically generate HTTP headers for every request sent to the
-Toolbox server. The most common use case is to add an Authorization header with
-a bearer token (e.g., a Google ID token).
-
-These header-generating functions are called just before each request, ensuring
-that fresh credentials or header values can be used.
-
-### Configuration
-
-You can configure these dynamic headers as follows:
-
-```python
-from toolbox_llamaindex import ToolboxClient
-
-async with ToolboxClient(
-    "toolbox-url", 
-    client_headers={"header1": header1_getter, "header2": header2_getter},
-) as client:
-```
-
-### Authenticating with Google Cloud Servers
-
-For Toolbox servers hosted on Google Cloud (e.g., Cloud Run) and requiring
-`Google ID token` authentication, the helper module
-[auth_methods](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/packages/toolbox-core/src/toolbox_core/auth_methods.py) provides utility functions.
-
-### Step by Step Guide for Cloud Run
-
-1. **Configure Permissions**: [Grant](https://cloud.google.com/run/docs/securing/managing-access#service-add-principals) the `roles/run.invoker` IAM role on the Cloud
-   Run service to the principal. This could be your `user account email` or a
-   `service account`.
-2. **Configure Credentials**
-    - Local Development: Set up
-   [ADC](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment).
-    - Google Cloud Environments: When running within Google Cloud (e.g., Compute
-      Engine, GKE, another Cloud Run service, Cloud Functions), ADC is typically
-      configured automatically, using the environment's default service account.
-3. **Connect to the Toolbox Server**
-
-    ```python
-    from toolbox_llamaindex import ToolboxClient
-    from toolbox_core import auth_methods
-
-    auth_token_provider = auth_methods.aget_google_id_token(URL)
-    async with ToolboxClient(
-        URL,
-        client_headers={"Authorization": auth_token_provider},
-    ) as client:
-        tools = await client.aload_toolset()
-
-        # Now, you can use the client as usual.
-    ```
-
-## Authenticating Tools
-
-{{< notice note >}}
-Always use HTTPS to connect your application with the Toolbox service, especially when using tools with authentication configured. Using HTTP exposes your application to serious security risks.
-{{< /notice >}}
-
-Some tools require user authentication to access sensitive data.
-
-### Supported Authentication Mechanisms
-Toolbox currently supports authentication using the [OIDC
-protocol](https://openid.net/specs/openid-connect-core-1_0.html) with [ID
-tokens](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) (not
-access tokens) for [Google OAuth
-2.0](https://cloud.google.com/apigee/docs/api-platform/security/oauth/oauth-home).
-
-### Configure Tools
-
-Refer to [these
-instructions](https://googleapis.github.io/genai-toolbox/resources/tools/#authenticated-parameters) on
-configuring tools for authenticated parameters.
-
-### Configure SDK
-
-You need a method to retrieve an ID token from your authentication service:
-
-```py
-async def get_auth_token():
-    # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow)
-    # This example just returns a placeholder. Replace with your actual token retrieval.
-    return "YOUR_ID_TOKEN" # Placeholder
-```
-
-#### Add Authentication to a Tool
-
-```py
-async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
-    tools = toolbox.load_toolset()
-
-    auth_tool = tools[0].add_auth_token_getter("my_auth", get_auth_token) # Single token
-
-    multi_auth_tool = tools[0].add_auth_token_getters({"auth_1": get_auth_1}, {"auth_2": get_auth_2}) # Multiple tokens
-
-    # OR
-
-    auth_tools = [tool.add_auth_token_getter("my_auth", get_auth_token) for tool in tools]
-```
-
-#### Add Authentication While Loading
-
-```py
-auth_tool = toolbox.load_tool(auth_token_getters={"my_auth": get_auth_token})
-
-auth_tools = toolbox.load_toolset(auth_token_getters={"my_auth": get_auth_token})
-```
-
-{{< notice note >}}
-Adding auth tokens during loading only affect the tools loaded within that call.
-{{< /notice >}}
-
-### Complete Example
-
-```py
-import asyncio
-from toolbox_llamaindex import ToolboxClient
-
-async def get_auth_token():
-    # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow)
-    # This example just returns a placeholder. Replace with your actual token retrieval.
-    return "YOUR_ID_TOKEN" # Placeholder
-
-async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
-    tool = toolbox.load_tool("my-tool")
-
-    auth_tool = tool.add_auth_token_getter("my_auth", get_auth_token)
-    result = auth_tool.call(input="some input")
-    print(result)
-```
-
-## Binding Parameter Values
-
-Predetermine values for tool parameters using the SDK. These values won't be
-modified by the LLM. This is useful for:
-
-* **Protecting sensitive information:**  API keys, secrets, etc.
-* **Enforcing consistency:** Ensuring specific values for certain parameters.
-* **Pre-filling known data:**  Providing defaults or context.
-
-### Binding Parameters to a Tool
-
-```py
-async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
-    tools = toolbox.load_toolset()
-
-    bound_tool = tool[0].bind_param("param", "value") # Single param
-
-    multi_bound_tool = tools[0].bind_params({"param1": "value1", "param2": "value2"}) # Multiple params
-
-    # OR
-
-    bound_tools = [tool.bind_param("param", "value") for tool in tools]
-```
-
-### Binding Parameters While Loading
-
-```py
-bound_tool = toolbox.load_tool("my-tool", bound_params={"param": "value"})
-
-bound_tools = toolbox.load_toolset(bound_params={"param": "value"})
-```
-
-{{< notice note >}}
-Bound values during loading only affect the tools loaded in that call.
-{{< /notice >}}
-
-### Binding Dynamic Values
-
-Use a function to bind dynamic values:
-
-```py
-def get_dynamic_value():
-  # Logic to determine the value
-  return "dynamic_value"
-
-dynamic_bound_tool = tool.bind_param("param", get_dynamic_value)
-```
-
-{{< notice note >}}
-You don't need to modify tool configurations to bind parameter values.
-{{< /notice >}}
-
-## Asynchronous Usage
-
-For better performance through [cooperative
-multitasking](https://en.wikipedia.org/wiki/Cooperative_multitasking), you can
-use the asynchronous interfaces of the `ToolboxClient`.
-
-{{< notice note >}}
-Asynchronous interfaces like `aload_tool` and `aload_toolset` require an asynchronous environment. For guidance on running asynchronous Python programs, see [asyncio documentation](https://docs.python.org/3/library/asyncio-runner.html#running-an-asyncio-program).
-{{< /notice >}}
-
-```py
-import asyncio
-from toolbox_llamaindex import ToolboxClient
-
-async def main():
-    async with ToolboxClient("http://127.0.0.1:5000") as toolbox:
-        tool = await client.aload_tool("my-tool")
-        tools = await client.aload_toolset()
-        response = await tool.ainvoke()
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```