Agent surfaces cheat sheet
Which rung each generation belongs on, where state lives, and how the three platforms compare. Facts checked 2026-09-16 (updated the same day for the "agents own memory" assumption).
1 · The ladder and the climbing test
- Plain LLM callCode assembles the inputs, and one call returns a fixed shape.
- Workflow / ADK 2.0 graphCode fixes the order of steps; nodes are functions, LLM calls or agents.
- Agent with toolsThe model decides what to fetch next.
- Managed agent sessionA vendor hosts the loop, a sandbox and session state.
Climb only if the model must decide what to fetch mid-task · the job can wait · the gain is worth several times the tokens (~$0.01 plain vs ~$0.03–0.15 agent per Lesson).
2 · Where state lives (depends on your memory decision)
| Assumption | Rule |
|---|---|
| Original: generators never write memory; Postgres is the record | Session-per-job. The agent is stateless, reads Postgres through tools or a bundle, and returns fixed shapes. |
| Current (2026-09-16): agents may write memory; Postgres is only the harness | Session-per-Thread. /next or the morning run creates a session. Taps and Replies are new events. Threads are never closed (2026-09-17), so sessions stay resumable indefinitely, and memories are written incrementally after each turn or when a newer Thread starts. |
Harness test: keep it in Postgres if your code needs it deterministically (routing a Telegram update, the Topic's latest Lesson for progression taps, update_id dedup, jobs and runRef, the Topic in progress, the Backlog copy, spend). Session = the open Thread's transcript. Long-term memory = facts that outlast a Thread (what was hard, Notes, recaps).
2b · Memory services
| Memory Bank (Google Agent Platform) | Claude Managed Agents memory stores | |
|---|---|---|
| Model | LLM extraction plus consolidation; similarity retrieval by scope | Files the agent reads and writes in a mounted directory |
| Writes | From session events (add_session_to_memory), event ingestion, or direct CreateMemory | Agent file edits; API seeding |
| Audit | Revisions; TTL | Immutable versions; redact |
| ADK TS | VertexAiMemoryBankService (in the 2.1.0 package; docs show only Python); PreloadMemoryTool / LoadMemoryTool | n/a |
| Cost | $0.30/GiB-month storage; $0.085 per 3M reads or 1M writes; Gemini tokens billed separately (since 2026-09-01) | Part of the Managed Agents session costs |
| Catch | Needs a GCP project and an Agent Engine id; extraction runs on Gemini; memory-poisoning risk; psql readback lost | Claude only |
3 · Placement for this project
| Generation | Rung | Reason |
|---|---|---|
| Reply classify | Plain | ~2 s placeholder; fixed inputs |
| Exercise · Answer feedback · Topic recap | Plain | All inputs known |
| Follow-up (plain Instruction) | Plain | Thread context is already loaded |
| Follow-up that needs Project code | Agent (node) | The model picks which files to read |
| Lesson (select → write) | ADK graph + agent select node | Fixed order; exploration only in select |
| Project digest refresh | Managed agent | Sandbox with git; slow is fine; outside the Thread |
4 · Platforms
| ADK 2.0 TS | Claude Managed Agents | Gemini Antigravity | |
|---|---|---|---|
| Status | GA 2026-08-21 | Beta | Public preview |
| Hosting | You (Cloud Run) | Anthropic | |
| Models | Gemini; OpenRouter via custom BaseLlm | Claude only | Gemini 3.5–3.8 Flash only |
| OpenRouter-only rule | Kept | Broken | Broken |
| Output shape | zod outputSchema | Validate yourself | No structured outputs |
| Custom tools | In your process | agent.custom_tool_use → idle → user.custom_tool_result | requires_action → create with function_result |
| Long runs | Your request | SSE stream / webhooks | background: true + poll |
| State | TS 2.1: in-memory, Postgres (DatabaseSessionService), or Agent Platform sessions | Sessions + memory stores | previous_interaction_id; environments kept 7 days |
| Extra cost | Cloud Run (free tier likely) | $0.08 per active hour; budget cap per session | Sandbox compute free during preview |
5 · Seam contract (agent-ready)
generate(kind, jobId, bundle) → { done, result } | { pending, runRef }
collect(runRef) → { done, result } | { pending } | { failed }The 150 s Edge wall clock makes pending → collect mandatory for agent engines. Collect through a webhook (Claude Managed Agents, or a Cloud Run callback) or a pg_cron poll (Antigravity). For managed runs, mount the context bundle as files instead of custom tools: each custom-tool call is a round trip through your code.
Sources
Building effective agents · Why we built ADK 2.0 · ADK 2.0 · ADK graphs · ADK human input · ADK sessions · Claude Managed Agents · Gemini Managed Agents · Antigravity agent · Custom agents · Memory Bank · Memory Bank + ADK · adk-js source