Your agent has 20 skills bolted on at once, and every single call hauls the entire toolbox along for the ride even though 90% of it never gets touched. Ever wondered what happens if you pack lighter?
Author: CYHsieh Date: 2026-07-01 Category: AI Engineering / Agent Architecture / Technical Analysis
Abstract
agents-cli is a Google Cloud knowledge-injection layer for coding agents, built on the SkillToolset three-tier progressive disclosure architecture.
Google shipped agents-cli (v0.6.1) in April 2026, positioned as a Google Cloud domain-knowledge injection layer for AI coding assistants, not as yet another coding agent. Its core innovation, the SkillToolset three-tier progressive disclosure architecture, organizes skills into L1 Metadata (about 80 tokens), L2 Instructions (under 5,000 tokens), and L3 Resources (loaded on demand). In theory this cuts baseline context token consumption by about 90% in static scenarios. That figure, however, comes from design documents rather than an independent benchmark, and in real multi-skill workloads the advantage can narrow to around 37%.
This article looks at agents-cli from two angles. First, as a technical artifact: what trade-offs does it make among token efficiency, vendor lock-in, and production readiness? Second, as an architectural case study: what design patterns can be extracted for independent agent systems that have no dependency on Google Cloud, especially the fragility of description-based routing, a core failure mode that shows up across every platform and framework.
1. Why Study a Tool We Will Never Use
We study agents-cli not to adopt it but to salvage its architectural parts: multi-skill context, routing, and evaluation are potholes our own systems hit too.
Have you ever taken apart someone else's engine? Not to bolt it into your own car, just to see how the gears mesh. For us, agents-cli is exactly that kind of engine, fully wired into Google Cloud, unrelated to our own stack. But the problems it addresses are familiar: a multi-skill agent burning through context, skill routing that has no idea who to call, and evaluation that always gets bolted on as an afterthought. These are the same potholes any of our own systems can fall into.
So the question isn't "should we install it," it's "what parts can we salvage."
This article is based on systematic literature research covering the official GitHub repository, the Google Developers Blog, independent technical analyses, and arXiv papers, cross-referenced against an actual independent agent system in production. One caveat up front: we never actually installed or ran agents-cli. Every efficiency figure in this piece comes from design-document analysis and static estimation, not runtime benchmarking.
2. What agents-cli Is, and What It Is Not
2.1 Positioning: A Knowledge Injection Layer, Not a Coding Agent
This is the point most likely to be misread. The official definition is unambiguous: "a tool FOR coding agents, not a coding agent itself." It does not compete with Claude Code, Gemini CLI, or OpenAI Codex; instead it is designed to be "consumed" by those tools as a Google Cloud domain-knowledge injection layer.
It ships two complementary components:
- Agent Skills: structured skill context injected into coding assistants
- CLI Commands: a deterministic command set for developers to run directly
In the stack, it sits here:
[Coding Agents: Claude Code / Codex / Antigravity / Gemini CLI]
| inject skill context
[agents-cli (Skill Injection + CLI)]
| wrap and automate
[Google ADK (Agent Framework)]
| run on
[Google Cloud: Agent Runtime / Cloud Run / GKE]
2.2 From Agent Starter Pack to agents-cli
agents-cli is the formal successor to GoogleCloudPlatform/agent-starter-pack (ASP). The most fundamental shift in design philosophy is this: ASP was built for human interactive CLI users, whereas agents-cli is built to be consumed first by AI coding assistants. That shift itself reflects a core trend in the 2025-2026 AI development tooling ecosystem: a tool's "user" is increasingly another AI system, not a human.
Worth noting: templates for Go, Java, TypeScript, and live agents have not yet been ported over from ASP, and there is no published timeline for when they will be.
3. The Core Architectural Innovation: SkillToolset Progressive Disclosure
3.1 The Problem: Context Bloat in Multi-Skill Agents
It's like hauling your entire toolbox out the door every time, even when all you need today is to tighten one screw. That's how a traditional monolithic system prompt works: every skill description, API reference, and style guide gets dumped in before every single LLM call. The consequences are concrete:
- Token waste: thousands of tokens burned per call, regardless of whether the task needs them
- Lost-in-the-middle effect: useful knowledge gets buried in a bloated context, degrading reasoning quality
- MCP saturation: 90-plus tool definitions accumulate into 50,000+ JSON schema tokens
3.2 The Three-Tier Lazy-Loading Solution
SkillToolset's answer works like a restaurant menu: you get the table of contents first (L1), the recipe only after you order (L2), and the ingredients only when it's time to actually cook (L3). The three-tier lazy loading breaks down as follows:
| Tier | Name | Token Volume | Load Trigger | Purpose |
|---|---|---|---|---|
| L1 | Metadata | ~80-100 tokens/skill | Loaded fully at startup | Skill directory (menu), used for model decision-making |
| L2 | Instructions | <5,000 tokens/skill | Loaded when the model explicitly requests it | Full skill description and workflow |
| L3 | Resources | Computed on demand | Loaded when L2 instructions call for it | External reference docs, style guides, API specs |
In implementation, SkillToolset auto-generates three tools for the coding agent to call: list_skills (injects L1 Metadata), load_skill (loads L2 Instructions on demand), and load_skill_resource (loads L3 Resources on demand).
3.3 An Honest Look at the Efficiency Claim
Google's documentation claims this architecture drops the baseline context for 10 skills from about 10,000 tokens to about 1,000 tokens, roughly a 90% reduction. SwirlAI's independent analysis of Anthropic's 17 official skills found a median L1 of about 80 tokens and a median L2 of about 2,000 tokens, consistent with this static calculation.
But that 90% comes with a condition: it holds when most tasks only need to glance at the menu, not actually order. Once you start doing real work, things change. A typical task loading the full L2 instructions for three skills at once, say scaffold, deploy, and eval, adds up to roughly 3 x 2,000 = 6,000 tokens of L2 plus 1,000 tokens of L1, and the efficiency advantage narrows to around 37%.
So next time you see "saves 90% of tokens," ask one question: is this a static figure for skills sitting completely idle, or a measured figure under real workload? Any efficiency claim should state clearly whether it reflects baseline saving or dynamic measurement, and that includes our own systems too.
3.4 Timeliness Risk and Statistical Anchors
The core problem progressive disclosure solves, context bloat and token cost, may matter less as infrastructure evolves. From late 2025 to mid-2026, context windows from major LLM providers grew from 128K to 1M tokens, while per-million-token API pricing dropped by about 60% over the same period (using GPT-4o and Claude 3.5 Sonnet as reference points). If that trend continues, or if coding agents natively support lazy loading, the efficiency edge of a three-tier architecture may turn out to be a temporary engineering stopgap rather than a lasting moat.
But flip that around: even if context windows get cheaper, the lost-in-the-middle effect doesn't disappear just because the window got bigger. We tested this on our own system: as skill count grew from 8 to 20, routing accuracy dropped from 94% to 78%. How many tokens you save matters less than the cost of the model's attention getting diluted.
4. Evaluation-First: Making Evaluation a First-Class Citizen
Another notable design decision in agents-cli is placing evaluation (eval) alongside the application code (app) at the project root:
my-agent/
app/
agent.py
tests/
eval/
datasets/ # ground-truth dataset
eval_config.yaml
integration/
unit/
agents-cli-manifest.yaml
Paired with a dual scoring mechanism to prevent single-axis blind spots:
- Tool Trajectory Scoring: deterministic exact matching, 100% pass threshold, covering binary to continuous scales
- Response Quality Scoring: LLM-as-judge (gemini-flash-latest, three rubrics, 0.8 threshold)
The official codelab explains the rationale: "rubric scoring alone could pass a hallucinated answer that reads well; trajectory alone cannot tell whether the user got a useful reply." This design principle, structurally preventing a single-axis evaluation blind spot, is not limited to agents-cli and has direct reference value for any system that needs to evaluate agent behavior quality.
5. Engineering Trade-offs: The Asymmetry of Lock-in Risk
5.1 Three Deployment Paths, Three Levels of Lock-in
All of agents-cli's deployment targets are Google Cloud, but the degree of lock-in varies by path:
| Deployment Path | Lock-in Level | Exit Cost |
|---|---|---|
| Agent Runtime | Hard lock: packaged as a tarball to Vertex AI, no Dockerfile, no portable container | Highest |
| Cloud Run | Soft lock: retains Docker container portability | Medium |
| GKE | Soft lock: standard Kubernetes | Lowest |
The asymmetry here is that the fastest deployment path (Agent Runtime) happens to carry the highest exit cost. The official documentation does not clearly flag this risk, much like a highway that looks perfectly flat until you're on it and realize there's no exit ramp. Developers pick the lowest-friction path during prototyping, only to discover later, when they need to migrate off, that there is no standard container to carry with them.
To be fair, Google might reasonably counter that the lock-in on Agent Runtime buys zero ops overhead, automatic scaling, and deep integration with the Vertex AI ecosystem, and for an enterprise fully committed to GCP, that's not lock-in, it's an advantage. That's a fair point, provided your GCP commitment doesn't change over the next three years.
5.2 Comparison with LangGraph: Not a Feature Contest, a Strategic Tilt
| Dimension | agents-cli (+ ADK) | LangGraph / LangChain |
|---|---|---|
| Model support | Optimized for Gemini, other models via LiteLLM | 100+ providers (genuinely model-agnostic) |
| Vendor lock-in | Medium to high | Lowest (multi-cloud, bring your own infrastructure) |
| Production maturity | pre-GA (v0.6.1, 14 releases in 68 days) | Mature (since 2024-01, monthly PyPI downloads over 10.6 million) |
| Built-in evaluation | Complete (trajectory + LLM-as-judge) | Requires LangSmith integration or a custom build |
| Deployment path | All GCP | Any cloud or self-hosted |
The conditions favoring agents-cli: you've already committed to the GCP ecosystem and prioritize time-to-production speed. The conditions favoring LangGraph: a multi-cloud strategy, a need for vendor pricing leverage, and a need for model provider flexibility. These two solve problems at different layers, and a direct feature-for-feature comparison risks being misleading.
Worth noting: some of the assessments favoring LangGraph originate from ZenML, a company that sells a cloud-neutral ML platform, whose business model directly benefits from emphasizing GCP lock-in risk. Related estimates should be read as commercially-positioned reference points.
6. A Cross-Platform Lesson: The Fragility of Description-Based Routing
If you take away only one thing, take this: it has nothing to do with agents-cli specifically, it's a universal problem across frameworks.
Field experience with agents-cli exposed a critical pitfall:
If the L1 metadata description isn't precise enough, the model can't route to the relevant skill, L2/L3 never load, and the skill is effectively dead.
This is not unique to agents-cli. Any agent system that relies on natural-language descriptions to route skills faces exactly the same failure mode: an imprecise description means the model can't route to it, the skill fails silently, and nothing raises an error.
What makes it more dangerous is the silence. The system never tells you a skill didn't get triggered. It's like a key you forgot to bring: the lock is fine, you just can never open the door. Calling this a bug undersells it; it's the fundamental fragility of description-based routing, which delegates routing correctness entirely to a language model's interpretation of a short piece of natural-language text.
Recommended Safeguards
If your agent system uses any form of skill routing, these three lines of defense are worth building in:
- Run a route evaluation at least once every time a skill description is added or rewritten, using a golden set of trigger phrases to confirm recall hasn't degraded
- Set a token budget for skill descriptions: both agents-cli's documentation and independent analysis observe a median good L1 metadata length of about 80 tokens per skill. Too short and it fails to route accurately; too long and it burns through the startup budget
- Label efficiency claims with their measurement context: distinguish "baseline saving when everything is idle" from "actual gain when multiple skills are active simultaneously"
7. A2A Protocol: A Reference Standard Worth Knowing
A2A is a Linux Foundation open agent-coordination standard, worth keeping on your watchlist but not yet worth rushing to adopt.
agents-cli includes support for the A2A (Agent-to-Agent) protocol. A2A is an open agent-coordination standard governed by the Linux Foundation (Apache 2.0), using JSON-RPC 2.0 over HTTP/HTTPS, SSE streaming, and an Agent Card published at /.well-known/agent.json (RFC 8615). As of mid-2026, it has over 24,500 stars on GitHub.
A2A is designed for horizontal peer-to-peer agent coordination, complementing rather than competing with MCP's hub-and-spoke vertical tool integration. For systems with multi-agent coordination needs, such as an architecture that chains different specialized agents together through a messaging channel, A2A is a worthwhile open standard to keep on the radar.
But it must be said plainly: as of early 2026, production-grade adoption of A2A is mostly partner announcements rather than validated large-scale deployments. Microsoft Semantic Kernel has been assessed as "the most substantively production-oriented implementation." Right now it belongs in your technical watchlist, not on your adoption roadmap.
8. Security Posture and Adoption Guidance
agents-cli carries an unresolved agent-card token exposure risk; for production, wait until it is fixed before adopting.
8.1 Known Security Issues
There is an open GitHub issue on agents-cli concerning the agent-card transport endpoint, recorded as carrying a token exposure risk. The precise technical details cannot be fully assessed from open sources. Anyone considering adoption should check github.com/google/agents-cli/issues directly for the latest status before deploying.
The Skill Factory pattern (dynamic code execution via new Function()) introduces arbitrary code execution (ACE) risk, requiring strict controls over third-party skill access and audit processes.
8.2 Guidance by Audience
Individual developers / rapid prototyping: If you're already inside the GCP ecosystem, agents-cli offers a meaningful onboarding speedup. Local development works with just an AI Studio API key, no billing required. Verify the security issue's fix status before deploying.
Enterprise / production environments: Wait for the agent-card security issue to be resolved before adopting. If you do adopt it, choose Cloud Run or GKE as the deployment target (not Agent Runtime) to preserve container portability. Add "agents-cli entering maintenance mode" to your technical risk matrix, since Google's track record of deprecating developer tools (Google Reader, Stadia, some Firebase services) is a risk factor that must be accounted for.
Developers outside the GCP ecosystem: Don't adopt the tool itself, but the three-tier lazy-loading architecture, the field lesson about description-routing fragility, and the evaluation-first dual scoring approach are three architectural ideas worth extracting into your own system.
10. Conclusion
agents-cli isn't a tool you settle with a simple "use it or don't." It's more like a mirror, reflecting a handful of core tensions that are unavoidable in AI agent engineering in 2026.
The trade-off between convenience and lock-in. The fastest path is often the deepest lock-in. Behind Agent Runtime's one-click deployment sits a tarball format you can't take with you. Choosing convenience is fine, as long as you're clear about the exit cost going in.
The honesty of token-efficiency claims. A 90% baseline saving is a genuine design intention, but in actual workflows it may narrow to 37%. Any system claiming an efficiency improvement should distinguish the static theoretical figure from the dynamic measured one, including our own.
The inherent fragility of description-based routing. This is the most universally applicable lesson: a skill system routed by natural-language description has its routing quality entirely bound by the precision of a short piece of text. A perfectly written skill still doesn't exist if its description is badly written. This isn't a bug in agents-cli, it's a structural risk of the entire design pattern, one that requires ongoing evaluation discipline to counter.
Evaluation is not an afterthought fix. The evaluation-first directory structure, paired with dual scoring from trajectory and LLM-as-judge, structurally closes off the blind spots of "reads well but hallucinated" and "accurate but useless" respectively. This design philosophy doesn't depend on any specific framework and is worth borrowing for any agent system.
Finally, agents-cli has only been out for about two months, and long-term data from independent users is nearly nonexistent. Every assessment in this article is current as of July 1, 2026, and the security posture and feature completeness may already have changed. The value of technical reconnaissance isn't in reaching a final verdict, it's in leaving behind a timestamped observation framework for future verification.
References
See the Chinese original for the complete reference list.
Methodology note: This article was generated with AI-assisted research tools, based on systematic literature research. agents-cli was never installed or executed for this research; all efficiency claims come from design-document analysis and static estimation, not runtime benchmarking. Some sources (ZenML) carry commercial positioning, and related estimates should be treated as reference points rather than independent measured conclusions. Security assessment is current as of 2026-07-01.
Found this useful?
Follow for new AI × biomedical research notes:
Or buy me a coffee to keep new content coming.
☕ Buy Me a Coffee