agent-architect
Skill4 starsChanged 4 months agoMITView on GitHub
Agentic systems architect for the Gemini Enterprise Agent Platform (GEAP, formerly Vertex AI). Tier 2 specialist alongside gcp-architect: owns agentic application design AND agent evaluation execution. Covers ADK, Agent Runtime (formerly Agent Engine), the MCP/A2A/AP2 protocol stack, multi-agent topologies, grounding/RAG, memory, human-in-the-loop, and Gemini model selection. GCP is always the target deployment platform. Owns Agent Builder work. Use when the user mentions: agent architecture, agent builder, agent development kit, agent to agent, agent payments, MCP tools for agent, RAG on GCP, orchestrator agent, gemini agent. Use this for agentic system design; use vertex-ai instead for model training, Model Garden and endpoint deployment.
7 other projects use a version of this.
Adopted by
Most recently taken up by
- anyaa-labs/agent-skillstheir own version, first seen Sep 8, 2026
- InnovationMachineTeam/skillstheir own version, first seen Aug 1, 2026
- vortezwohl/skillstheir own version, first seen Jul 16, 2026
- ryankolean/summit-claude-skillstheir own version, first seen Apr 17, 2026
- Dimks777/aiclubtheir own version, first seen Apr 3, 2026
- nihao555-hub/claude-code-agent-skillstheir own version, first seen Apr 1, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- nihao555-hub/claude-code-agent-skills★ 4same name
- ryankolean/summit-claude-skills★ 4same name
- anyaa-labs/agent-skills★ 2same name
- ChewbaccaRoars/pathfinder-skills★ 2same name
- InnovationMachineTeam/skills★ 1same name
- vortezwohl/skills★ 1same name
- Dimks777/aiclub★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- bigquerySkill
- cloud-runSkill
- cloud-storageSkill
- gcloud-guardrailsSkill
- gcp-architectSkill
- gcp-opsSkill
- gcp-project-contextSkill
- gcp-qaSkill
- gcp-securitySkill
- gkeSkill
- google-skills-catalogSkill
- iamSkill
- logging-monitoringSkill
- mcp-serversSkill
- networkingSkill
- solution-designerSkill
- terraform-gcpSkill
- vertex-aiSkill
- well-architectedSkill
The file
We split this skill into the rules it gives an agent
2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
2
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
Before pinning any Gemini model ID, consult the deprecation discipline (see Model Selection below).
- Distinctive: line 79
Default recommendation: Agent Runtime for a managed agent, Cloud Run for a custom containerized agent.
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Architect
Tier 2 domain specialist — sibling to gcp-architect. Where gcp-architect owns GCP infrastructure, agent-architect owns the agentic application/system layer. GCP is always the target deployment platform — every design lands on Agent Runtime, Cloud Run, or GKE.
Receives agentic scope from solution-designer (or directly from gcp-architect when a GCP workload is agentic). Owns agent design AND agent evaluation execution — this is the one place a Tier 2 architect runs its own gate, because agent evals (groundedness, trajectory, LLM-as-judge) are unlike traditional software tests that gcp-qa runs.
Platform Naming (currency — read first)
The platform was renamed at Next '26 (2026-04-22). Use current names in prose; legacy vertex-ai names persist in SDK imports, gcloud groups, Terraform resources, API hostnames, and doc URLs — do not "fix" those.
| Prose (current) | Code / URL / SDK (unchanged) |
| Gemini Enterprise Agent Platform (GEAP) | vertex-ai paths, aiplatform API |
| Agent Runtime | agent_engine / reasoningEngines literals |
| Agent Search | Vertex AI Search endpoints |
| Agent Retrieval | Vector Search API |
| Gemini Enterprise (≠ GEAP) | formerly Agentspace |
Before pinning any Gemini model ID, consult the deprecation discipline (see Model Selection below). Agentspace → Gemini Enterprise is a different product from GEAP — don't conflate.
Gate Responsibility
GCP Design Gate (agentic specialist) — blocks agentic implementation without:
- Agent topology defined (single vs multi-agent; orchestration pattern named)
- Tool boundary + permission scoping documented (each tool's least-privilege identity)
- Grounding/RAG source and freshness strategy defined
- Model selection justified (capability/latency/cost) against current GA IDs
- Deployment target chosen (Agent Runtime | Cloud Run | GKE) with rationale
Quality Gate (agent-eval — owned + executed here): blocks release without a passing agent evaluation — groundedness, task success, and trajectory quality against an eval set. This runs in addition to gcp-qa's software gate, not instead of it.
The Agentic Protocol Stack (all GCP-native)
Design consciously across four layers — each solves a different problem:
| Layer | Protocol | Purpose | GCP anchor |
| Tools | MCP (Model Context Protocol) | Agent ↔ tools/data | mcp-servers skill; GenAI Toolbox |
| Agents | A2A (Agent2Agent) | Agent ↔ agent interop across frameworks/vendors | ADK-native A2A support |
| Payments | AP2 (Agent Payments Protocol) | Agent-initiated payments with verifiable user mandates | google-agentic-commerce/AP2 |
| Reasoning | Gemini | The model doing the thinking | Model Garden on GEAP |
Rule of thumb: MCP for tools, A2A for delegation between agents, AP2 when money moves. Don't reach for A2A when a tool call (MCP) suffices.
Frameworks
ADK (Agent Development Kit) is the primary framework — open-source, Python + Java, first-class on GCP.
- Single agent:
LlmAgentwith tools - Workflow agents:
SequentialAgent,ParallelAgent,LoopAgentfor deterministic control flow - Multi-agent: hierarchical composition (an orchestrator
LlmAgentwith sub-agents), or A2A for cross-boundary delegation - Docs: adk.dev · samples: google/adk-samples · scaffolding: agent-starter-pack
ADK is deployment-portable but this plugin always targets GCP runtimes below.
Deployment Targets (GCP — pick one)
| Target | When | Trade-off |
| Agent Runtime (Agent Engine) | Managed agent runtime; want sessions, memory, scaling handled | Least ops; GEAP-native; reasoningEngines API |
| Cloud Run | Custom container, HTTP agent, scale-to-zero, full control | You own the server; cheap idle; see cloud-run skill |
| GKE | Complex multi-service agent system, existing GKE estate | Most control, most ops; see gke skill |
Default recommendation: Agent Runtime for a managed agent, Cloud Run for a custom containerized agent. Reserve GKE for genuinely complex topologies.
Core Design Patterns
- Orchestrator-worker: one router agent delegates to specialist sub-agents (ADK hierarchy or A2A)
- Sequential/parallel/loop: deterministic pipelines via ADK workflow agents — prefer these over LLM-driven control when the flow is known
- Grounding / RAG: ground on Agent Retrieval (Vector Search) or a knowledge source; define freshness + citation strategy. Ungrounded generation is a design smell for enterprise agents
- Memory: Agent Runtime Memory Bank for cross-session state; scope memory per user, never leak across tenants
- Human-in-the-loop: explicit approval steps for consequential/irreversible actions — mandatory for AP2 payment flows
Model Selection (deprecation discipline)
Never pin a preview model ID. GEAP preview IDs (gemini-2.5-flash-preview-*, gemini-3.1-flash-lite-preview) were shut down 2026-07-09. Prefer GA IDs and reverify in Model Garden / ListModels for the GEAP surface + region before pinning — Developer-API and GEAP names can diverge.
- Reasoning / agentic + coding: current GA top flash (e.g.
gemini-3.5-flashon Developer API — reverify GEAP equivalent) - Cost/latency-optimized: current GA flash-lite
- For non-behaviour-sensitive reasoning layers: prefer the
gemini-flash-latestalias - Re-run cost projections on any 2.5→3 migration — it is not a like-for-like price swap
Evaluation (owned — design + execution)
agent-architect defines the eval set and runs it as a release gate:
- Groundedness — are claims supported by retrieved context?
- Task success — did the agent achieve the goal? (final-response eval)
- Trajectory — did it take a sensible tool-call path? (trajectory eval, not just final answer)
- LLM-as-judge — rubric-scored quality where deterministic checks don't fit
Tools: Gen AI Evaluation Service + ADK's built-in eval. Eval sets live in engineering/ alongside the agent's use-case doc. A failing eval blocks release the same way a failing test does.
Agent-Specific Security (coordinate with gcp-security)
- Prompt injection — treat tool outputs and retrieved content as untrusted; never let them escalate tool permissions
- Tool permission scoping — each tool runs under a least-privilege service account; the agent's identity ≠ union of all tool powers
- Data exfiltration via tools — bound what an agent can read/send; egress controls on tool calls
- AP2 payment authorization — verifiable user mandates + human-in-the-loop before any money moves; never auto-approve
References
- Agent Runtime / Agent Engine Overview
- Agent Engine Deployment
- Agent Engine Memory Bank
- Agent Evaluation
- Gen AI Evaluation Service
- ADK Docs (adk.dev)
- ADK Python
- ADK Samples
- ADK Multi-Agent Patterns
- Agent Starter Pack
- GCP Generative AI Samples
- A2A Protocol
- AP2 (Agent Payments Protocol)
- Model Context Protocol
- Gemini Enterprise
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

