3.7 Section 3 Master Takeaway: Custom Agents Architecture Summary
1. Interactive ADK Architecture Switcher: Top 3 Section 3 Design Pitfalls
Section titled “1. Interactive ADK Architecture Switcher: Top 3 Section 3 Design Pitfalls”Click each button below to verify the exact architectural fix for the three most common ADK design pitfalls:
Why the Naive Design Fails
Configuring a single LlmAgent with both tools=[…] and output_schema=PydanticModel disables tool calling because the model is forced to emit strict JSON immediately.
The Winning Architectural Fix
Chain two agents inside a SequentialAgent: Agent 1 calls the tools and saves to output_key; Agent 2 (with no tools) reads that state key and applies output_schema!
2. The 6-Pillar Architecture Summary Grid
Section titled “2. The 6-Pillar Architecture Summary Grid”3.1 Single-Agent Params
description vs. instruction
Parent routers read description to delegate tasks; the agent’s own LLM reads instruction. Use output_key to write to session.state.
3.2 Workflow Patterns
Sequential, Parallel & Loop
Deterministic orchestrators use zero LLM calls for routing. Use unique output_key names in ParallelAgent and escalate=True in LoopAgent.
3.3 MCP & Custom Tools
MCP Toolbox for Databases
Uses tools.yaml (sources, tools, toolsets) for connection pooling, IAM auth, and parameterized SQL. Wrap built-in tools in AgentTool.
3.4 Grounding & Caching
Search vs. RAG vs. Cache
Agent Search = turnkey SaaS connectors + ACLs. RAG Engine = custom chunking + reranking. Context Caching = static 32k+ token reuse.
3.5 State & Memory Bank
4 Prefixes & Artifacts
temp: (1 turn), no prefix (1 session), user: (all user sessions), app: (global). Use Memory Bank for semantic recall & ArtifactService for PDFs.
3.6 A2A Protocol
Agent Cards & Task States
Publish /.well-known/agent.json. Use SSE for live streaming, Push Webhooks for multi-hour jobs, and input-required to request missing data.
3. Master “If You See X, Pick Y” Decision Matrix (Section 3)
Section titled “3. Master “If You See X, Pick Y” Decision Matrix (Section 3)”| Architectural Requirement / Scenario | Recommended Google Cloud / ADK Solution | Anti-Pattern to Avoid |
|---|---|---|
| Fix a parent coordinator that routes tasks to the wrong specialist sub-agent | Update the child agents’ description parameter so capabilities are distinct and mutually exclusive. |
Rewriting the child agent’s internal instruction or changing output_key. |
| Run 3 independent API/database checks concurrently and synthesize the results | Wrap a ParallelAgent (with 3 unique output_key names) and a synthesizer LlmAgent inside a SequentialAgent. |
Running all 3 checks sequentially or sharing one output_key across parallel branches. |
| Connect multiple agents to AlloyDB, Cloud SQL, Spanner, or BigQuery with pooling | MCP Toolbox for Databases configured via declarative tools.yaml (sources, tools, toolsets). |
Letting the LLM execute raw SQL strings over unpooled database connections in Python. |
| Ground an agent on SharePoint/Drive/Jira while enforcing document-level user ACLs | Agent Search on the Gemini Enterprise Agent Platform with identity-aware ACL filtering. | Gemini Context Caching or a custom RAG corpus without ACL metadata. |
| Cut latency and token costs when querying the exact same 400-page PDF on every turn | Gemini Context Caching (CachedContent / ContextCacheConfig) with an appropriate TTL. |
Re-sending the raw 400-page PDF in every prompt or chunking it when full-document reasoning is required. |
Store a 20-MB customer PDF or generated chart image without bloating session.state |
ArtifactService (GcsArtifactService) using save_artifact() and load_artifact(). |
Base64-encoding the PDF into session.state or storing binary blobs in Memory Bank. |
| Delegate a multi-turn, stateful goal to an external partner’s opaque agent | Agent2Agent (A2A) Protocol (RemoteA2aAgent, Agent Card, and input-required / Push Webhooks). |
Exposing the stateful partner agent as a stateless MCP database tool. |