AI Agents10 min readBy Petrică RădanReference guide
Human-in-the-Loop Workflows for Gemini Agents on Google Cloud
Learn how to decouple Gemini function calling from human review by persisting conversation state in Firestore and resuming execution via Cloud Tasks, Cloud Run, and Next.js
Architecting a Gemini agent human in the loop workflow requires decoupling synchronous model inference from asynchronous human review by serializing the conversation state to Firestore and resuming execution via Cloud Tasks. In a production deployment on Google Cloud, a Next.js application running on Cloud Run intercepts high-consequence Gemini function calls, persists the exact model candidate payload, and terminates the HTTP request so compute instances can scale to zero. Once an operator approves, edits, or rejects the pending action in the Next.js interface, the backend enqueues an authenticated task into Cloud Tasks, which dispatches a background Cloud Run worker to execute the tool and continue the Gemini session.
Engineering deterministic checkpoints into autonomous pipelines addresses both operational reliability and regulatory governance. Implementing structured human-in-the-loop approval gates across 4.2 million agent tasks over 14 months reduced an autonomous agent pipeline's critical error rate from 23% to 5.1%, representing a 78% reduction, according to DEV Community (2026). Furthermore, according to a Dataiku and Harris Poll survey of over 800 global data leaders reported by Dataiku Blog (2026), only 5% say AI output is traceable 100% of the time. Structured approval checkpoints close this auditability gap to satisfy EU AI Act Article 14 oversight requirements, which carry fines up to 15 million euros or 3% of global turnover, according to Dataiku Blog (2026).
Why do Google Cloud serverless AI agents require an asynchronous AI agent approval workflow?
Google Cloud serverless AI agents cannot hold open synchronous HTTP connections while awaiting human intervention because Cloud Run enforces strict request timeout limits and bills for active container instance duration. Moving human review into an asynchronous AI agent approval workflow allows the initial Cloud Run instance to exit immediately after persisting state, preventing dropped connections and idle compute costs when managers take hours or days to respond.
A production blueprint documented by Google Cloud Blog (2026) separates this workload into a three-layer generative workflow architecture: creative generation powered by models such as Gemini 3.1 Pro, deterministic rules and validation with human-in-the-loop review gates stored in Firestore, and asynchronous background processing dispatched via Cloud Tasks to Cloud Run workers. Isolating the validation gate from the model layer ensures that security policies execute deterministically in application code rather than relying on prompt instructions. When a tool call triggers a validation rule, the application suspends the turn before any external API mutation occurs.
Selective policy gating is equally critical because interrupting operators on routine actions degrades review quality. In March 2026, Anthropic published data showing that developers accepted 93% of permission prompts from its coding agent, leading to approval fatigue and necessitating selective gating based on consequence and reversibility, according to Human in the Loop AI Agent Approval: How It Works (2026). For example, a reimbursement agent documented in Human-in-the-Loop AI Agents with Google ADK and Telegram (2026) uses a tool threshold to automatically approve requests under $100 while pausing execution with a pending ticket ID for amounts over $100 until a manager responds via an asynchronous webhook pipeline. When reserved for high-blast-radius actions alongside automated pre-checks, governance does not compromise speed: across simulated Black Friday cache-stampede outages, Google Cloud's Project Chrysalis architecture running on Gemini and ADK with human sign-off capabilities cut time-to-first-mitigation from 15–45 minutes down to 1.8 seconds and dropped P99 latency from 519.8 ms to 18.2 ms, according to Architecting Governed, Self-Evolving AI Agents on Google Cloud (2026).
Engineers building on Google Cloud can choose among several primitives for managing long-running human wait states. Selecting the right service depends on your maximum approval window, existing web framework, and control requirements over conversation persistence.
| Google Cloud Primitive | Maximum Wait or Schedule Horizon | State and Execution Model | Primary Architectural Fit |
|---|---|---|---|
| Cloud Tasks | Up to 30 days (30 * 60 * 60 * 24 seconds) into the future (Create an HTTP task within an App Engine app - Google Cloud Documentation, 2026) | Stateless HTTP dispatch queue targeting Cloud Run handlers with OIDC authentication; agent state persists externally in Firestore or SQL | Next.js and Cloud Run applications requiring fine-grained control over UI streaming, Firestore schemas, and timeout escalations |
| Google Cloud Workflows | Up to 1 year for stateful callbacks and retries, with 5,000 free steps and 2,000 external API calls per month (Google Cloud Documentation, 2026) | Managed orchestration engine that exposes native callback endpoints and suspends step state until an external HTTP request arrives | Multi-service enterprise pipelines requiring multi-month audit wait windows across heterogeneous internal APIs |
| Google Cloud Agent Runtime | Up to 7 days of maintained state while consuming zero compute resources, announced at Google Cloud Next '26 (Google Cloud Blog, 2026) | Managed agent hosting environment supporting delegated approval workflows where the runtime natively pauses and restores agent state | Greenfield agent backends built directly on Google ADK without custom Next.js session persistence layers |
How do you implement function calling interrupts and execution pausing in Gemini?
You pause a Gemini tool loop by inspecting the model's returned functionCall part before invoking the underlying TypeScript or Python function and breaking out of the runner loop whenever policy rules demand human sign-off. Instead of executing the side effect and sending a functionResponse back to the model, the backend writes a pending approval record to the database and returns the ticket metadata to the frontend.
Every autonomous loop must also enforce strict iteration ceilings across both active and resumed turns. In production Gemini function calling loops, implementing a hard step limit such as MAX_STEPS = 10 prevents confused models from calling functions indefinitely and burning tokens, according to Medium (2026). Storing the cumulative step count inside the paused session document ensures that resuming an agent after human sign-off enforces the original token and iteration budget.
Gemini agent human in the loop: Gemini Function Calling and Execution Pausing
If you build with Google's framework ecosystem rather than raw Vertex AI SDK calls, native interrupt primitives handle the pause lifecycle automatically. According to Agent Development Kit (ADK) Documentation (2026), Google's ADK supports native Tool Confirmation for pausing tool execution across ADK Python v1.14.0, TypeScript v0.2.0, Go v0.3.0, and Kotlin v0.1.0, as well as ADK for Kotlin 1.0. ADK provides two mechanisms for human oversight: wrapping a function in a LongRunningFunctionTool such as ask_for_approval that immediately returns a status: pending ticket, or configuring ToolConfirmation to emit a system REQUEST_CONFIRMATION_FUNCTION_CALL_NAME interrupt. In a production database incident response agent built with ADK for Kotlin 1.0, Session Resumability pauses, serializes, and restores active agent interactions across user sessions, resuming only when a user submits a FunctionResponse containing ToolConfirmation.CONFIRMED_KEY set to true, according to Google for Developers Blog (2026).
Middleware architectures offer equivalent interception hooks for custom TypeScript backends. On May 14, 2026, Google announced Genkit Middleware for TypeScript, Go, and Dart, introducing composable hooks at 3 distinct layers of the tool loop—Generate, Model, and Tool—to intercept execution for human-in-the-loop approval and retries, according to Google for Developers Blog (2026). When designing the payload schema for human responses at the Tool layer, engineers can model the 4 built-in decision types defined by LangChain's Human-in-the-Loop middleware—approve, edit, reject, and respond—according to Docs by LangChain (2026).
- Approve: The worker runs the target function with the exact arguments generated by Gemini and returns the raw execution output inside a FunctionResponse turn.
- Edit: The reviewer modifies sensitive tool parameters in the UI prior to execution, and the worker runs the updated call while returning both the result and parameter change context to Gemini.
- Reject: The worker skips tool execution completely and returns a structured denial object inside the FunctionResponse so Gemini can halt safely or propose a non-destructive alternative.
- Respond: The reviewer injects domain context or clarifying instructions directly back into the conversation history without invoking the underlying tool.
How do you manage stateful agent persistence during human wait states?
Because the Gemini API is stateless across requests, pausing an agent requires serializing the entire conversation contents array to a durable database such as Firestore before the Cloud Run request terminates. When the human reviewer submits a decision, the background worker loads that exact array and appends a matching user-role functionResponse turn to resume inference.
Gemini agent human in the loop: Stateful Agent Persistence during Human Wait States
The persisted JSON array must maintain the strict alternating role structure required by Gemini: a user object containing prompt or tool response parts, followed by the exact model candidate content object containing the functionCall part with its name, args, and id. When using Gemini 3 and thinking models with function calling, the model emits thought: true reasoning parts alongside a cryptographic thoughtSignature attached to the initial functionCall part. Your Firestore serialization logic must persist the raw candidate.content object intact without stripping unfamiliar properties or reconstructing the model message from scratch.
When pausing Gemini 3 thinking models for human approval, always serialize the exact candidate.content object returned by the API. Dropping the thoughtSignature on the functionCall part or failing to echo back the matching call id in your FunctionResponse will cause the Gemini API to fail validation upon resumption.
To resume execution after human review, the Cloud Run worker fetches the stored contents history from Firestore and appends a user turn formatted as {role: 'user', parts: [{functionResponse: {name, id, response: {result}}}]}. Both the tool name and the exact id from the paused functionCall must be present before calling generateContent. If Gemini emitted parallel function calls in a single turn—for instance, pairing an auto-approved lookup tool with an approval-gated write tool—your persistence layer must buffer the auto-approved result and submit all functionResponse parts for that turn together in a single user message once the gated call is resolved.
1import { GoogleGenAI, Content } from '@google/genai';
2import { Firestore } from '@google-cloud/firestore';
3
4const ai = new GoogleGenAI({});
5const db = new Firestore();
6const MAX_STEPS = 10;
7
8export async function runOrPauseAgentTurn(sessionId: string): Promise<{ status: string; ticketId?: string }> {
9 const sessionRef = db.collection('agentSessions').doc(sessionId);
10 const snap = await sessionRef.get();
11 const session = snap.data() as { contents: Content[]; stepCount: number };
12
13 if (session.stepCount >= MAX_STEPS) {
14 throw new Error('Agent exceeded MAX_STEPS limit');
15 }
16
17 const response = await ai.models.generateContent({
18 model: 'gemini-3.1-pro-preview',
19 contents: session.contents,
20 config: { tools: [{ functionDeclarations: [reimbursementToolDeclaration] }] }
21 });
22
23 const [candidate] = response.candidates ?? [];
24 if (!candidate?.content) throw new Error('Empty model candidate');
25
26 // Preserve exact candidate.content including thoughtSignature and functionCall.id
27 const updatedContents: Content[] = [...session.contents, candidate.content];
28 const calls = candidate.content.parts?.filter((p) => p.functionCall) ?? [];
29
30 for (const part of calls) {
31 const call = part.functionCall!;
32 if (call.name === 'submit_reimbursement' && Number(call.args?.amount) > 100) {
33 const ticketRef = db.collection('approvalTickets').doc(call.id!);
34 await db.runTransaction(async (tx) => {
35 tx.update(sessionRef, { contents: updatedContents, stepCount: session.stepCount + 1, state: 'PAUSED' });
36 tx.set(ticketRef, {
37 sessionId,
38 callId: call.id,
39 toolName: call.name,
40 proposedArgs: call.args,
41 status: 'PENDING'
42 });
43 });
44 return { status: 'PENDING_APPROVAL', ticketId: call.id };
45 }
46 }
47
48 await sessionRef.update({ contents: updatedContents, stepCount: session.stepCount + 1, state: 'COMPLETED' });
49 return { status: 'COMPLETED' };
50}
51
52export async function resumePausedAgent(ticketId: string, decision: 'APPROVE' | 'REJECT', editedArgs?: Record<string, unknown>) {
53 const ticketSnap = await db.collection('approvalTickets').doc(ticketId).get();
54 const ticket = ticketSnap.data()!;
55 const sessionRef = db.collection('agentSessions').doc(ticket.sessionId);
56 const session = (await sessionRef.get()).data() as { contents: Content[]; stepCount: number };
57
58 const toolResult = decision === 'APPROVE'
59 ? await executeReimbursement(editedArgs ?? ticket.proposedArgs)
60 : { error: 'Action rejected by human reviewer' };
61
62 const resumedContents: Content[] = [
63 ...session.contents,
64 {
65 role: 'user',
66 parts: [{
67 functionResponse: {
68 name: ticket.toolName,
69 id: ticket.callId,
70 response: { result: toolResult }
71 }
72 }]
73 }
74 ];
75
76 await sessionRef.update({ contents: resumedContents, state: 'RUNNING' });
77 return runOrPauseAgentTurn(ticket.sessionId);
78}How do you design a Next.js Cloud Run Gemini architecture for approval UIs?
A production Next.js Cloud Run Gemini architecture separates interactive streaming from background resumption by using Route Handlers to stream active chat turns and Server Actions to record authenticated human review decisions. Hosting the Next.js container on Cloud Run places your frontend rendering, approval mutations, and background worker routes inside a single Google Cloud IAM perimeter.
On the frontend, chat views must transition cleanly from streaming tokens to rendering interactive approval controls whenever a gated tool interrupts the turn. In a Next.js chatbot application, human-in-the-loop tool execution approval is implemented using the AI SDK's needsApproval property on tools and managed on the frontend via the useChat hook from @ai-sdk/react communicating with the /api/chat route, according to Human-in-the-Loop with Next.js - AI SDK (2026). Similarly, in Next.js and Workflow SDK applications documented by AI SDK Documentation (2026), a flight booking agent defines an approval-gated confirmBooking tool with needsApproval enabled, streaming an approval-requested state to the client UI and pausing execution until addToolApprovalResponse() is invoked with a cryptographically signed decision.
Preventing Race Conditions with Optimistic Locking and Idempotency
Asynchronous human interfaces introduce two concurrency hazards: multiple reviewers clicking Approve on the same shared dashboard simultaneously, and Cloud Tasks retrying HTTP delivery after transient network faults. To block duplicate task scheduling at the UI boundary, your Next.js Server Action should update the Firestore approval ticket inside an atomic transaction. The transaction checks that the ticket status equals PENDING, writes the reviewer's identity alongside the new APPROVED or REJECTED status, and aborts immediately if another request already claimed the ticket.
Idempotency must also extend into the background worker that executes the external tool. If an external payment API succeeds on the initial Cloud Tasks dispatch but the subsequent Gemini generateContent call fails due to a transient network blip, Cloud Tasks will retry the worker endpoint. Recording the external tool's output in Firestore keyed by the deterministic Gemini functionCall id allows the retried worker to detect prior execution, bypass the side effect, and proceed directly to injecting the cached FunctionResponse.
How does Cloud Tasks AI workflow orchestration handle background resumption and timeouts?
Cloud Tasks AI workflow orchestration decouples the Next.js approval click from slow downstream APIs and multi-step Gemini inference by queuing durable HTTP requests to an internal Cloud Run worker endpoint. It also handles abandoned reviews by letting your backend schedule a future timeout inspection task at the exact moment an agent pauses.
Tuning queue dispatch parameters prevents sudden bursts of human approvals from exhausting Cloud Run container concurrency or Vertex AI model quotas. According to How to Send HTTP Tasks to Cloud Run Services Using Cloud Tasks (2026), production Cloud Tasks queues targeting Cloud Run handlers are commonly configured with rate limits such as 50 max dispatches per second, 20 max concurrent dispatches, 5 max attempts, a minimum backoff of 10 seconds, and a maximum backoff of 300 seconds. For stalled reviews, Cloud Tasks allows scheduling tasks up to a maximum limit of 30 days (30 * 60 * 60 * 24 seconds) into the future, enabling delayed execution or timeout checks for human-in-the-loop workflows, according to Create an HTTP task within an App Engine app in Google Cloud Documentation (2026). When creating the pending Firestore ticket, enqueue a secondary task with scheduleTime set to your SLA deadline; if the ticket is still PENDING when the task fires, the worker marks it EXPIRED and injects a cancellation FunctionResponse so the session closes cleanly.
Securing Cloud Tasks to Cloud Run Dispatch with OIDC
Internal worker endpoints on Cloud Run that execute approved agent tools must reject unauthenticated external traffic. As documented in How to Create and Process Cloud Tasks from a Node.js Express Application (2026), a Node.js backend creates authenticated HTTP target tasks using @google-cloud/tasks by setting httpRequest.oidcToken with serviceAccountEmail and audience set to the Cloud Run SERVICE_URL, while base64-encoding the JSON task payload. Inside the Next.js Route Handler, the application verifies incoming requests using google-auth-library's OAuth2Client.verifyIdToken alongside the x-cloudtasks-taskname and x-cloudtasks-queuename headers before touching Firestore or Vertex AI.
1import { CloudTasksClient } from '@google-cloud/tasks';
2import { OAuth2Client } from 'google-auth-library';
3import { NextRequest, NextResponse } from 'next/server';
4import { resumePausedAgent } from '@/lib/agent-runner';
5
6const tasksClient = new CloudTasksClient();
7const authClient = new OAuth2Client();
8
9export async function enqueueResumptionTask(payload: {
10 ticketId: string;
11 decision: 'APPROVE' | 'REJECT';
12 editedArgs?: Record<string, unknown>;
13}) {
14 const queuePath = tasksClient.queuePath(
15 process.env.GCP_PROJECT_ID!,
16 process.env.GCP_LOCATION!,
17 process.env.CLOUD_TASKS_QUEUE!
18 );
19 const serviceUrl = process.env.CLOUD_RUN_SERVICE_URL!;
20
21 await tasksClient.createTask({
22 parent: queuePath,
23 task: {
24 httpRequest: {
25 httpMethod: 'POST',
26 url: `${serviceUrl}/api/worker/resume`,
27 headers: { 'Content-Type': 'application/json' },
28 body: Buffer.from(JSON.stringify(payload)).toString('base64'),
29 oidcToken: {
30 serviceAccountEmail: process.env.TASKS_INVOKER_SA_EMAIL!,
31 audience: serviceUrl
32 }
33 }
34 }
35 });
36}
37
38export async function POST(req: NextRequest) {
39 const taskName = req.headers.get('x-cloudtasks-taskname');
40 const queueName = req.headers.get('x-cloudtasks-queuename');
41 const authHeader = req.headers.get('authorization');
42
43 if (!taskName || !queueName || !authHeader?.startsWith('Bearer ')) {
44 return NextResponse.json({ error: 'Missing Cloud Tasks headers or OIDC token' });
45 }
46
47 const idToken = authHeader.split('Bearer ')[1];
48 const ticket = await authClient.verifyIdToken({
49 idToken,
50 audience: process.env.CLOUD_RUN_SERVICE_URL!
51 });
52
53 const payload = ticket.getPayload();
54 if (payload?.email !== process.env.TASKS_INVOKER_SA_EMAIL) {
55 return NextResponse.json({ error: 'Invalid invoker service account' });
56 }
57
58 const body = await req.json();
59 const result = await resumePausedAgent(body.ticketId, body.decision, body.editedArgs);
60 return NextResponse.json({ resumed: true, result });
61}What are the practical next steps for deploying this architecture?
Deploying a production human-in-the-loop Gemini agent on Google Cloud requires defining clear tool risk boundaries, atomic state persistence schemas, and authenticated task queues before exposing autonomous actions to end users. Engineering teams can roll out this architecture cleanly by executing the following implementation sequence.
- Classify every agent tool declaration by consequence and reversibility, allowing read-only lookups and low-value actions such as reimbursements under $100 to run automatically while enforcing interrupts on destructive writes and external financial mutations.
- Create a Firestore session schema that stores the unmodified Gemini contents array—preserving Gemini 3 thoughtSignature metadata and functionCall IDs—paired with an explicit step counter capped at MAX_STEPS = 10 and optimistic locking fields.
- Provision a dedicated Cloud Tasks queue configured with production dispatch bounds—such as 50 max dispatches per second, 20 max concurrent dispatches, 5 max attempts, a 10-second minimum backoff, and a 300-second maximum backoff—and configure a least-privilege IAM service account for OIDC token minting.
- Build Next.js approval UI cards and Server Actions supporting approve, edit, reject, and respond workflows, while scheduling delayed Cloud Tasks timeout checks within the 30-day scheduling horizon to automatically expire abandoned tickets.
- Emit immutable audit records linking each resumed FunctionResponse to the reviewer's authenticated identity, timestamp, and argument diff to maintain end-to-end traceability for internal security reviews and EU AI Act Article 14 compliance.
Sources
- Google, Agent Development Kit (ADK) Documentation (2026) (opens in a new tab)
- Vinothkumar Kolluru, Medium (2026) (opens in a new tab)
- Google Cloud, Google Cloud Documentation (2026) (opens in a new tab)
- Google Cloud, Create an HTTP task within an App Engine app - Google Cloud Documentation (2026) (opens in a new tab)
- Google Cloud, Architecting Governed, Self-Evolving AI Agents on Google Cloud (2026) (opens in a new tab)
- OneUptime, How to Send HTTP Tasks to Cloud Run Services Using Cloud Tasks (2026) (opens in a new tab)
- Google Cloud, Google Cloud Blog (2026) (opens in a new tab)
- DEV Community (2026) (opens in a new tab)
- Dataiku, Dataiku Blog (2026) (opens in a new tab)
- Squirro, Human in the Loop AI Agent Approval: How It Works (2026) (opens in a new tab)
- Chris Gill, Product Manager at Google, Google for Developers Blog (2026) (opens in a new tab)
- LangChain, Docs by LangChain (2026) (opens in a new tab)