google-adk

Google ADK Rules

Agent Design

• Keep each agent focused on a clear goal, persona, and tool set.
• Use LLM agents for flexible reasoning and workflow agents for deterministic orchestration.
• Write instructions that define task boundaries, tool-use rules, and escalation behavior.
• Split multi-agent systems by responsibility rather than by implementation convenience.
• Keep model choices configurable.

Tools

• Give tools narrow, typed inputs and outputs.
• Validate tool arguments before performing side effects.
• Keep secrets, credentials, and privileged APIs out of agent prompts.
• Handle tool errors explicitly and return actionable failure messages.
• Be aware of ADK tool limitations; some built-in tools cannot be combined with other tools on the same agent.

Sessions, State, and Memory

• Use session state for current-conversation data.
• Use memory for cross-session recall and retrieval.
• Keep state small and serializable.
• Do not store large files or binary payloads in session state.
• Make state keys stable and documented.

Artifacts

• Use artifacts for generated files, uploaded files, reports, images, audio, and other binary data.
• Configure an artifact service in the runner before relying on artifact operations.
• Version artifact filenames intentionally and avoid overwriting semantically different outputs.
• Store only references or summaries in state when full content belongs in artifacts.

Evaluation and Deployment

• Add tests for tool behavior, agent routing, prompt regressions, and unsafe tool calls.
• Use trace or event logs to debug agent decisions.
• Keep local development, staging, and production configuration separate.
• Add observability for latency, tool failures, token use, and handoff failures.

Common Mistakes

• Do not make one agent responsible for every workflow.
• Do not let tools accept arbitrary shell, SQL, or HTTP input without validation.
• Do not rely on prompt text for access control.
• Do not hide important side effects behind generic tool names.