Merge branch 'main' into processing-docs

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

docs/en/samples/pre_post_processing/_index.md

@@ -0,0 +1,52 @@
+---
+title: "Pre and Post processing"
+type: docs
+weight: 1
+description: >
+  Pre and Post processing in GenAI applications.
+---
+
+Pre and post processing allow developers to intercept and modify interactions between the agent and its tools or the user. This capability is essential for building robust, secure, and compliant agents.
+
+## Types of Processing
+
+### Pre-processing
+
+Pre-processing occurs before a tool is executed or an agent processes a message. Key types include:
+
+- **Input Sanitization & Redaction**: Detecting and masking sensitive information (like PII) in user queries or tool arguments to prevent it from being logged or sent to unauthorized systems.
+- **Business Logic Validation**: Verifying that the proposed action complies with business rules (e.g., ensuring a requested hotel stay does not exceed 14 days, or checking if a user has sufficient permission).
+- **Security Guardrails**: Analyzing inputs for potential prompt injection attacks or malicious payloads.
+
+### Post-processing
+
+Post-processing occurs after a tool has executed or the model has generated a response. Key types include:
+
+- **Response Enrichment**: Injecting additional data into the tool output that wasn't part of the raw API response (e.g., calculating loyalty points earned based on the booking value).
+- **Output Formatting**: Transforming raw data (like JSON or XML) into a more human-readable or model-friendly format to improve the agent's understanding.
+- **Compliance Auditing**: Logging the final outcome of transactions, including the original request and the result, to a secure audit trail.
+
+## Processing Scopes
+
+Processing logic can be applied at different levels of the application:
+
+### Tool Level
+
+Wraps individual tool executions. This is best for logic specific to a single tool or a set of tools.
+
+- **Scope**: Intercepts the raw inputs (arguments) to a tool and its outputs.
+- **Use Cases**: Argument validation, output formatting, specific privacy rules for sensitive tools.
+
+### Model Level
+
+Intercepts individual calls to the Large Language Model (LLM).
+
+- **Scope**: Intercepts the list of messages (prompt) sent to the model and the generation (response) received.
+- **Use Cases**: Global PII redaction (across all tools/chat), prompt engineering/injection, token usage tracking, and hallucination detection.
+
+### Agent Level
+
+Wraps the high-level agent execution loop (e.g., a "turn" in the conversation).
+
+- **Scope**: Intercepts the initial user input and the final agent response, enveloping one or more model calls and tool executions.
+- **Use Cases**: User authentication, rate limiting, session management, and end-to-end audit logging.

docs/en/samples/pre_post_processing/golden.txt

@@ -0,0 +1,5 @@
+Final Client Response:
+AI:
+Booking Confirmed!
+Loyalty Points
+POLICY CHECK: Intercepting 'book-hotel'

docs/en/samples/pre_post_processing/python.md

@@ -0,0 +1,31 @@
+---
+title: "(Python) Pre and post processing"
+type: docs
+weight: 4
+description: >
+  How to add pre and post processing to your Python toolbox applications.
+---
+
+## Prerequisites
+
+This tutorial assumes that you have set up a basic toolbox application as described in the [local quickstart](../../getting-started/local_quickstart).
+
+This guide demonstrates how to implement these patterns in your Toolbox applications.
+
+## Python
+
+{{< tabpane persist=header >}}
+{{% tab header="ADK" text=true %}}
+Coming soon.
+{{% /tab %}}
+{{% tab header="Langchain" text=true %}}
+The following example demonstrates how to use `ToolboxClient` with LangChain's middleware to implement pre and post processing for tool calls.
+
+```py
+{{< include "python/langchain/agent.py" >}}
+```
+
+For more information, see the [LangChain Middleware documentation](https://docs.langchain.com/oss/python/langchain/middleware/custom#wrap-style-hooks).
+You can also add model-level (`wrap_model`) and agent-level (`before_agent`, `after_agent`) hooks to intercept messages at different stages of the execution loop. See the [LangChain Middleware documentation](https://docs.langchain.com/oss/python/langchain/middleware/custom#wrap-style-hooks) for details on these additional hook types.
+{{% /tab %}}
+{{< /tabpane >}}

docs/en/samples/pre_post_processing/python/__init__.py

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

docs/en/samples/pre_post_processing/python/agent_test.py

@@ -0,0 +1,58 @@
+# Copyright 2026 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 asyncio
+import importlib
+import os
+from pathlib import Path
+
+import pytest
+
+ORCH_NAME = os.environ.get("ORCH_NAME")
+module_path = f"python.{ORCH_NAME}.agent"
+agent = importlib.import_module(module_path)
+
+
+@pytest.fixture(scope="module")
+def golden_keywords():
+    """Loads expected keywords from the golden.txt file."""
+    golden_file_path = Path(__file__).resolve().parent.parent / "golden.txt"
+    if not golden_file_path.exists():
+        pytest.fail(f"Golden file not found: {golden_file_path}")
+    try:
+        with open(golden_file_path, "r") as f:
+            return [line.strip() for line in f.readlines() if line.strip()]
+    except Exception as e:
+        pytest.fail(f"Could not read golden.txt: {e}")
+
+
+# --- Execution Tests ---
+class TestExecution:
+    """Test framework execution and output validation."""
+
+    @pytest.fixture(scope="function")
+    def script_output(self, capsys):
+        """Run the agent function and return its output."""
+        asyncio.run(agent.main())
+        return capsys.readouterr()
+
+    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, golden_keywords):
+        """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 not in output]
+        assert not missing_keywords, f"Missing keywords in output: {missing_keywords}"

docs/en/samples/pre_post_processing/python/langchain/agent.py

@@ -0,0 +1,111 @@
+# Copyright 2026 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 asyncio
+from datetime import datetime
+
+from langchain.agents import create_agent
+from langchain.agents.middleware import wrap_tool_call
+from langchain_core.messages import ToolMessage
+from langchain_google_vertexai import ChatVertexAI
+from toolbox_langchain import ToolboxClient
+
+system_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.
+"""
+
+
+# Pre processing
+@wrap_tool_call
+async def enforce_business_rules(request, handler):
+    """
+    Business Logic Validation:
+    Enforces max stay duration (e.g., max 14 days).
+    """
+    tool_call = request.tool_call
+    name = tool_call["name"]
+    args = tool_call["args"]
+
+    print(f"POLICY CHECK: Intercepting '{name}'")
+
+    if name == "update-hotel":
+        if "checkin_date" in args and "checkout_date" in args:
+            try:
+                start = datetime.fromisoformat(args["checkin_date"])
+                end = datetime.fromisoformat(args["checkout_date"])
+                duration = (end - start).days
+
+                if duration > 14:
+                    print("BLOCKED: Stay too long")
+                    return ToolMessage(
+                        content="Error: Maximum stay duration is 14 days.",
+                        tool_call_id=tool_call["id"],
+                    )
+            except ValueError:
+                pass  # Ignore invalid date formats
+
+    return await handler(request)
+
+
+# Post processing
+@wrap_tool_call
+async def enrich_response(request, handler):
+    """
+    Post-Processing & Enrichment:
+    Adds loyalty points information to successful bookings.
+    Standardizes output format.
+    """
+    result = await handler(request)
+
+    if isinstance(result, ToolMessage):
+        content = str(result.content)
+        tool_name = request.tool_call["name"]
+
+        if tool_name == "book-hotel" and "Error" not in content:
+            loyalty_bonus = 500
+            result.content = f"Booking Confirmed! \n You earned {loyalty_bonus} Loyalty Points with this stay.\n\nSystem Details: {content}"
+
+    return result
+
+
+async def main():
+    async with ToolboxClient("http://127.0.0.1:5000") as client:
+        tools = await client.aload_toolset("my-toolset")
+        model = ChatVertexAI(model="gemini-2.5-flash")
+        agent = create_agent(
+            system_prompt=system_prompt,
+            model=model,
+            tools=tools,
+            middleware=[enforce_business_rules, enrich_response],
+        )
+
+        user_input = "Book hotel with id 3."
+        response = await agent.ainvoke(
+            {"messages": [{"role": "user", "content": user_input}]}
+        )
+
+        print("-" * 50)
+        print("Final Client Response:")
+        last_ai_msg = response["messages"][-1].content
+        print(f"AI: {last_ai_msg}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/en/samples/pre_post_processing/python/langchain/requirements.txt

@@ -0,0 +1,2 @@
+langchain==1.2.6
+toolbox-langchain==0.5.7