feat(go/ai): added DefineMiddleware (Middleware V2)

.github/workflows/build-cli-binaries.yml

@@ -146,20 +146,26 @@ jobs:
         shell: bash
         run: |
           echo "Testing genkit --help"
-          ./genkit-${{ matrix.target }}${{ steps.binary.outputs.ext }} --help
+          ./genkit-${{ matrix.target }}${STEPS_BINARY_OUTPUTS_EXT} --help
+        env:
+          STEPS_BINARY_OUTPUTS_EXT: ${{ steps.binary.outputs.ext }}
 
       - name: Test --version command
         shell: bash
         run: |
           echo "Testing genkit --version"
-          ./genkit-${{ matrix.target }}${{ steps.binary.outputs.ext }} --version
+          ./genkit-${{ matrix.target }}${STEPS_BINARY_OUTPUTS_EXT} --version
+        env:
+          STEPS_BINARY_OUTPUTS_EXT: ${{ steps.binary.outputs.ext }}
 
       - name: Verify UI commands exist
         shell: bash
         run: |
           echo "Verifying UI commands are available"
-          ./genkit-${{ matrix.target }}${{ steps.binary.outputs.ext }} ui:start --help
-          ./genkit-${{ matrix.target }}${{ steps.binary.outputs.ext }} ui:stop --help
+          ./genkit-${{ matrix.target }}${STEPS_BINARY_OUTPUTS_EXT} ui:start --help
+          ./genkit-${{ matrix.target }}${STEPS_BINARY_OUTPUTS_EXT} ui:stop --help
+        env:
+          STEPS_BINARY_OUTPUTS_EXT: ${{ steps.binary.outputs.ext }}
 
       - name: Test UI start functionality (Unix only)
         if: runner.os != 'Windows'

.github/workflows/bump-cli-version.yml

@@ -63,7 +63,9 @@ jobs:
 
       - name: Bump and Tag
         run: |
-          js/scripts/bump_and_tag_cli.sh ${{ inputs.releaseType }} ${{ inputs.preid }}
+          js/scripts/bump_and_tag_cli.sh ${{ inputs.releaseType }} ${INPUTS_PREID}
+        env:
+          INPUTS_PREID: ${{ inputs.preid }}
 
       - name: Push
         shell: bash

.github/workflows/bump-js-version.yml

@@ -63,7 +63,9 @@ jobs:
 
       - name: Bump and Tag
         run: |
-          js/scripts/bump_and_tag_js.sh ${{ inputs.releaseType }} ${{ inputs.preid }}
+          js/scripts/bump_and_tag_js.sh ${{ inputs.releaseType }} ${INPUTS_PREID}
+        env:
+          INPUTS_PREID: ${{ inputs.preid }}
 
       - name: Push
         shell: bash

.github/workflows/bump-package-version.yml

@@ -71,7 +71,11 @@ jobs:
 
       - name: Bump and Tag
         run: |
-          js/scripts/bump_and_tag.sh ${{ inputs.packageDir }} ${{ inputs.packageName }} ${{ inputs.releaseType }} ${{ inputs.preid }}
+          js/scripts/bump_and_tag.sh ${INPUTS_PACKAGEDIR} ${INPUTS_PACKAGENAME} ${{ inputs.releaseType }} ${INPUTS_PREID}
+        env:
+          INPUTS_PACKAGEDIR: ${{ inputs.packageDir }}
+          INPUTS_PACKAGENAME: ${{ inputs.packageName }}
+          INPUTS_PREID: ${{ inputs.preid }}
 
       - name: Push
         shell: bash

.github/workflows/publish_python.yml

@@ -224,16 +224,16 @@ jobs:
           echo "**Dry Run:** ${{ inputs.dry_run }}" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
 
-          if [ "${{ needs.publish.result }}" == "success" ]; then
+          if [ "${NEEDS_PUBLISH_RESULT}" == "success" ]; then
             echo "### ✅ Publish Status: Success" >> $GITHUB_STEP_SUMMARY
           else
             echo "### ❌ Publish Status: Failed" >> $GITHUB_STEP_SUMMARY
           fi
           echo "" >> $GITHUB_STEP_SUMMARY
 
-          if [ "${{ needs.verify.result }}" == "success" ]; then
+          if [ "${NEEDS_VERIFY_RESULT}" == "success" ]; then
             echo "### ✅ Verification: Passed" >> $GITHUB_STEP_SUMMARY
-          elif [ "${{ needs.verify.result }}" == "failure" ]; then
+          elif [ "${NEEDS_VERIFY_RESULT}" == "failure" ]; then
             echo "### ⚠️ Verification: Some packages failed" >> $GITHUB_STEP_SUMMARY
           else
             echo "### ⏭️ Verification: Skipped" >> $GITHUB_STEP_SUMMARY
@@ -244,3 +244,8 @@ jobs:
           echo "1. Verify on PyPI: https://pypi.org/project/genkit/$VERSION/" >> $GITHUB_STEP_SUMMARY
           echo "2. Test installation: \`pip install genkit==$VERSION\`" >> $GITHUB_STEP_SUMMARY
           echo "3. Update documentation if needed" >> $GITHUB_STEP_SUMMARY
+
+        env:
+          NEEDS_PUBLISH_RESULT: ${{ needs.publish.result }}
+
+          NEEDS_VERIFY_RESULT: ${{ needs.verify.result }}

.github/workflows/release_js_main.yml

@@ -62,6 +62,7 @@ jobs:
         registry-url: 'https://wombat-dressing-room.appspot.com/'
     - name: release script
       shell: bash
-      run: RELEASE_BRANCH=${{ steps.extract_branch.outputs.branch }} RELEASE_TAG=${{ inputs.releaseTag }} scripts/release_main.sh
+      run: RELEASE_BRANCH=${STEPS_EXTRACT_BRANCH_OUTPUTS_BRANCH} RELEASE_TAG=${{ inputs.releaseTag }} scripts/release_main.sh
       env:
         NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
+        STEPS_EXTRACT_BRANCH_OUTPUTS_BRANCH: ${{ steps.extract_branch.outputs.branch }}

.github/workflows/release_js_package.yml

@@ -65,7 +65,9 @@ jobs:
     - name: release script
       shell: bash
       run: |
-          cd ${{ inputs.packageDir }}
-          pnpm publish --tag ${{ inputs.releaseTag }} --publish-branch ${{ steps.extract_branch.outputs.branch }} --access=public --registry https://wombat-dressing-room.appspot.com
+          cd ${INPUTS_PACKAGEDIR}
+          pnpm publish --tag ${{ inputs.releaseTag }} --publish-branch ${STEPS_EXTRACT_BRANCH_OUTPUTS_BRANCH} --access=public --registry https://wombat-dressing-room.appspot.com
       env:
         NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
+        INPUTS_PACKAGEDIR: ${{ inputs.packageDir }}
+        STEPS_EXTRACT_BRANCH_OUTPUTS_BRANCH: ${{ steps.extract_branch.outputs.branch }}

.github/workflows/releasekit-uv.yml

@@ -234,14 +234,14 @@ jobs:
           if [ "${{ inputs.force_prepare }}" = "true" ]; then
             cmd+=(--force)
           fi
-          if [ -n "${{ inputs.group }}" ]; then
-            cmd+=(--group "${{ inputs.group }}")
+          if [ -n "${INPUTS_GROUP}" ]; then
+            cmd+=(--group "${INPUTS_GROUP}")
           fi
           if [ "${{ inputs.bump_type }}" != "auto" ] && [ -n "${{ inputs.bump_type }}" ]; then
             cmd+=(--bump "${{ inputs.bump_type }}")
           fi
-          if [ -n "${{ inputs.prerelease }}" ]; then
-            cmd+=(--prerelease "${{ inputs.prerelease }}")
+          if [ -n "${INPUTS_PRERELEASE}" ]; then
+            cmd+=(--prerelease "${INPUTS_PRERELEASE}")
           fi
 
           # Run prepare — capture output even on failure so CI logs
@@ -264,6 +264,10 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+          INPUTS_GROUP: ${{ inputs.group }}
+
+          INPUTS_PRERELEASE: ${{ inputs.prerelease }}
+
   # ═══════════════════════════════════════════════════════════════════════
   # RELEASE: Tag merge commit and create GitHub Release
   #
@@ -308,7 +312,7 @@ jobs:
           echo "::group::Execution Plan (ASCII)"
           uv run --directory ${{ env.RELEASEKIT_DIR }} releasekit --workspace py plan --format full 2>&1 || true
           echo "::endgroup::"
-          if [ "${{ env.DRY_RUN }}" = "true" ]; then
+          if [ "${DRY_RUN}" = "true" ]; then
             echo "::notice::DRY RUN — no tags or releases will be created"
           else
             echo "::notice::LIVE RUN — tags and GitHub Release will be created"
@@ -322,7 +326,7 @@ jobs:
           set -euo pipefail
 
           DRY_RUN_FLAG=""
-          if [ "${{ env.DRY_RUN }}" = "true" ]; then
+          if [ "${DRY_RUN}" = "true" ]; then
             DRY_RUN_FLAG="--dry-run"
           fi
 
@@ -389,7 +393,7 @@ jobs:
           echo "::group::Execution Plan (ASCII)"
           uv run --directory ${{ env.RELEASEKIT_DIR }} releasekit --workspace py plan --format full 2>&1 || true
           echo "::endgroup::"
-          if [ "${{ env.DRY_RUN }}" = "true" ]; then
+          if [ "${DRY_RUN}" = "true" ]; then
             echo "::notice::DRY RUN — no packages will be published"
           else
             echo "::notice::LIVE RUN — packages will be published to ${{ inputs.target || 'pypi' }}"
@@ -401,7 +405,7 @@ jobs:
 
           cmd=(uv run --directory ${{ env.RELEASEKIT_DIR }} releasekit --workspace py publish --force)
 
-          if [ "${{ env.DRY_RUN }}" = "true" ]; then
+          if [ "${DRY_RUN}" = "true" ]; then
             cmd+=(--dry-run)
           fi
 
@@ -412,16 +416,16 @@ jobs:
             cmd+=(--index-url "$PUBLISH_INDEX_URL")
           fi
 
-          CONCURRENCY="${{ inputs.concurrency }}"
+          CONCURRENCY="${INPUTS_CONCURRENCY}"
           if [ -n "$CONCURRENCY" ] && [ "$CONCURRENCY" != "0" ]; then
             cmd+=(--concurrency "$CONCURRENCY")
           fi
 
-          if [ -n "${{ inputs.group }}" ]; then
-            cmd+=(--group "${{ inputs.group }}")
+          if [ -n "${INPUTS_GROUP}" ]; then
+            cmd+=(--group "${INPUTS_GROUP}")
           fi
 
-          MAX_RETRIES="${{ inputs.max_retries }}"
+          MAX_RETRIES="${INPUTS_MAX_RETRIES}"
           if [ -n "$MAX_RETRIES" ] && [ "$MAX_RETRIES" != "0" ]; then
             cmd+=(--max-retries "$MAX_RETRIES")
           fi
@@ -439,6 +443,9 @@ jobs:
           # For trusted publishing (OIDC), no token needed.
           # For API token auth, set PYPI_TOKEN / TESTPYPI_TOKEN in repo secrets.
           UV_PUBLISH_TOKEN: ${{ inputs.target == 'testpypi' && secrets.TESTPYPI_TOKEN || secrets.PYPI_TOKEN }}
+          INPUTS_CONCURRENCY: ${{ inputs.concurrency }}
+          INPUTS_GROUP: ${{ inputs.group }}
+          INPUTS_MAX_RETRIES: ${{ inputs.max_retries }}
 
       - name: Upload manifest artifact
         uses: actions/upload-artifact@v4

genkit-tools/common/src/types/index.ts

@@ -23,6 +23,7 @@ export * from './document';
 export * from './env';
 export * from './eval';
 export * from './evaluator';
+export * from './middleware';
 export * from './model';
 export * from './prompt';
 export * from './retriever';

genkit-tools/common/src/types/middleware.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 { z } from 'zod';
+
+/** Descriptor for a registered middleware, returned by reflection API. */
+export const MiddlewareDescSchema = z.object({
+  /** Unique name of the middleware. */
+  name: z.string(),
+  /** Human-readable description of what the middleware does. */
+  description: z.string().optional(),
+  /** JSON Schema for the middleware's configuration. */
+  configSchema: z.record(z.any()).nullish(),
+  /** User defined metadata for the middleware. */
+  metadata: z.record(z.any()).optional(),
+});
+export type MiddlewareDesc = z.infer<typeof MiddlewareDescSchema>;
+
+/** Reference to a registered middleware with optional configuration. */
+export const MiddlewareRefSchema = z.object({
+  /** Name of the registered middleware. */
+  name: z.string(),
+  /** Configuration for the middleware (schema defined by the middleware). */
+  config: z.any().optional(),
+});
+export type MiddlewareRef = z.infer<typeof MiddlewareRefSchema>;

genkit-tools/common/src/types/model.ts

@@ -15,6 +15,7 @@
  */
 import { z } from 'zod';
 import { DocumentDataSchema } from './document';
+import { MiddlewareRefSchema } from './middleware';
 import {
   CustomPartSchema,
   DataPartSchema,
@@ -399,5 +400,7 @@ export const GenerateActionOptionsSchema = z.object({
   maxTurns: z.number().optional(),
   /** Custom step name for this generate call to display in trace views. Defaults to "generate". */
   stepName: z.string().optional(),
+  /** Middleware to apply to this generation. */
+  use: z.array(MiddlewareRefSchema).optional(),
 });
 export type GenerateActionOptions = z.infer<typeof GenerateActionOptionsSchema>;

genkit-tools/genkit-schema.json

@@ -270,6 +270,49 @@
       ],
       "additionalProperties": false
     },
+    "MiddlewareDesc": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "configSchema": {
+          "anyOf": [
+            {
+              "type": "object",
+              "additionalProperties": {}
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": {}
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false
+    },
+    "MiddlewareRef": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "config": {}
+      },
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false
+    },
     "CandidateError": {
       "type": "object",
       "properties": {
@@ -466,6 +509,12 @@
         },
         "stepName": {
           "type": "string"
+        },
+        "use": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/MiddlewareRef"
+          }
         }
       },
       "required": [

genkit-tools/scripts/schema-exporter.ts

@@ -26,6 +26,7 @@ const EXPORTED_TYPE_MODULES = [
   '../common/src/types/embedder.ts',
   '../common/src/types/evaluator.ts',
   '../common/src/types/error.ts',
+  '../common/src/types/middleware.ts',
   '../common/src/types/model.ts',
   '../common/src/types/parts.ts',
   '../common/src/types/reranker.ts',

go/ai/gen.go

@@ -96,6 +96,8 @@ type GenerateActionOptions struct {
 	ToolChoice ToolChoice `json:"toolChoice,omitempty"`
 	// Tools is a list of registered tool names for this generation if supported.
 	Tools []string `json:"tools,omitempty"`
+	// Use is middleware to apply to this generation, referenced by name with optional config.
+	Use []*MiddlewareRef `json:"use,omitempty"`
 }
 
 // GenerateActionResume holds options for resuming an interrupted generation.
@@ -206,6 +208,27 @@ type Message struct {
 	Role Role `json:"role,omitempty"`
 }
 
+// MiddlewareDesc is the registered descriptor for a middleware.
+type MiddlewareDesc struct {
+	// ConfigSchema is a JSON Schema describing the middleware's configuration.
+	ConfigSchema map[string]any `json:"configSchema,omitempty"`
+	// Description explains what the middleware does.
+	Description string `json:"description,omitempty"`
+	// Metadata contains additional context for the middleware.
+	Metadata map[string]any `json:"metadata,omitempty"`
+	// Name is the middleware's unique identifier.
+	Name           string `json:"name,omitempty"`
+	configFromJSON middlewareConfigFunc
+}
+
+// MiddlewareRef is a serializable reference to a registered middleware with config.
+type MiddlewareRef struct {
+	// Config contains the middleware configuration.
+	Config any `json:"config,omitempty"`
+	// Name is the name of the registered middleware.
+	Name string `json:"name,omitempty"`
+}
+
 // ModelInfo contains metadata about a model's capabilities and characteristics.
 type ModelInfo struct {
 	// ConfigSchema defines the model-specific configuration schema.