AG-UI · ADK Basic Chat (Railway-ready)

A minimal AG-UI endpoint built on the Google ADK middleware. It serves a single chat agent:

• Model: gemini-2.5-flash
• Web search: Gemini-native Google Search grounding (no separate search API key)
• Memory: in-memory session + memory services with PreloadMemoryTool for recall of prior turns within the process lifetime

The AG-UI run endpoint is POST /; GET /healthz is a health probe and GET /capabilities reports agent capabilities.

Files

File	Purpose
main.py	FastAPI app + agent definition
requirements.txt	Python dependencies
railway.json	Railway build/deploy config (start command + health check)
Procfile	Start command fallback (Nixpacks/Heroku-style)
.python-version	Pins Python 3.12 for the Nixpacks builder
.env.example	Required environment variables

Run locally

cd railway-basic-chat
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env          # then put your real GOOGLE_API_KEY in .env
set -a && source .env && set +a

uvicorn main:app --host 0.0.0.0 --port 8000

Probe it:

curl localhost:8000/healthz          # {"status":"ok"}

Get a Gemini API key from https://aistudio.google.com/app/apikey.

Deploy to Railway

1. Create the project. Push this folder to a Git repo (or use the Railway CLI).

   • Dashboard: New Project → Deploy from GitHub repo, then set the service Root Directory to integrations/adk-middleware/python/railway-basic-chat if you deploy from the monorepo.
   • CLI:

     npm i -g @railway/cli
     railway login
     railway init
     railway up

2. Set environment variables (Service → Variables):

   Variable	Value
   GOOGLE_API_KEY	your Gemini API key
   GOOGLE_GENAI_USE_VERTEXAI	FALSE

   PORT is injected by Railway automatically — don't set it.

3. Deploy. Railway uses railway.json: it builds with Nixpacks (detecting requirements.txt + .python-version) and starts with uvicorn main:app --host 0.0.0.0 --port $PORT, health-checking /healthz.

4. Generate a public domain (Service → Settings → Networking → Generate Domain). Your AG-UI endpoint is then https://<your-app>.up.railway.app/.

Connect from an AG-UI client

Point an HttpAgent at the deployed URL (the root path):

import { HttpAgent } from "@ag-ui/client";

const agent = new HttpAgent({ url: "https://<your-app>.up.railway.app/" });

Notes & limits

• State is process-local. In-memory services lose all sessions/memory on restart or redeploy, and won't be shared across multiple replicas. For durable memory, swap in a persistent ADK memory/session service (e.g. Vertex AI) via ADKAgent(..., memory_service=..., session_service=...).
• Google Search + other tools. The built-in search tool is constructed with bypass_multi_tools_limit=True so it can run alongside PreloadMemoryTool; ADK wraps search as a sub-agent tool to satisfy Gemini's built-in-tool rules.
• Auth. This sample uses a single static user_id. For multi-user deployments, pass extract_state_from_request / a user_id_extractor to derive identity from the request.