Project Summary
This repository is a runnable Google ADK agent app — not a slideshow. It features a multi-agent root_agent with specialists, a RevOps lead triage subsystem using function tools over synthetic CRM data, Meridian BSA/AML alert triage over synthetic alerts, and a Vite + React chat UI with trace replay of tool calls against the ADK api_server. When GOOGLE_API_KEY is missing, agents use ollama/llama3.2 via ADK's LiteLLM integration.
Technical deep dive
Overview
Google Agent Development Kit (ADK) powers a production-style multi-agent architecture across three domains: portfolio storytelling, RevOps lead triage, and BSA/AML alert adjudication. This implementation demonstrates how orchestrator-specialist graphs can remain stable under prompt drift, model endpoint changes, and evolving tool contracts by enforcing typed inputs, deterministic tool outputs, and replayable trace events.
The project is engineered for enterprise agent evaluation, not one-off demos. Each hierarchy isolates domain context, routes intent to constrained specialists, and records event-level telemetry that can be replayed for recruiter walkthroughs, architecture reviews, and CI regression gates. The result is an auditable deployment blueprint for teams using ADK in high-accountability and customer-facing workflows.
Hierarchies mermaid
Each hierarchy follows the same systems contract with different domain semantics: an orchestrator decomposes intent, specialists execute tightly scoped tasks, and final outputs are assembled with provenance metadata. Reusing this pattern reduces operational complexity, improves debuggability, and accelerates specialist onboarding as tool and policy surfaces evolve.
Tool design rules table
| Rule | Rationale |
|---|---|
| Typed payload contracts | Every tool returns schema-stable keys and explicit status primitives so orchestrator branching remains deterministic and regression-friendly. |
| Domain namespace partitioning | Specialists receive only approved namespaces, reducing cross-domain leakage and accidental access to unrelated operational data. |
| Grounded narrative requirement | Narrative outputs must cite tool-returned evidence, reducing unsupported claims and hallucinated business facts. |
| Synthetic data disclosure | Synthetic datasets are explicitly labeled to separate demo artifacts from verified production history and avoid stakeholder confusion. |
| Replayable event logging | Structured traces support recruiter demos, incident debugging, and CI investigations across prompt and model routing changes. |
| Fail-closed tool errors | Tool exceptions return typed safe error states so orchestrators branch predictably without leaking internal implementation details. |
Model routing Gemini vs Ollama
Routing defaults to Gemini for high-fidelity reasoning, long-context synthesis, and stable cloud inference under production-like concurrency. Gemini is preferred when response quality, consistency, and broad tool-context comprehension directly influence stakeholder trust, executive communication, or downstream operational decisions.
Ollama provides a local fallback route for cost-controlled development, privacy-constrained demos, and offline execution. This dual-routing strategy lets the same ADK orchestration graph run in cloud and laptop environments with minimal branching logic, improving portability while preserving comparable evaluation signals.
| Route condition | Preferred model | Reason |
|---|---|---|
| Recruiter demo with rich synthesis | Gemini | Higher narrative quality and stronger multi-step reasoning for executive-facing storytelling and interview context. |
| RevOps triage with strict cost envelope | Ollama | Predictable local cost profile with acceptable quality for scoped classification, triage, and action recommendation tasks. |
| AML explanation requiring policy nuance | Gemini | Better long-context coherence for policy-grounded rationale, risk justification, and trace readability. |
| Offline or air-gapped development | Ollama | No outbound dependency and stronger control over data residency in local or restricted environments. |
Recruiter demo trace replay flow
Trace replay is a first-class product surface, not a debugging afterthought. It helps non-technical reviewers see how orchestrators delegate work, which specialist generated each claim, and how tool evidence shaped final outputs.
- Recruiter selects a scenario prompt for portfolio storytelling, RevOps triage, or AML alert dispositioning.
- Frontend sends a run request and receives structured events with orchestrator and specialist step metadata.
- Trace viewer replays delegation decisions, specialist outputs, and tool invocation events in strict time order.
- Final response renders with provenance markers mapping each key claim to specialist role and supporting tool evidence.
- Saved traces replay deterministically for interview demos, architecture walkthroughs, onboarding, and CI smoke checks.
- Regression harness compares trace signatures to detect prompt drift, tool contract breaks, and routing regressions.
Synthetic disclosure security callout
Production gaps table
| Area | Current state vs production target |
|---|---|
| Identity and access | Demo authentication supports local usage; production requires SSO, scoped RBAC, workload identity, and tenant isolation. |
| Secrets and key lifecycle | Environment variables simplify development; production needs managed secret stores, rotation policy, and key usage audit trails. |
| Observability | Basic logs enable troubleshooting; production needs distributed traces, metrics, redaction guarantees, and alerting SLAs with runbooks. |
| Evaluation and safety | Manual demos validate concept; production requires automated eval suites, policy conformance gates, and rollback thresholds. |
| Deployment posture | Local and Docker prove portability; production needs hardened CI/CD, runtime controls, canary rollouts, and rollback automation. |
| Data governance | Synthetic labels are present; production requires lineage tracking, retention controls, and legal hold workflows. |
pytest/CI
The test strategy uses pytest to validate tool determinism, specialist boundary enforcement, and orchestration invariants without requiring paid model calls on every run. CI executes linting, static analysis, schema contract checks, and targeted routing simulations so behavior remains stable as prompts, tools, and model policies evolve.
- Run unit tests for each tool adapter with strict request/response schema assertions.
- Execute orchestrator integration tests with mocked Gemini and Ollama backends for deterministic branch validation.
- Replay golden traces in CI to detect delegation drift, tool contract regressions, and response-shape changes.
- Fail builds on ungrounded citation checks when specialist outputs reference non-existent tool evidence.
- Publish coverage and trace diff artifacts for fast debugging during pull request review.
Key Features & Capabilities
- Multi-agent root_agent + specialists with LLM-driven transfer_to_agent delegation
- RevOps lead orchestrator: policy, scoring, and next-best-action over synthetic CRM records
- Meridian BSA/AML alert orchestrator with policy, risk severity, and disposition specialists
- Tool-grounded answers from portfolio_data.py — verified résumé facts, not hallucinations
- Gemini 2.0 Flash when API key is set; local Ollama fallback with zero Google bill required
- React recruiter demo with POST /run trace replay via Vite proxy to ADK api_server
Tech Stack & Components
Getting Started
1.Python environment
Create venv and install requirements from repo root.
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt2.Run ADK web UI
Select drake_talley_adk in the ADK web interface.
adk web --port 80003.Recruiter demo with trace replay
Terminal A runs api_server; Terminal B runs the React UI on port 5173.
adk api_server --port 8000
cd recruiter_demo && npm install && npm run devFrequently asked questions
- What is the Google ADK Portfolio repository?
- A runnable Google Agent Development Kit application with multi-agent transfer_to_agent delegation, tool-grounded résumé facts, RevOps lead triage over synthetic CRM data, Meridian BSA/AML alert orchestration over synthetic alerts, and a Vite + React trace-replay demo UI—not a static slideshow.
- Can I run the Google ADK portfolio without a Google API key?
- Yes. When GOOGLE_API_KEY is missing or a placeholder, agents route to ollama/llama3.2:latest via ADK LiteLLM integration. Install Ollama, run ollama pull llama3.2, and keep ollama serve running. A real API key selects gemini-2.0-flash instead.
- How does the portfolio prevent résumé hallucinations?
- Verified employment and quantitative claims live in portfolio_data.py and are exposed only through portfolio_tools.py. Tools return structured dicts with status fields; the LLM narrates tool output rather than inventing metrics. Synthetic case studies and demo CRM/AML records are explicitly labeled as illustrative.
- What agent hierarchies are in the Google ADK portfolio?
- Three parallel hierarchies: drake_talley_portfolio (technical_proof and executive_voice specialists), revops_lead_orchestrator (policy, scoring, action over synthetic leads), and aml_alert_orchestrator (policy, risk, disposition over synthetic BSA/AML alerts)—each with partitioned tool namespaces per specialist.
- Is Google ADK Web suitable for production?
- No. Google documents ADK Web as development-only. Production deployments target Cloud Run, Vertex AI Agent Engine, or hardened adk api_server patterns with Secret Manager, OpenTelemetry, OAuth at the edge, and per-tenant session isolation.