Agent architect

Skill jpantsjoha/googlecloud-plugin/skills/agent-architect

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.From its SKILL.md

Install

npx -y skills add jpantsjoha/googlecloud-plugin --skill agent-architect

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

9.4 KB, as published. Nobody here has run it

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: LlmAgent with tools
Workflow agents: SequentialAgent, ParallelAgent, LoopAgent for deterministic control flow
Multi-agent: hierarchical composition (an orchestrator LlmAgent with 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-flash on Developer API — reverify GEAP equivalent)
Cost/latency-optimized: current GA flash-lite
For non-behaviour-sensitive reasoning layers: prefer the gemini-flash-latest alias
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