Session 3 assignment support: Turn your capstone into an agent

Async

Session 3 assignment support: Turn your capstone into an agent

1. Start here: what this assignment is

This guide has two paths. Path A is the basic agent submission: enough to pass. Do that first. Path B is stretch goals: pick one or two only if you have time and energy.

You already have a Session 1 `/ask` service and (ideally) Session 2 RAG. Session 3 turns that assistant into an agent: it plans, calls at least one real tool, observes the result, and decides again - not a one-shot answer.

Ready when

Default stack: Google ADK

Build Path A in Google ADK (matches the Week 3 live session). LangGraph (or a clearly traced raw-SDK loop) is an accepted alternative if you already started there or your coach agrees - same bar: multi-step task, real tool, Think → Act → Observe proof.

Tip

Start from the sample repos (clone these)

Preferred - ADK demos: adk-multi-agent-systems - routing, MCP, full system + Streamlit. Accepted alt - LangGraph twin: langgraph-multi-agent-systems - same three demos, different framework. Fork/clone, run Demo 1 first, then adapt patterns into your capstone job. Do not submit an unchanged demo as your homework.

Tip

Session resources

Live patterns: Week 3 session deck. Primary: Google ADK docs · ADK agents · ADK MCP tools. Alternative: LangGraph overview · quickstart.

Critical

The Golden Rule (read this first)

Whenever anything goes wrong, copy the entire error message and paste it into Claude Code or Cursor with: "I got this error, please fix it and explain what happened in simple terms."

That habit fixes most problems.
You are never stuck. You just haven't pasted the error yet.

Basic agent submission: what counts

Basic submission: enough to pass

Extend your capstone (Session 1/2 service) when it helps. A focused ADK agent project is fine if wiring into FastAPI is painful this week.
Ship a Google ADK agent (preferred) - or LangGraph / clearly traced raw-SDK - that completes a multi-step task.
At least one real tool runs (HTTP, DB, calendar, search, Sheets, MCP server, your own API - not a fake stub that returns hardcoded text).
You can show Think → Act → Observe for one run (ADK run logs, console, or a short Loom).
One-liner: why this is an agent (or a fixed workflow) and why that choice is right.

2. Before you build: pick the job

Write one sentence: When [user ask / trigger], the agent should [outcome] using [tool(s)]. If you cannot write that sentence, the job is still too vague.

Capstone FAQ bot → agent that searches your docs (reuse Session 2 retrieval as a tool) then answers with citations.
Ops helper → agent that looks up a row (Sheets / DB) then drafts a status reply.
Research helper → agent that calls an HTTP API (weather, GitHub, Notion, etc.) then summarises.
Support triage → agent that classifies the request then routes to a specialist tool or reply template.

Critical

Agent vs workflow - choose on purpose

If every run always does A → B → C with no model choice, that is a workflow. An agent is right when the next step depends on a tool result you cannot hard-code. Use the simplest shape that does the job.

Preflight: what you need

ADK sample repo

Start here

Clone adk-multi-agent-systems. Read the README, copy `.env.example` → `.env`, run Demo 1 before inventing your own graph.

Google AI / Gemini access

ADK

ADK is built around Gemini. Get an API key from Google AI Studio (or Vertex if you already use GCP). Keep spend limits tight.

Your Session 1/2 repo (optional base)

Reuse helpers (retrieval, DB) as tools when you can. If ADK is cleaner as a sibling package this week, keep `/ask` working and call shared tools from both.

One real tool target

HTTP API, Sheet, Pinecone/Chroma from Session 2, a DB table, or an MCP server. Fake tools do not count for Path A.

Claude Code or Cursor

You will paste prompts below. Keep one coding agent working before you change architecture.

3. Path A: Basic Google ADK agent (preferred)

Do these steps first. When the basic checklist is done, you have passed. Stop there if you are tired.

Step 0: Clone and run the ADK sample

Open adk-multi-agent-systems.
Clone or fork → create a venv (Python 3.12+) → `pip install -e .` (or `uv pip install -e .`).
Copy `.env.example` to `.env` and set `GOOGLE_API_KEY`.
Run Demo 1 (`python demo1_routing.py`) so you see router → specialists with local tools.
Optional: Demo 2 (MCP + Supabase) and Demo 3 (MCP + A2A) once Demo 1 works - they map to stretch goals.

PROMPT 0: Orient on the ADK sample repo

I cloned https://github.com/akshika47/AI-Internship/tree/main/ai-engineering-bootcamp/adk-multi-agent-systems for my Session 3 assignment.

Please read the README and Demo 1 code and explain in plain English:
1. What Demo 1 / Demo 2 / Demo 3 each prove (routing, MCP, A2A)
2. Where the router and specialist agents are defined
3. How tools are attached in ADK in this repo
4. The smallest change I should make to adapt Demo 1 to MY capstone job (one sentence job: …)

Do not rewrite the whole demo yet - map it first.

Step 1: Orient on your codebase + ADK

PROMPT 1: Map the project for an ADK agent

I am building a Session 3 agent assignment with **Google ADK** (preferred stack) + at least one real tool. I have the sample repo at ai-engineering-bootcamp/adk-multi-agent-systems and my Session 1/2 FastAPI capstone.

Please read both and explain in plain English:
1. Where POST /ask (and /ingest if present) live in my capstone
2. What helpers I can reuse as ADK tools (retrieval, DB, external APIs)
3. Whether I should adapt the sample demos in-place or add a sibling ADK entrypoint in my capstone
4. What env vars I need for Gemini / ADK vs what I already have

Do not write code yet - just map the project and propose the smallest agent job that fits.

Step 2: Stand up a minimal ADK agent

PROMPT 2: Minimal ADK agent

Using patterns from the ADK sample (Demo 1), add a minimal Google ADK agent for ONE multi-step job tied to my capstone.

Requirements:
- One root agent with a clear name, model, and instruction (goal, constraints, what "done" looks like)
- At least a placeholder for tools (we will wire a real tool next)
- Max-iteration / step limit so the loop cannot run forever
- Clear logging of Think / Act / Observe (or ADK's equivalent event stream)
- How to run it locally (same style as the sample demos, `adk web`, or a small Python entrypoint)

Explain the agent in 5 bullets a beginner can repeat. Do not add multi-agent yet unless my job truly needs a router. Point me at the sample files you copied patterns from.

Critical

Always bound the loop

Cap steps / iterations (for example 8 - 12). Unbounded agents burn tokens and money. Fail closed when the cap is hit.

Tip

ADK docs to keep open

ADK docs home · Agents · Tools · MCP tools.

Step 3: Wire one real tool

PROMPT 3: First real ADK tool

Add exactly ONE real tool to my Google ADK agent.

Preferred options (pick the best fit for this repo):
1. Reuse Session 2 retrieval as a FunctionTool / custom tool (search_docs)
2. HTTP request to a public API I choose
3. Read/write one Google Sheet or local SQLite/Postgres table I already have
4. One MCP-backed tool via ADK's MCP integration (if that is cleaner for my job)

Requirements:
- Clear tool name + description so the model knows when to call it
- Real side effect or real data returned (no hardcoded fake success)
- Tool errors returned as observations the model can see
- A run command that triggers a task where the tool is actually called

After implementing, show me one successful execution log with Think → Act → Observe labeled (map ADK events to those three words if needed).

Step 4: Prove the loop

Run one task that must call the tool (not answerable from memory alone).
Save the ADK run log or record a 30 - 60s Loom walking Think → Act → Observe.
Write your one-liner: "This is an agent because …" or "This is a workflow because …".
Name the stack in one word: ADK (or LangGraph / raw if you used the alternative).

Ready when

What success looks like

The model proposes a tool call (Think).
Your tool runs and returns a real result (Act / Observe).
The model uses that result in a final answer (or another tool call).
You can show that sequence to the cohort without pasting secrets.

Step 5: Optional HTTP entrypoint

A localhost ADK demo (`adk web` / CLI) with a clear Loom is enough if your coach accepts it. Prefer exposing `POST /agent` on the same Render service as Session 1/2 when you can.

PROMPT 4: Expose POST /agent (optional)

Add POST /agent to this FastAPI app that invokes my Google ADK agent.

Requirements:
- Accept a user goal / message as JSON
- Return final answer plus a short steps[] array (tool names + truncated observations)
- Never return API keys or full env
- Include a curl example for local and for my Render URL

Keep Session 1 /ask working.

3b. Accepted alternative: LangGraph (or raw SDK)

Use this only if you already committed to LangGraph, or ADK setup is blocked and your coach agrees. The bar is identical: multi-step task, real tool, bounded loop, Think → Act → Observe proof.

Tip

LangGraph sample twin

Same demos as ADK, different framework: langgraph-multi-agent-systems. Clone it, copy env from the ADK folder if needed (`cp ../adk-multi-agent-systems/.env .env`), run Demo 1, then adapt - do not submit the stock demo unchanged.

ALT PROMPT: Minimal LangGraph agent

I am using the LangGraph alternative for Session 3. Sample repo: https://github.com/akshika47/AI-Internship/tree/main/ai-engineering-bootcamp/langgraph-multi-agent-systems

Add a minimal LangGraph StateGraph for ONE multi-step job tied to my capstone, using patterns from Demo 1.

Requirements:
- Typed state with messages
- Model / supervisor node + tools (or specialist) nodes + conditional edges / Command routing as in the sample
- Max-iteration / recursion limit
- Log Think / Act / Observe clearly
- Exactly ONE real tool first (reuse Session 2 retrieval, HTTP, or DB)

Explain the graph in 5 bullets and name which sample files you copied from. Do not add multi-agent unless the job needs it.

4. Stop point: basic submission is done

Ready when

Stop here if you need to

If you have an ADK agent (or accepted LangGraph / raw alternative), one real tool, a multi-step run you can show, and a one-liner on agent vs workflow, the basic Session 3 submission is done.

Before you move to stretch, confirm this

Stack named: ADK (preferred) or LangGraph / raw (accepted).
Multi-step task completes with at least one real tool call.
Think → Act → Observe visible in logs or a short clip.
Loop is bounded (max iterations / step limit).
One-liner explains agent vs workflow for this job.
No secrets in screenshots, Loom, or Maven posts.

5. Path B: Stretch goals (optional)

Human-in-the-loop

Recommended

Pause before one consequential action (send email, write DB, spend money). Resume only after approve.

Multi-agent or A2A (ADK)

ADK

ADK multi-agent or A2A only if roles are truly separable. A vague "research team" of five agents does not help.

MCP-backed tool

Call one capability via MCP (ADK MCP tools is the natural fit after the live session).

LangGraph mirror

If you shipped ADK for Path A, optionally rebuild the same job once in LangGraph to feel the second stack.

Prompt-injection drill

Feed a malicious doc/instruction and show how your allowlist, HITL, or tool policy blocked it.

ADD-ON PROMPT: Pick one stretch

I have completed the basic Session 3 agent assignment on Google ADK (or LangGraph). Help me choose ONE stretch based on my current code:
1. Human-in-the-loop before a consequential tool
2. ADK multi-agent / router / A2A (only if roles separate)
3. One MCP-backed tool
4. Mirror the same job in LangGraph (if I used ADK) or ADK (if I used LangGraph)
5. Prompt-injection test case + defense

Recommend the most useful one for my capstone, explain why, then implement it in small steps with a simple before/after demo.

6. Share + troubleshoot

Critical

Do NOT paste secrets or burnable URLs carelessly

Maven / WhatsApp: short clip or screenshots of the loop, link or export of the agent/code, stack used (ADK / LangGraph / raw), and which stretch items you hit. Never paste API keys. If you expose a live /agent URL, treat it like Session 1 - do not post it on LinkedIn.

Basic agent submission checklist

Google ADK agent (preferred) - or LangGraph / traced raw - completes a multi-step task.
At least one real tool runs in your code.
Think → Act → Observe shown in logs or Loom.
One-liner: agent vs workflow and why.
Submitted proof in Maven / WhatsApp without secrets.

Optional stretch

HITL before a consequential action.
ADK multi-agent / A2A only when roles separate cleanly.
MCP tool wired through ADK (or equivalent).
Second-stack mirror (LangGraph ↔ ADK).
Prompt-injection test case with a documented defense.

Troubleshooting

Gemini / ADK auth errors - confirm `GOOGLE_API_KEY` (or Vertex creds) in env; never commit the key; restart the shell after setting it.
Model never calls the tool - tighten the tool description and the user task so the answer is impossible without the tool.
Infinite loop / huge bills - lower step / recursion limit; log every step; fail closed at the cap.
Tool errors crash the run - return errors as observations; do not raise uncaught exceptions out of the tool.
"Multi-agent" that does nothing better - collapse to one agent + tools until roles force a split.
ADK feels magical - rebuild the same job once as a raw SDK while-loop, then map events to Think / Act / Observe.
Stuck on ADK install - use the LangGraph alternative path with coach OK; same proof bar.
Deploy breaks on new deps - paste the Render build log into your coding agent; pin versions in requirements.txt.

Go deeper (optional)