Merge branch 'main' into adk-js-processing

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

.github/workflows/link_checker.yaml

@@ -97,10 +97,9 @@ jobs:
           gh api \
             --method DELETE \
             -H "Accept: application/vnd.github+json" \
-            /repos/${{ github.repository }}/issues/comments/${STEPS_FIND_COMMENT_OUTPUTS_COMMENT_ID}
+            /repos/${{ github.repository }}/issues/comments/${{ steps.find-comment.outputs.comment-id }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          STEPS_FIND_COMMENT_OUTPUTS_COMMENT_ID: ${{ steps.find-comment.outputs.comment-id }}
 
       - name: Prepare Report 
         if: env.HAS_CHANGES == 'true' && steps.lychee-check.outcome == 'failure'

docs/en/samples/pre_post_processing/golden.txt

@@ -0,0 +1,4 @@
+Final Client Response:
+AI:
+Loyalty Points
+POLICY CHECK: Intercepting 'update-hotel'

docs/en/samples/pre_post_processing/js.md

@@ -16,10 +16,18 @@ This guide demonstrates how to implement these patterns in your Toolbox applicat
 
 {{< tabpane persist=header >}}
 {{% tab header="ADK" text=true %}}
-Coming soon.
+The following example demonstrates how to use the `beforeToolCallback` and `afterToolCallback` hooks in the ADK `LlmAgent` to implement pre and post processing logic.
+
+```js
+{{< include "js/adk/agent.js" >}}
+```
+
+You can also add model-level (`beforeModelCallback`, `afterModelCallback`) and agent-level (`beforeAgentCallback`, `afterAgentCallback`) hooks to intercept messages at different stages of the execution loop. 
+
+For more information, see the [ADK Callbacks documentation](https://google.github.io/adk-docs/callbacks/types-of-callbacks/).
 {{% /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.
+The following example demonstrates how to use `ToolboxClient` with LangChain's middleware to implement pre and post processing for tool calls.
 
 ```js
 {{< include "js/langchain/agent.js" >}}

docs/en/samples/pre_post_processing/js/adk/agent.js

@@ -0,0 +1,103 @@
+import { InMemoryRunner, LlmAgent, LogLevel } from '@google/adk';
+import { ToolboxClient } from '@toolbox-sdk/adk';
+
+process.env.GOOGLE_GENAI_API_KEY = process.env.GOOGLE_API_KEY || 'your-api-key'; // Replace it with your API key
+
+const systemPrompt = `
+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
+function enforeBusinessRules({tool, args}) {
+  const name = tool.name;
+  console.log(`POLICY CHECK: Intercepting '${name}'`);
+
+  if (name === "update-hotel" && args.checkin_date && args.checkout_date) {
+    try {
+      const start = new Date(args.checkin_date);
+      const end = new Date(args.checkout_date);
+      const duration = (end - start) / (1000 * 60 * 60 * 24); // days
+
+      if (duration > 14) {
+        console.log("BLOCKED: Stay too long");
+        return "Error: Maximum stay duration is 14 days.";
+      }
+    } catch (e) {
+      // Ignore invalid dates
+    }
+  }
+  return undefined;
+}
+
+// Post-Processing
+function enrichResponse({tool, response}) {
+  const name = tool.name;
+  console.log(`ENRICHING RESPONSE: Intercepting '${name}'`);
+  if (name === "book-hotel") {
+    let content = response;
+    if (response && typeof response === "object") {
+      content = response.content;
+    }
+    if (typeof content === "string" && !content.includes("Error")) {
+      const loyaltyBonus = 500;
+      const enrichedContent = `Booking Confirmed!\n You earned ${loyaltyBonus} Loyalty Points with this stay.\n\nSystem Details: ${content}`;
+
+      if (response && typeof response === "object") {
+        return { ...response, content: enrichedContent };
+      }
+      return enrichedContent;
+    }
+  }
+  return response;
+}
+
+async function runTurn(runner, userId, sessionId, prompt) {
+  console.log(`\nUSER: '${prompt}'`);
+  const content = { role: 'user', parts: [{ text: prompt }] };
+  const stream = runner.runAsync({ userId, sessionId, newMessage: content });
+  
+  let fullText = "";
+  for await (const chunk of stream) {
+      if (chunk.content && chunk.content.parts) {
+          fullText += chunk.content.parts.map(p => p.text || "").join("");
+      }
+  }
+  
+  console.log("-".repeat(50));
+  console.log(`AI: ${fullText}`);
+}
+
+export async function main() {
+  const userId = 'test_user';
+  const client = new ToolboxClient('http://127.0.0.1:5000');
+  const tools = await client.loadToolset("my-toolset");
+  
+  const rootAgent = new LlmAgent({
+    name: 'hotel_agent',
+    model: 'gemini-2.5-flash',
+    description: 'Agent for hotel bookings and administration.',
+    instruction: systemPrompt,
+    tools: tools,
+    // Add any pre- and post- processing callbacks
+    beforeToolCallback: enforeBusinessRules,
+    afterToolCallback: enrichResponse
+  });
+
+  const appName = rootAgent.name;
+  const runner = new InMemoryRunner({ agent: rootAgent, appName, logLevel: LogLevel.ERROR });
+  const session = await runner.sessionService.createSession({ appName, userId });
+
+  // Turn 1: Booking
+  await runTurn(runner, userId, session.id, "Book hotel with id 3.");
+
+  // Turn 2: Policy Violation
+  await runTurn(runner, userId, session.id, "Update my hotel with id 3 with checkin date 2025-01-18 and checkout date 2025-02-10");
+}
+
+main();

docs/en/samples/pre_post_processing/js/adk/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "adk",
+  "version": "1.0.0",
+  "description": "ADK.js sample for pre/post processing",
+  "type": "module",
+  "main": "agent.js",
+  "scripts": {
+    "start": "node agent.js"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@google/adk": "^0.2.0",
+    "@toolbox-sdk/adk": "^0.2.1"
+  }
+}

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

@@ -0,0 +1 @@
+# Empty init for package resolution