Agent Design — Naming, Tagging & Descriptions
The single biggest cause of "wrong agent in production" incidents is inconsistent naming. Two minutes of convention up front saves hours of confusion later.
Why this matters
In a busy tenant, a Tenant User opens the ADK UI and sees a grid of 30+ agents. If the names are bot, bot2, support-v3-final, and test, they will pick wrong. Worse, an Admin updating an endpoint URL might patch the wrong one.
Good agent design makes the Agents page scannable in one second.
The naming checklist
Use the pattern: <purpose>-<audience>-<env>
| Good | Bad |
|---|---|
support-customer-prod | bot |
sre-internal-prod | bot2 |
sales-outbound-staging | test-final-v3 |
compliance-internal-dev | agent |
Rules:
- Lowercase, hyphenated, no spaces
- Three segments max — purpose, audience, environment
prod,staging,devfor environment (avoidqa,uat,live— pick one vocabulary)
Tagging
Tags are how filters work. Without them, the Framework filter and Status filter in the Agents page are your only way to slice the list.
Required tags
Every agent should carry at least:
- An environment tag —
production,staging,development - A domain tag —
support,sre,sales,internal,compliance,research - A sensitivity tag —
public,internal,confidential
Optional tags
customer-facing— flags agents that need AgentGuardcost-sensitive— flags agents under tight token budgetsbeta— flags experimental agents your team should treat with caution
Use the same tag vocabulary across all teams. Document the list in your team's runbook or in TraptureIQ's Support reference.
Descriptions
The description appears under the agent name in the ADK UI and in chat history. Treat it like a one-line README.
Format: Who uses it — what it does — what data it can see
| Good | Bad |
|---|---|
Customer support — answers L1 questions from the help-center KB. Reads ticket metadata only. | Support bot |
SRE — incident triage assistant. Has read-only access to Cloud Logging and PagerDuty. | For SREs |
A bad description gets the agent ignored. A good one gets it adopted.
Environment separation
Run separate Google ADK agents for dev, staging, and production — do not toggle a single agent's endpoint URL between environments.
Why:
- Traces, logs, evals, and cost reports are all attributed per-agent
- Mixing environments contaminates your observability data
- A dev rollback shouldn't take production offline
If you have three environments and five purposes, that's fifteen agents. That's fine — registration is zero-code, so the only cost is naming discipline.
Anti-patterns
Untitled Agentleft in production — Rename before you walk away from the registration form.v2,v3,finalin the name — Versions belong in your deployment metadata, not the agent name. Update the agent in place.- Same agent reused across environments — See above. Always split.
- No tags — Your filters are useless.
Where to configure
- Register a new agent → Registering an Agent
- Edit an existing one → Editing or Deactivating Agents
- Browse and filter → Viewing Your Agents