chore: import upstream snapshot with attribution

docs/en/documentation/getting-started/quickstart/python/__init__.py

@@ -0,0 +1,4 @@
+# This file makes the 'quickstart' directory a Python package.
+
+# You can include any package-level initialization logic here if needed.
+# For now, this file is empty.

docs/en/documentation/getting-started/quickstart/python/adk/quickstart.py

@@ -0,0 +1,57 @@
+# [START quickstart]
+import asyncio
+
+from google.adk import Agent
+from google.adk.apps import App
+from google.adk.runners import InMemoryRunner
+from google.adk.tools.toolbox_toolset import ToolboxToolset
+from google.genai.types import Content, Part
+
+prompt = """
+You're a helpful hotel assistant. You handle hotel searching, booking and
+cancellations. When the user searches for a hotel, mention it's name, id,
+location and price tier. Always mention hotel ids while performing any
+searches. This is very important for any operations. For any bookings or
+cancellations, please provide the appropriate confirmation. Be sure to
+update checkin or checkout dates if mentioned by the user.
+Don't ask for confirmations from the user.
+"""
+
+# TODO(developer): update the TOOLBOX_URL to your toolbox endpoint
+toolset = ToolboxToolset(
+    server_url="http://127.0.0.1:5000",
+)
+
+root_agent = Agent(
+    name='hotel_assistant',
+    model='gemini-2.5-flash',
+    instruction=prompt,
+    tools=[toolset],
+)
+
+app = App(root_agent=root_agent, name="my_agent")
+# [END quickstart]
+
+queries = [
+    "Find hotels in Basel with Basel in its name.",
+    "Can you book the Hilton Basel for me?",
+    "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",
+    "My check in dates would be from April 10, 2024 to April 19, 2024.",
+]
+
+async def main():
+    runner = InMemoryRunner(app=app)
+    session = await runner.session_service.create_session(
+        app_name=app.name, user_id="test_user"
+    )
+
+    for query in queries:
+        print(f"\nUser: {query}")
+        user_message = Content(parts=[Part.from_text(text=query)])
+
+        async for event in runner.run_async(user_id="test_user", session_id=session.id, new_message=user_message):
+            if event.is_final_response() and event.content and event.content.parts:
+                print(f"Agent: {event.content.parts[0].text}")
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/en/documentation/getting-started/quickstart/python/adk/requirements.txt

@@ -0,0 +1,2 @@
+google-adk[toolbox]==1.28.1
+pytest==9.0.3

docs/en/documentation/getting-started/quickstart/python/core/quickstart.py

@@ -0,0 +1,111 @@
+import asyncio
+import os
+
+from google import genai
+from google.genai.types import (
+    Content,
+    FunctionDeclaration,
+    GenerateContentConfig,
+    Part,
+    Tool,
+)
+
+from toolbox_core import ToolboxClient
+
+project = os.environ.get("GCP_PROJECT") or "project-id"
+
+prompt = """
+  You're a helpful hotel assistant. You handle hotel searching, booking and
+  cancellations. When the user searches for a hotel, mention it's name, id,
+  location and price tier. Always mention hotel id while performing any
+  searches. This is very important for any operations. For any bookings or
+  cancellations, please provide the appropriate confirmation. Be sure to
+  update checkin or checkout dates if mentioned by the user.
+  Don't ask for confirmations from the user.
+"""
+
+queries = [
+    "Find hotels in Basel with Basel in its name.",
+    "Please book the hotel Hilton Basel for me.",
+    "This is too expensive. Please cancel it.",
+    "Please book Hyatt Regency for me",
+    "My check in dates for my booking would be from April 10, 2024 to April 19, 2024.",
+]
+
+async def main():
+    async with ToolboxClient("http://127.0.0.1:5000") as toolbox_client:
+
+        # The toolbox_tools list contains Python callables (functions/methods) designed for LLM tool-use
+        # integration. While this example uses Google's genai client, these callables can be adapted for
+        # various function-calling or agent frameworks. For easier integration with supported frameworks
+        # (https://github.com/googleapis/mcp-toolbox-python-sdk/tree/main/packages), use the
+        # provided wrapper packages, which handle framework-specific boilerplate.
+        toolbox_tools = await toolbox_client.load_toolset("my-toolset")
+        tool_map = {tool.__name__: tool for tool in toolbox_tools}
+        genai_client = genai.Client(
+            vertexai=True, project=project, location="us-central1"
+        )
+
+        genai_tools = [
+            Tool(
+                function_declarations=[
+                    FunctionDeclaration.from_callable_with_api_option(callable=tool)
+                ]
+            )
+            for tool in toolbox_tools
+        ]
+        history = []
+        for query in queries:
+            print(f"\n[INPUT] User: {query}")
+            user_prompt_content = Content(
+                role="user",
+                parts=[Part.from_text(text=query)],
+            )
+            history.append(user_prompt_content)
+
+            response = genai_client.models.generate_content(
+                model="gemini-2.5-flash",
+                contents=history,
+                config=GenerateContentConfig(
+                    system_instruction=prompt,
+                    tools=genai_tools,
+                ),
+            )
+            history.append(response.candidates[0].content)
+            function_response_parts = []
+
+            if response.function_calls:
+                for function_call in response.function_calls:
+                    fn_name = function_call.name
+                    print(f"[TOOL CALL] Model requested tool '{fn_name}' with args: {function_call.args}")
+                    
+                    if fn_name in tool_map:
+                        function_result = await tool_map[fn_name](**function_call.args)
+                    else:
+                        raise ValueError(f"Function name {fn_name} not present.")
+
+                    function_response = {"result": function_result}
+                    function_response_part = Part.from_function_response(
+                        name=function_call.name,
+                        response=function_response,
+                    )
+                    function_response_parts.append(function_response_part)
+
+            if function_response_parts:
+                tool_response_content = Content(role="tool", parts=function_response_parts)
+                history.append(tool_response_content)
+
+                response2 = genai_client.models.generate_content(
+                    model="gemini-2.5-flash",
+                    contents=history,
+                    config=GenerateContentConfig(
+                        tools=genai_tools,
+                    ),
+                )
+                final_model_response_content = response2.candidates[0].content
+                history.append(final_model_response_content)
+                print(f"[OUTPUT] AI: {response2.text}")
+            else:
+                print(f"[OUTPUT] AI: {response.text}")
+
+asyncio.run(main())

docs/en/documentation/getting-started/quickstart/python/core/requirements.txt

@@ -0,0 +1,3 @@
+google-genai==2.3.0
+toolbox-core==1.0.0
+pytest==9.0.3

docs/en/documentation/getting-started/quickstart/python/langchain/quickstart.py

@@ -0,0 +1,47 @@
+import asyncio
+
+from langgraph.prebuilt import create_react_agent
+
+# TODO(developer): replace this with another import if needed
+from langchain_google_genai import ChatGoogleGenerativeAI
+# from langchain_anthropic import ChatAnthropic
+
+from langgraph.checkpoint.memory import MemorySaver
+from toolbox_langchain import ToolboxClient
+
+prompt = """
+  You're a helpful hotel assistant. You handle hotel searching, booking and
+  cancellations. When the user searches for a hotel, mention it's name, id,
+  location and price tier. Always mention hotel ids while performing any
+  searches. This is very important for any operations. For any bookings or
+  cancellations, please provide the appropriate confirmation. Be sure to
+  update checkin or checkout dates if mentioned by the user.
+  Don't ask for confirmations from the user.
+"""
+
+queries = [
+    "Find hotels in Basel with Basel in its name.",
+    "Can you book the Hilton Basel for me?",
+    "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",
+    "My check in dates would be from April 10, 2024 to April 19, 2024.",
+]
+
+async def main():
+    # TODO(developer): replace this with another model if needed
+    model = ChatGoogleGenerativeAI(model="gemini-2.5-flash")
+    # model = ChatAnthropic(model="claude-3-5-sonnet-20240620")
+
+    # Load the tools from the Toolbox server
+    async with ToolboxClient("http://127.0.0.1:5000") as client:
+        tools = await client.aload_toolset()
+
+        agent = create_react_agent(model, tools, checkpointer=MemorySaver())
+
+        config = {"configurable": {"thread_id": "thread-1"}}
+        for query in queries:
+            inputs = {"messages": [("user", prompt + query)]}
+            print(f"\n[INPUT] User: {query}")
+            response = agent.invoke(inputs, stream_mode="values", config=config)
+            print(f"[OUTPUT] AI: {response['messages'][-1].content}")
+
+asyncio.run(main())

docs/en/documentation/getting-started/quickstart/python/langchain/requirements.txt

@@ -0,0 +1,5 @@
+langchain==1.3.9
+langchain-google-genai==4.2.1
+langgraph==1.2.4
+toolbox-langchain==1.0.0
+pytest==9.0.3

docs/en/documentation/getting-started/quickstart/python/llamaindex/quickstart.py

@@ -0,0 +1,62 @@
+import asyncio
+import os
+
+from llama_index.core.agent.workflow import AgentWorkflow
+from llama_index.core.workflow import Context
+
+# TODO(developer): replace this with another import if needed
+from llama_index.llms.google_genai import GoogleGenAI
+# from llama_index.llms.anthropic import Anthropic
+
+from toolbox_llamaindex import ToolboxClient
+
+project = os.environ.get("GCP_PROJECT") or "project-id"
+
+prompt = """
+  You're a helpful hotel assistant. You handle hotel searching, booking and
+  cancellations. When the user searches for a hotel, mention it's name, id,
+  location and price tier. Always mention hotel ids while performing any
+  searches. This is very important for any operations. For any bookings or
+  cancellations, please provide the appropriate confirmation. Be sure to
+  update checkin or checkout dates if mentioned by the user.
+  Don't ask for confirmations from the user.
+"""
+
+queries = [
+    "Find hotels in Basel with Basel in its name.",
+    "Can you book the Hilton Basel for me?",
+    "Oh wait, this is too expensive. Please cancel it and book the Hyatt Regency instead.",
+    "My check in dates would be from April 10, 2024 to April 19, 2024.",
+]
+
+async def main():
+    # TODO(developer): replace this with another model if needed
+    llm = GoogleGenAI(
+        model="gemini-2.5-flash",
+        vertexai_config={"project": project, "location": "us-central1"},
+    )
+    # llm = GoogleGenAI(
+    #     api_key=os.getenv("GOOGLE_API_KEY"),
+    #     model="gemini-2.5-flash",
+    # )
+    # llm = Anthropic(
+    #   model="claude-3-7-sonnet-latest",
+    #   api_key=os.getenv("ANTHROPIC_API_KEY")
+    # )
+
+    # Load the tools from the Toolbox server
+    async with ToolboxClient("http://127.0.0.1:5000") as client:
+        tools = await client.aload_toolset()
+
+        agent = AgentWorkflow.from_tools_or_functions(
+            tools,
+            llm=llm,
+            system_prompt=prompt,
+        )
+        ctx = Context(agent)
+        for query in queries:
+            response = await agent.run(user_msg=query, ctx=ctx)
+            print(f"---- {query} ----")
+            print(str(response))
+
+asyncio.run(main())

docs/en/documentation/getting-started/quickstart/python/llamaindex/requirements.txt

@@ -0,0 +1,4 @@
+llama-index==0.14.18
+llama-index-llms-google-genai==0.8.7
+toolbox-llamaindex==0.6.0
+pytest==9.0.3

docs/en/documentation/getting-started/quickstart/python/quickstart_test.py

@@ -0,0 +1,58 @@
+# Copyright 2025 Google LLC
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#      http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import pytest
+from pathlib import Path
+import asyncio
+import sys
+import importlib.util
+
+ORCH_NAME = os.environ.get("ORCH_NAME")
+module_path = f"python.{ORCH_NAME}.quickstart"
+quickstart = importlib.import_module(module_path)
+
+
+GOLDEN_KEYWORDS = ["Hilton Basel", "Hyatt Regency", "book"]
+
+# --- Execution Tests ---
+class TestExecution:
+    """Test framework execution and output validation."""
+
+    _cached_output = None
+
+    @pytest.fixture(scope="function")
+    def script_output(self, capsys):
+        """Run the quickstart function and return its output."""
+        if TestExecution._cached_output is None:
+            asyncio.run(quickstart.main())
+            out, err = capsys.readouterr()
+            TestExecution._cached_output = (out, err)
+            
+        class Output:
+            def __init__(self, out, err):
+                self.out = out
+                self.err = err
+                
+        return Output(*TestExecution._cached_output)
+
+    def test_script_runs_without_errors(self, script_output):
+        """Test that the script runs and produces no stderr."""
+        assert script_output.err == "", f"Script produced stderr: {script_output.err}"
+
+    def test_keywords_in_output(self, script_output):
+        """Test that expected keywords are present in the script's output."""
+        output = script_output.out
+        missing_keywords = [kw for kw in GOLDEN_KEYWORDS if kw.lower() not in output.lower()]
+        assert not missing_keywords, f"Missing keywords in output: {missing_keywords}"