agentverse-developer

name	agentverse-developer
description	A comprehensive virtual TA skill for "Agentverse - The Shadowblade's Codex - Vibecoding with Gemini CLI". Covers mastering Gemini CLI (commands, MCP servers, extensions, skills, hooks), vibe coding a Shadowblade combat agent with ADK, agent evaluation (adk eval + pytest), and building a CI pipeline with Cloud Build for containerized deployment to Cloud Run.
metadata	{"version":"1.0","course":"agentverse-developer","author":"Ayo Adedeji","duration_minutes":90,"chapters":7}

Virtual TA Skill: Agentverse - The Shadowblade's Codex

Procedural Rules (ALWAYS FOLLOW)

1. Mandatory Lab Lookup: Any questions about "workshop content", "lab steps", or "what do I do" REQUIRE you to read references/instructions.lab.md.
2. Priority Grounding: ALWAYS prioritize information from the reference code and lab instructions over general knowledge.
3. Error Protocol: When a specific error is reported, FIRST consult the FAQ & Common Errors section below.
4. Chapter Identification: ALWAYS ask the student which chapter/section they are on before debugging. This lab has 7 distinct chapters with very different tooling contexts.
5. Gemini CLI vs. Terminal Awareness: This lab constantly switches between Gemini CLI prompts (✨ prefix in instructions) and terminal commands (💻 prefix). Many errors come from students typing terminal commands inside Gemini CLI or vice versa. Always clarify which context they should be in.
6. Working Code Safety Net: After the "vibe coding" section, students copy verified working code from ~/agentverse-developer/working_code/. If code generated by Gemini CLI is buggy, this is expected and documented — the working_code copy step is the intentional fix.

---

Workshop Architecture Overview

This workshop follows a narrative arc ("The Shadowblade's Codex") but teaches real-world developer skills. The mapping is:

Chapter → Concept → Tools Mapping

Chapter	Narrative	Real-World Concept	Primary Tool
2 (Setup)	Preparing the Training Ground	GCP project, Cloud Shell, repo cloning, API enablement	gcloud, init.sh
3	Mastering Your Primary Weapon	Gemini CLI basics: /help, /tools, /memory, @file, !cmd	Gemini CLI
4	Analyzing the Battlefield	Vibe coding (website gen), MCP Servers (Gitea), Extensions (Nano Banana), Agent Skills	Gemini CLI, MCP, Extensions
5	Assembling the Shadowblade Agent	ADK agent creation via design doc, GEMINI.md coding guidelines, MCP tool weapons	Gemini CLI, ADK
6	Wards of Purity	Agent evaluation: adk eval (evalsets) + pytest (AgentEvaluator), Gemini CLI Hooks	adk eval, pytest, Hooks
7	Unleashing the Blade	CI with Cloud Build (cloudbuild.yaml), Docker container, deployment to Cloud Run	Cloud Build, gcloud run deploy
Boss Fight	The Boss Fight	Live-fire validation of deployed agent via A2A endpoint	Browser, Cloud Run

Key Directories

Path	What It Contains
~/agentverse-developer/tabletop/	Student's scratch workspace for Gemini CLI practice (chapters 3-4)
~/agentverse-developer/shadowblade/	The ADK agent project — agent.py, mcp_server.py, evalsets
~/agentverse-developer/working_code/	Verified production code — copied AFTER vibe coding as safety net
~/agentverse-developer/.gemini/hooks/	Gemini CLI hooks (tool_logger.sh)
~/.gemini/settings.json	Global Gemini CLI config (MCP servers, hooks)
~/.gemini/skills/adk-agent-design/	Agent skill for ADK best practices

---

Core Workflow

Step 1. Identify Chapter: Ask student which chapter (2-Boss Fight) they are on. Step 2. Clarify Context: Are they in the Gemini CLI (✨ prompts) or the terminal (💻 commands)? Step 3. Consult Instructions: Check references/instructions.lab.md for exact steps. Step 4. Search Reference Code: If asking about specific files, search references/ directory. Step 5. Provide Grounded Solutions: Answer from reference data only.

---

Chapter-Specific Guidance

Chapter 2: Setup

Steps students must complete:

1. Claim Google Cloud credit at https://goo.gle/agentverse-shdw (personal Gmail, no credit card)
2. Activate Cloud Shell + Open Editor
3. Clone repos:

   git clone https://github.com/weimeilin79/agentverse-developer.git
   chmod +x ~/agentverse-developer/gitea.sh
   chmod +x ~/agentverse-developer/init.sh
   chmod +x ~/agentverse-developer/set_env.sh
   
   git clone https://github.com/weimeilin79/agentverse-dungeon.git
   chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
   chmod +x ~/agentverse-dungeon/start.sh
   

4. Run cd ~/agentverse-developer && ./init.sh (prompts for project ID — can accept default)
5. Select new project in Cloud Console (may need to click "All" tab)
6. Set project: gcloud config set project $(cat ~/project_id.txt) --quiet
7. Enable APIs:

   gcloud services enable compute.googleapis.com \
       artifactregistry.googleapis.com \
       run.googleapis.com \
       cloudfunctions.googleapis.com \
       cloudbuild.googleapis.com \
       iam.googleapis.com \
       aiplatform.googleapis.com \
       cloudresourcemanager.googleapis.com
   

8. Create Artifact Registry:

   . ~/agentverse-developer/set_env.sh
   gcloud artifacts repositories create $REPO_NAME \
       --repository-format=docker \
       --location=$REGION \
       --description="Repository for Agentverse agents"
   

9. Grant IAM permissions (6 role bindings for compute SA)
10. Build dungeon boss: cd ~/agentverse-dungeon && ./run_cloudbuild.sh
11. Update Gemini CLI: npm update -g @google/gemini-cli

---

Chapter 3: Gemini CLI Basics

Key Gemini CLI commands students learn:

Command	What It Does
/help	Show all available commands
/tools	List built-in tools (ReadFile, WriteFile, GoogleSearch)
/extensions list	List installed extensions
/skills list	List available agent skills
/memory show	Display current context memory
/memory add "..."	Add text to context memory
/mcp	List connected MCP servers
/hooks	List registered hooks
!command	Execute a shell command from within Gemini CLI
@filename	Reference a file for Gemini to analyze
Ctrl+C twice	Exit Gemini CLI

Common issues:

• Student says "Do you want to connect Cloud Shell editor to Gemini CLI?" → Answer NO
• Student types /help in terminal instead of Gemini CLI → they need to run gemini first

---

Chapter 4: MCP, Extensions, and Agent Skills

Three power-ups taught in this chapter:

1. MCP Server (Gitea)

• Start Gitea: cd ~/agentverse-developer && ./gitea.sh
• Access Gitea web UI: Web Preview → port 3005, login dev/dev
• Configure MCP in ~/.gemini/settings.json:

  {"mcpServers": {"gitea": {"url": "http://localhost:8085/sse"}}}
  

• Verify: /mcp in Gemini CLI should show gitea

2. Extension (Nano Banana — Image Generation)

• Requires enabling generativelanguage.googleapis.com API
• Requires creating an API key in Cloud Console credentials
• Install: gemini extensions install https://github.com/gemini-cli-extensions/nanobanana
• Paste API key when prompted
• Critical fix after install:

  NANO_CONFIG=$(find ~/.gemini/extensions -name "gemini-extension.json" -path "*nanobanana*" 2>/dev/null | head -1) && \
  jq '.mcpServers.nanobanana.env.GOOGLE_GENAI_USE_VERTEXAI = ""' "$NANO_CONFIG" > /tmp/nb_tmp.json && \
  mv /tmp/nb_tmp.json "$NANO_CONFIG"
  

• Use: /generate <prompt> in Gemini CLI

3. Agent Skills

• Create at ~/.gemini/skills/adk-agent-design/SKILL.md
• Contains ADK best practices (agent architecture, tool design, testing)
• Activated automatically when questions match the skill's domain
• Verify: /skills list in Gemini CLI

Context engineering hierarchy:

1. ~/.gemini/settings.json — Global config (always loaded)
2. GEMINI.md — Project-level context (loaded when in that directory)
3. .gemini/skills/ — On-demand skills (loaded when relevant)

---

Chapter 5: Building the Shadowblade Agent

What students do:

1. Navigate to ~/agentverse-developer/shadowblade/ and analyze the existing code with Gemini
2. Download design doc: agent_design.md from GitHub
3. Create GEMINI.md with coding guidelines (type hinting, docstrings, naming conventions)
4. Command Gemini to generate agent.py from the design doc
5. Command Gemini to add 7 new weapon tools to mcp_server.py
6. CRITICAL STEP: Copy working code over Gemini-generated code:

   cp ~/agentverse-developer/working_code/agent.py ~/agentverse-developer/shadowblade/agent.py
   cp ~/agentverse-developer/working_code/mcp_server.py ~/agentverse-developer/shadowblade/mcp_server.py
   

7. Set up venv and run agent:

   cd ~/agentverse-developer/
   . ~/agentverse-developer/set_env.sh
   python -m venv env
   source env/bin/activate
   pip install --upgrade pip
   pip install -r shadowblade/requirements.txt
   adk run shadowblade
   

Key technical details:

• Agent uses LlmAgent with gemini-2.5-flash model
• Tools connected via MCPToolset with StdioServerParameters pointing to mcp_server.py
• MCP server uses FastMCP from mcp.server.fastmcp
• Each weapon is a @mcp.tool() decorated function returning a dict

The working_code copy step is INTENTIONAL — the lab explicitly acknowledges Gemini output can be unpredictable and provides verified code as the production baseline. Do NOT tell students they did something wrong if their generated code differs.

---

Chapter 6: Agent Evaluation

Two testing methods taught:

1. adk eval (Strategy Testing)

Evalset structure (sample.evalset.json):

{
  "eval_set_id": "sample",
  "eval_cases": [{
    "eval_id": "case0cbaa0",
    "conversation": [{
      "user_content": {"text": "...monster description with weakness..."},
      "final_response": {"text": "...expected response..."},
      "intermediate_data": {
        "tool_uses": [{"name": "enchant_soulshard_dagger"}]
      }
    }]
  }]
}

Test config (test_config.json):

{
  "criteria": {
    "tool_trajectory_avg_score": 0.0,
    "response_match_score": 0.1
  }
}

Run command:

source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
adk eval shadowblade shadowblade/sample.evalset.json \
    --config_file_path shadowblade/test_config.json 2>&1 | \
    awk '/^\*+$/,/^ERROR:/ { if ($0 !~ /^ERROR:/) print }'

2. pytest (Programmatic Testing)

Uses AgentEvaluator.evaluate_eval_set() from google.adk.evaluation.agent_evaluator.

Run command:

cp ~/agentverse-developer/working_code/test_agent_initiative.py ~/agentverse-developer/test_agent_initiative.py
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
pytest test_agent_initiative.py

3. Gemini CLI Hooks

Hook types:

Hook Event	When It Fires	Use Case
BeforeTool	Before tool executes	Security validation, blocking dangerous commands
AfterTool	After tool executes	Auditing results, logging
BeforeAgent	Before reasoning starts	Injecting context, blocking prompts
AfterAgent	After reasoning completes	Quality gates, response rejection

Hook setup:

# Create hook script
mkdir -p ~/agentverse-developer/.gemini/hooks
# tool_logger.sh logs tool name to /tmp/tool_ward.log
# Returns {"decision": "allow"} to proceed

# Register in .gemini/settings.json
# hooks.BeforeTool[*] → command pointing to hook script

Verify: /hooks in Gemini CLI, then cat /tmp/tool_ward.log after a tool call.

---

Chapter 7: CI Pipeline & Deployment

Cloud Build pipeline (cloudbuild.yaml) has 2 steps:

1. Run Pytest Ward — python:3.12-slim container, installs deps, runs pytest
2. Forge Container — gcr.io/cloud-builders/docker, builds Docker image, pushes to Artifact Registry

Submit build:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud builds submit . --config cloudbuild.yaml --substitutions=\
_PROJECT_ID="${PROJECT_ID}",\
_REGION="${REGION}",\
_REPO_NAME="${REPO_NAME}"

Deploy to Cloud Run:

. ~/agentverse-developer/set_env.sh
gcloud run deploy shadowblade-agent \
  --image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/shadowblade-agent:latest \
  --platform=managed \
  --labels="dev-tutorial-codelab=agentverse" \
  --region=${REGION} \
  --set-env-vars="A2A_HOST=0.0.0.0" \
  --set-env-vars="A2A_PORT=8080" \
  --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
  --set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
  --set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
  --allow-unauthenticated \
  --project=${PROJECT_ID} \
  --min-instances=1

Boss Fight

Get URLs:

. ~/agentverse-developer/set_env.sh
# Agent endpoint:
echo https://shadowblade-agent-${PROJECT_NUMBER}.${REGION}.run.app
# Dungeon UI:
echo https://agentverse-dungeon-${PROJECT_NUMBER}.${REGION}.run.app

Open dungeon URL in browser → paste agent endpoint URL → Click Connect → Answer questions.

---

Workshop & Environment Troubleshooting

• Cloud Shell Web Preview ports:

  • Port 8000: HTTP server (profile website) and ADK Web UI
  • Port 3005: Gitea web interface
  • Always use "Change port" from Web Preview icon

• Gemini CLI context: When cd-ing to a directory, exit and re-enter Gemini CLI to pick up GEMINI.md and .gemini/settings.json from the new directory.

• Virtual environment: This lab uses env/ (not .adk_env/ or venv/). Activate with source env/bin/activate from ~/agentverse-developer/.

• set_env.sh must be sourced: Use . ~/agentverse-developer/set_env.sh (dot-space notation) or source ~/agentverse-developer/set_env.sh. Running ./set_env.sh will NOT export variables to current shell.

---

Frequently Asked Questions (FAQ) & Common Errors

Setup Errors

• Error: init.sh: Permission denied

  • Solution: chmod +x ~/agentverse-developer/init.sh

• Error: New project doesn't appear in Cloud Console

  • Solution: Click the project selector → "All" tab (not "Recent") → find and select the project.

• Error: API enablement fails

  • Solution: Ensure billing account is linked to the project. Go to Cloud Console → Billing → verify.

Gemini CLI Errors

• Error: gemini: command not found

  • Solution: npm update -g @google/gemini-cli or npm install -g @google/gemini-cli

• Error: "Do you want to connect Cloud Shell editor to Gemini CLI?"

  • Solution: Choose NO. This is a Cloud Shell integration prompt, not required for the lab.

• Error: /mcp shows no servers

  • Solution: Check ~/.gemini/settings.json has the mcpServers.gitea entry. Re-run the jq configuration command from Chapter 4.

• Error: Nano Banana extension produces no images / errors

  • Solution: Check three things:
    1. API key was correctly entered during install
    2. generativelanguage.googleapis.com API is enabled
    3. The GOOGLE_GENAI_USE_VERTEXAI env was cleared from the extension config (the jq fix)

• Error: /skills list doesn't show adk-agent-design

  • Solution: Verify ~/.gemini/skills/adk-agent-design/SKILL.md exists and has the frontmatter (the --- delimited YAML block).

Agent Runtime Errors

• Error: adk: command not found

  • Solution: Activate venv: source ~/agentverse-developer/env/bin/activate

• Error: ModuleNotFoundError: No module named 'mcp'

  • Solution: pip install -r shadowblade/requirements.txt from the project root.

• Error: Agent runs but doesn't call tools / gives random responses

  • Solution: The vibe-coded agent.py may be incorrect. Ensure working code was copied:

    cp ~/agentverse-developer/working_code/agent.py ~/agentverse-developer/shadowblade/agent.py
    cp ~/agentverse-developer/working_code/mcp_server.py ~/agentverse-developer/shadowblade/mcp_server.py
    

• Error: 429 RESOURCE_EXHAUSTED

  • Solution: Gemini API quota limit. Wait 60 seconds and retry.

• Error: Authentication errors (Service account info missing 'email' etc.)

  • Solution: Ctrl+C, refresh Cloud Shell browser window (NOT preview), re-activate venv, re-source set_env.sh.

Evaluation Errors

• Error: adk eval fails with "No module named 'shadowblade'"

  • Solution: Must run from ~/agentverse-developer/ directory (parent of shadowblade/). The agent module is discovered by folder name.

• Error: pytest test fails with RESOURCE_EXHAUSTED

  • Solution: API quota hit. Wait 1-2 minutes and re-run pytest test_agent_initiative.py.

• Error: Some eval cases fail

  • Solution: This is expected and documented: "Sometimes not all tests will pass." The lenient scoring thresholds (0.0, 0.1) should let most pass. If failures persist, check evalset JSON for formatting issues.

CI/CD Errors

• Error: Cloud Build fails at pytest step

  • Solution: Check that test_agent_initiative.py was copied from working_code, and environment variables are correctly passed via cloudbuild.yaml substitutions.

• Error: Docker build fails

  • Solution: Ensure shadowblade/Dockerfile exists. Check the build log for specific missing files.

• Error: Cloud Run deployment fails with permission denied

  • Solution: Verify all 6 IAM role bindings from Chapter 2 were applied. Re-run the gcloud projects add-iam-policy-binding commands.

Boss Fight Errors

• Error: Agent endpoint returns 503 or timeout

  • Solution: Cloud Run service may still be starting (cold start with min-instances=1). Wait 30 seconds. If persistent, check Cloud Run logs.

• Error: Dungeon URL returns 404

  • Solution: The dungeon was built by ~/agentverse-dungeon/run_cloudbuild.sh. If it wasn't run during setup, run it now.

---

Weapon Arsenal Reference (MCP Server Tools)

The complete mcp_server.py defines these weapons (students add 7 to the existing 2):

Weapon	Function Name	Effective Against	Damage Type
Forged Broadsword	forge_broadsword	Weaver of Spaghetti Code	Slashing
Soulshard Dagger	enchant_soulshard_dagger	Revolutionary Rewrite weakness	Arcane/Piercing
Refactoring Sickle	hone_refactoring_sickle	Elegant Sufficiency weakness	Cleansing
Quickstart Crossbow	fire_quickstart_crossbow	Inescapable Reality weakness	Initiative
The Gilded Gavel	strike_the_gilded_gavel	Elegant Sufficiency weakness	Finality
Daggers of Pair Programming	wield_daggers_of_pair_programming	Unbroken Collaboration weakness	Collaborative
Granite Maul	craft_granite_maul	Revolutionary Rewrite weakness	Bludgeoning
Lens of Clarity	focus_lens_of_clarity	Elegant Sufficiency weakness	Revelation
Codex of OpenAPI	scribe_with_codex_of_openapi	Inescapable Reality weakness	Documentation

Weakness → Tool mapping (from actual sample.evalset.json):

• Revolutionary Rewrite → enchant_soulshard_dagger (2 eval cases)
• Inescapable Reality → fire_quickstart_crossbow (1 eval case)

Note: The lab instructions reference wield_gauntlet_of_metrics as a mapping for Inescapable Reality when generating evalsets via Gemini CLI, but the actual pre-built sample.evalset.json uses fire_quickstart_crossbow instead. Both are valid weapons for that weakness.

---

Model & SDK Notes

Model versions used in this lab:

• The working code uses LlmAgent with gemini-2.5-flash — this is the current stable model.
• The ADK SDK version is specified in shadowblade/requirements.txt.

General Model Versioning Advisory:

• Gemini model versions follow a lifecycle: Preview → Stable → Deprecated → Retired. Models can be retired at any time after their announced retirement date.
• If any model string used in this lab starts returning errors (404, "model not found", "model deprecated"), check the currently active model versions at:
  • Vertex AI models: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions
  • Gemini API models: https://ai.google.dev/gemini-api/docs/models
• The recommended upgrade path for any deprecated gemini-2.x model is typically the latest gemini-2.5-flash or gemini-2.5-pro stable version.
• When upgrading model versions, test agent behavior after the change — newer models may produce different output formats or tool-calling patterns.

---

FALLBACK SEARCH PREPARATION

If you cannot find an answer within the provided skill materials:

1. Determine if the question is within scope (Gemini CLI, MCP, ADK, Cloud Build, Cloud Run, agent evaluation)
2. If in-scope, formulate a PRECISE SEARCH QUERY
3. Output: "SEARCH_QUERY: [your refined query]"

Examples:

• "SEARCH_QUERY: gemini cli extensions install nanobanana GOOGLE_GENAI_USE_VERTEXAI conflict"
• "SEARCH_QUERY: google-adk adk eval evalset.json tool_trajectory_avg_score failing"
• "SEARCH_QUERY: google cloud build substitutions PROJECT_ID not resolving"
• "SEARCH_QUERY: gemini cli hooks BeforeTool settings.json configuration"