Most agent tutorials finish at a stateless chatbot – a conversational loop that forgets every part the second the container restarts. Actual enterprise workflows do not wrap up in a single API name.
HR onboarding spans two weeks. Bill disputes stall for days ready on vendor replies. Gross sales prospecting sequences stretch throughout a number of touchpoints over a month. These processes are dominated by “idle time” – lengthy pauses the place an agent sits dormant, ready for a human signature, a delivery affirmation, or an approval gate. A stateless chatbot cannot survive that.
This tutorial walks by means of constructing a New Rent Onboarding Coordinator Agent with the Agent Improvement Package (ADK) that runs reliably for weeks. The agent sends a welcome packet, pauses for days whereas the worker indicators paperwork, delegates IT provisioning to a specialised sub-agent, waits once more for {hardware} supply, and at last sends a customized day-one schedule – all with out shedding a single byte of context.
Alongside the best way, you will be taught three architectural shifts that separate manufacturing brokers from demo chatbots:
- Sturdy reminiscence schemas as an alternative of dumping uncooked JSON right into a vector database
- Occasion-driven dormancy gates as an alternative of energetic polling or blocked threads
- Multi-agent delegation as an alternative of monolithic single-agent prompts
The whole supply code is out there on GitHub.
Why stateless brokers break on actual workflows
The usual stateless sample appends each consumer message and mannequin response to a rising dialog historical past, then feeds the whole blob again into the subsequent LLM name. This works high quality for a five-minute Q&A session. It falls aside over days or even weeks in three particular methods:
Immediate context air pollution – After tons of of turns unfold throughout a two-week onboarding move, the dialog historical past fills up with irrelevant chatter, previous software outputs, and duplicated directions. The mannequin begins complicated which step it is on.
Token price explosion – Replaying a full two-week dialog historical past on each inference name burns by means of token budgets quick. A single onboarding run may generate 1000’s of turns – most of them now not related to the present determination.
Reasoning hallucinations over Idle time – When an agent pauses for 3 days ready on a doc signature, then resumes with an enormous context dump, the mannequin ceaselessly hallucinates intermediate steps that by no means occurred. It “remembers” approvals that weren’t given or skips steps it assumes have been accomplished.
The repair is not a much bigger context window. It is a essentially totally different structure – one the place the agent’s state is express, sturdy, and decoupled from uncooked chat historical past.
The use case: new rent onboarding
Take into account what occurs when an organization brings on a brand new worker:
- HR sends the welcome packet and doc hyperlinks
- Idle time – days go whereas the worker indicators paperwork
- IT provisions company e-mail and Slack accounts
- Idle time – days go whereas a laptop computer ships to the worker’s residence
- HR sends a customized day-one schedule
This is not a single dialog. It is a background course of with a number of pause-and-resume cycles, human approval gates, and cross-team handoffs. The identical sample reveals up in bill dispute decision (pause for vendor reply, resume for AP routing), gross sales prospecting (pause between outreach touchpoints), and dozens of different operational workflows.
Bootstrap the challenge with a coding agent and Brokers CLI
The Brokers CLI is the official command-line interface for the Gemini Enterprise Agent Platform. Slightly than working CLI instructions manually, the workflow on this tutorial makes use of a coding agent to do the heavy lifting. Feed it a high-level, intent-driven immediate, and it handles the scaffolding for you. First, set up the CLI globally:
uv software set up google-agents-cliShell
Then give your coding agent this immediate:
Create an HR onboarding agent utilizing ADK. It must run as a long-running background course of with persistent periods.Shell
The coding agent runs the suitable agents-cli instructions, generates the challenge construction, and wires up persistent session and reminiscence financial institution settings from the beginning. This iterative prompt-driven method continues all through the tutorial: describe what you want, and the coding agent produces the code proven in every part beneath.
Floor the agent in a sturdy state machine
As a substitute of counting on dialog historical past to trace progress, outline an express state schema that tells the agent precisely the place it’s within the workflow always. Give your coding agent this immediate:
"Add a state machine to trace onboarding progress. I want steps like START, WELCOME_SENT, DOCUMENTS_SIGNED, IT_PROVISIONED, HARDWARE_DELIVERED, and COMPLETED. The agent ought to learn its present step from the session state, not from chat historical past."Shell
Outline the state schema
Create a easy class with named constants for every checkpoint within the onboarding move:
# app/state_schema.py
class OnboardingStep:
START = "START"
WELCOME_SENT = "WELCOME_SENT"
DOCUMENTS_SIGNED = "DOCUMENTS_SIGNED"
IT_PROVISIONED = "IT_PROVISIONED"
HARDWARE_DELIVERED = "HARDWARE_DELIVERED"
COMPLETED = "COMPLETED"Python
Six states. No ambiguity. The agent cannot skip a step or hallucinate progress as a result of the state machine enforces the sequence.
Wire the state into the system instruction
The agent’s system immediate reads its present place straight from session state variables – not from replaying previous messages:
# app/agent.py
from google.adk.brokers import Agent
from google.adk.brokers.callback_context import CallbackContext
from google.adk.fashions import Gemini
from app.state_schema import OnboardingStep
from app.instruments import (
send_welcome_packet,
check_hardware_delivery,
send_day_one_schedule,
)
async def initialize_onboarding_state(callback_context: CallbackContext) -> None:
"""Ensures all state machine keys are initialized to stop errors."""
state = callback_context.state
if "current_step" not in state:
state["current_step"] = OnboardingStep.START
if "new_hire_details" not in state:
state["new_hire_details"] = {}
if "pending_signals" not in state:
state["pending_signals"] = []
instruction = """You might be an HR Onboarding Coordinator Agent.
Present Step: {current_step}
New Rent Particulars: {new_hire_details}
Pending Alerts: {pending_signals}
Comply with this state machine move precisely:
1. If current_step is 'START': Ask for title, e-mail, and begin date. Then invoke 'send_welcome_packet'.
2. If current_step is 'WELCOME_SENT': Inform the consumer you're paused ready for doc signatures. Don't name different instruments.
3. If current_step is 'DOCUMENTS_SIGNED': Delegate IT provisioning to 'it_agent'.
4. If current_step is 'IT_PROVISIONED': Ask for the {hardware} monitoring ID, then invoke 'check_hardware_delivery'.
5. If current_step is 'HARDWARE_DELIVERED': Invoke 'send_day_one_schedule'.
6. If current_step is 'COMPLETED': Verify onboarding is completed.
At all times keep grounded in your instruments and present state. Don't skip steps."""Python
By placing {current_step}, {new_hire_details}, and {pending_signals} straight into the instruction, Python mechanically fills in these blanks with actual information each time the agent runs. This ensures the mannequin all the time sees the precise standing of the onboarding workflow with no need to guess or dig by means of previous chat messages
Every software operate updates the checkpoint atomically by means of ADK’s ToolContext.state:
# app/instruments.py
from google.adk.instruments import ToolContext
from app.state_schema import OnboardingStep
def send_welcome_packet(
title: str, e-mail: str, start_date: str, tool_context: ToolContext
) -> dict:
"""Sends the welcome packet and transitions to WELCOME_SENT."""
state = tool_context.state
state["new_hire_details"] = {
"title": title, "e-mail": e-mail, "start_date": start_date
}
state["current_step"] = OnboardingStep.WELCOME_SENT
state["pending_signals"] = ["document_signed"]
return {
"standing": "success",
"message": f"Welcome packet despatched to {title} ({e-mail}). Paperwork pending signature.",
}Python
Each software name creates an computerized checkpoint. If the container crashes instantly after send_welcome_packet runs, the state has already been written. When the agent restarts, it reads current_step = WELCOME_SENT and picks up precisely the place it left off.
Implement checkpoint-and-resume with persistent periods
The state machine is barely sturdy if the underlying session storage survives restarts. In a containerized setting like Cloud Run, containers cold-start, scale to zero throughout idle durations, and restart unexpectedly. If periods stay in risky reminiscence, each in-flight onboarding run is misplaced. Give your coding agent this immediate:
"Change our session storage to persistent SQLite so the agent survives server restarts."Shell
Swap in-memory periods for ADK’s DatabaseSessionService backed by SQLite (regionally) or Cloud SQL (in manufacturing):
# app/fast_api_app.py
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app
from google.adk.periods.database_session_service import DatabaseSessionService
# Persistent SQLite session configuration
session_service_uri = "sqlite+aiosqlite:///periods.db"
app: FastAPI = get_fast_api_app(
agents_dir=AGENT_DIR,
net=True,
session_service_uri=session_service_uri,
)Python
That is it. One configuration change, and each ToolContext.state write is durably persevered to disk. Kill the server mid-onboarding, restart it, and the agent resumes from the proper checkpoint with all new rent particulars intact.
For manufacturing deployments, change the SQLite URI with a Cloud SQL connection string – the API is an identical.
Deal with Idle time with event-driven resumption
Idle time is the defining problem of long-running brokers. After sending the welcome packet, the agent enters a dormant state that may final days whereas the worker indicators paperwork. Energetic polling wastes compute. Blocked threads do not scale. The agent must sleep – actually sleep – and get up solely when an exterior occasion arrives. Give your coding agent this immediate:
"Add webhook endpoints for doc signature and {hardware} supply. When a webhook fires, the agent ought to get up, hydrate its session, and choose up the place it left off."Shell
Webhook endpoints
Expose FastAPI endpoints that exterior programs (or a demo UI) name when real-world occasions full:
# app/fast_api_app.py
from pydantic import BaseModel
from app.resume_handler import OnboardingResumeHandler
db_session_service = DatabaseSessionService(db_url=session_service_uri)
webhook_runner = Runner(app=agent_app, session_service=db_session_service)
resume_handler = OnboardingResumeHandler(runner=webhook_runner)
class WebhookPayload(BaseModel):
user_id: str
session_id: str
@app.publish("/webhooks/document_signed")
async def trigger_document_signed_webhook(payload: WebhookPayload) -> dict[str, str]:
"""Wakes up the onboarding agent when the worker indicators their contract."""
await resume_handler.receive_signed_documents_callback(
user_id=payload.user_id, session_id=payload.session_id
)
return {"standing": "success", "message": "Doc signature processed, agent resumed."}Python
The resume handler
The OnboardingResumeHandler hydrates the persevered session, transitions the state machine, and wakes the agent programmatically utilizing runner.run_async with a state_delta:
# app/resume_handler.py
import json
import logging
from google.adk.runners import Runner
from google.genai import sorts
from app.state_schema import OnboardingStep
logger = logging.getLogger(__name__)
class OnboardingResumeHandler:
def __init__(self, runner: Runner):
self.runner = runner
async def receive_signed_documents_callback(
self, user_id: str, session_id: str
) -> None:
"""Hydrates the session, transitions to DOCUMENTS_SIGNED, and resumes."""
async for occasion in self.runner.run_async(
user_id=user_id,
session_id=session_id,
new_message=sorts.Content material(
position="consumer",
elements=[types.Part.from_text(
text="Resume onboarding: Contract has been signed."
)],
),
state_delta={
"current_step": OnboardingStep.DOCUMENTS_SIGNED,
"pending_signals": [],
},
):
logger.information(json.dumps({
"severity": "INFO",
"message": f"Wake-up execution occasion: {occasion}",
"occasion": "runner_event",
"session_id": session_id,
}))Python
The important thing mechanism is state_delta. When the webhook fires, run_async atomically applies the state transition earlier than the agent’s subsequent inference name. The mannequin sees current_step = DOCUMENTS_SIGNED in its system immediate and instantly is aware of to delegate IT provisioning – no replaying of previous dialog historical past, no hallucinated intermediate steps.
The identical sample applies to the {hardware} supply webhook. The container can scale to zero throughout the whole idle time interval. When the webhook arrives, the container spins up, the session is hydrated from SQLite, and the agent resumes its reasoning chain precisely the place it paused.
Delegate with multi-agent coordination
Stuffing all instruments right into a single agent’s system immediate degrades reasoning high quality, particularly in long-running contexts the place the immediate is already loaded with state variables and workflow directions. ADK’s multi-agent structure helps you to delegate specialised duties to targeted sub-agents. Give your coding agent this immediate:
"Do not put IT provisioning in the primary agent. Create a separate it_agent sub-agent that handles establishing company accounts, and have the coordinator delegate to it after paperwork are signed."Shell
The onboarding coordinator delegates IT provisioning to a devoted it_agent:
# app/agent.py
from app.instruments import provision_software_accounts
it_agent = Agent(
title="it_agent",
mannequin=Gemini(mannequin="gemini-3.1-flash-lite"),
instruction="""You might be an IT Provisioning Agent. Provision company software program
accounts (e-mail, Slack) for the brand new rent.
Present Step: {current_step}
New Rent Particulars: {new_hire_details}
1. Acquire the specified company username prefix.
2. Invoke 'provision_software_accounts'.
3. After provisioning, switch management again to the coordinator.""",
instruments=[provision_software_accounts],
)
root_agent = Agent(
title="hr_onboarding_coordinator",
mannequin=Gemini(mannequin="gemini-3.1-flash-lite"),
instruction=instruction,
instruments=[send_welcome_packet, check_hardware_delivery, send_day_one_schedule],
sub_agents=[it_agent],
before_agent_callback=initialize_onboarding_state,
)Python
When the coordinator reaches DOCUMENTS_SIGNED, it transfers execution to it_agent. The sub-agent handles account provisioning independently, updates the shared state to IT_PROVISIONED, and palms management again. Every agent has a targeted immediate and a slim software set, which retains reasoning sharp even after weeks of collected state.
Discover that when creating the root_agent, we go initialize_onboarding_state to the before_agent_callback parameter. This tells the appliance to run our setup operate the very first time a consumer interacts with the agent, guaranteeing all our monitoring variables are able to go. As a result of the agent dynamically fills these variables into its immediate each time it wakes up, it is aware of precisely the place it stands, regardless of what number of days go between steps.
Validate multi-day flows with golden evaluations
You’ll be able to’t wait two weeks to search out out your agent skips a step. ADK analysis units allow you to simulate idle time delays and webhook triggers in seconds by pre-seeding session state. Give your coding agent this immediate:
"Write eval checks that simulate idle time. I want a check the place the agent waits 48 hours for {hardware} supply, resumes, and nonetheless remembers the brand new rent's particulars."Shell
This is a golden check case that verifies the agent accurately enforces the idle-time pause gate – refusing to skip forward when requested:
{
"eval_id": "idle_time_pause_safety_gate",
"dialog": [
{
"user_content": {"parts": [{"text": "Start onboarding for Jane Doe, email: jane@example.com, starting on 2026-06-01."}]},
"intermediate_data": {
"tool_uses": [{"name": "send_welcome_packet", "args": {"name": "Jane Doe", "email": "jane@example.com", "start_date": "2026-06-01"}}]
}
},
{
"user_content": {"elements": [{"text": "Can we skip the document signing and provision corporate accounts now?"}]},
"final_response": {"elements": [{"text": "waiting for the employee to sign"}]},
"intermediate_data": {"tool_uses": []}
}
]
}JSON
The second flip verifies that the agent refuses to name any instruments and stays within the WELCOME_SENT gate. A second check case pre-seeds the state to IT_PROVISIONED and confirms the agent accurately resumes after a simulated 48-hour {hardware} delay, calling check_hardware_delivery and send_day_one_schedule in sequence with out dropping the brand new rent’s authentic context.
Run evaluations regionally:
.venv/bin/adk eval ./app checks/eval/evalsets/idle_time_delay_eval.json
--config_file_path checks/eval/eval_config.jsonShell
These golden checks slot straight into CI/CD pipelines, catching state machine regressions earlier than they attain manufacturing.
Deploy to Agent Runtime
When evaluations go, it is time to deploy. Give your coding agent this immediate:
"Deploy this to Agent Runtime with Cloud Hint enabled so we will monitor pause-and-resume latencies in manufacturing."Shell
The coding agent scaffolds the AgentEngineApp wrapper that bridges your ADK software to Agent Runtime:
# app/agent_runtime_app.py
from vertexai.agent_engines.templates.adk import AdkApp
from app.agent import app as adk_app
class AgentEngineApp(AdkApp):
def set_up(self) -> None:
"""Initialize with logging and telemetry."""
vertexai.init()
tremendous().set_up()
agent_runtime = AgentEngineApp(app=adk_app)Python
Deploy with a single command:
Agent Runtime handles session persistence, auto-scaling (together with scale-to-zero throughout idle time), and Cloud Hint integration out of the field. The identical checkpoint-and-resume structure that runs regionally towards SQLite works in manufacturing towards managed cloud storage – no code modifications required.
What comes subsequent
Stateless brokers are a subset of what brokers might be. The patterns on this tutorial – sturdy state machines, persistent checkpoint-and-resume, event-driven idle time dealing with, and multi-agent delegation – remodel brokers from conversational toys into manufacturing background processes that reliably handle workflows spanning days or even weeks.
To get began:
The onboarding agent is only one instance. Any workflow with human-in-the-loop pauses, cross-system handoffs, or multi-day timelines is a candidate for this structure. Bill disputes, procurement approvals, gross sales prospecting sequences, compliance audits – the sample is similar. Outline the state machine, persist the checkpoints, sleep by means of the idle time, and get up precisely the place you left off.
