agentleFS
jpantsjohajpantsjoha/googlecloud-plugin/skills/agent-architect/SKILL.md

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

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
  1. Distinctive:

    Before pinning any Gemini model ID, consult the deprecation discipline (see Model Selection below).

    line 34
  2. Distinctive:

    Default recommendation: Agent Runtime for a managed agent, Cloud Run for a custom containerized agent.

    line 79

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 Runtimeagent_engine / reasoningEngines literals
Agent SearchVertex AI Search endpoints
Agent RetrievalVector 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:

LayerProtocolPurposeGCP anchor
ToolsMCP (Model Context Protocol)Agent ↔ tools/datamcp-servers skill; GenAI Toolbox
AgentsA2A (Agent2Agent)Agent ↔ agent interop across frameworks/vendorsADK-native A2A support
PaymentsAP2 (Agent Payments Protocol)Agent-initiated payments with verifiable user mandatesgoogle-agentic-commerce/AP2
ReasoningGeminiThe model doing the thinkingModel 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)

TargetWhenTrade-off
Agent Runtime (Agent Engine)Managed agent runtime; want sessions, memory, scaling handledLeast ops; GEAP-native; reasoningEngines API
Cloud RunCustom container, HTTP agent, scale-to-zero, full controlYou own the server; cheap idle; see cloud-run skill
GKEComplex multi-service agent system, existing GKE estateMost 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

References

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.