# Pitfall Log

Project: google/agents-cli

Summary: Found 40 structured pitfall item(s), including 15 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/44

## 2. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/42

## 3. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/29

## 4. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/9

## 5. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/28

## 6. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/39

## 7. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/36

## 8. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/25

## 9. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/37

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: Add an optional AISP deployment readiness contract for eval, approval, deploy, rollback, and observability gates
- User impact: Developers may expose sensitive permissions or credentials: Add an optional AISP deployment readiness contract for eval, approval, deploy, rollback, and observability gates
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/48

## 11. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: Support Antigravity SDK as a first-class agent implementation framework
- User impact: Developers may expose sensitive permissions or credentials: Support Antigravity SDK as a first-class agent implementation framework
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/41

## 12. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/21

## 13. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/45

## 14. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/41

## 15. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/46

## 16. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Add an optional AISP lifecycle contract for spec → scaffold → build → eval → deploy → observe
- User impact: Developers may fail before the first successful local run: Add an optional AISP lifecycle contract for spec → scaffold → build → eval → deploy → observe
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/47

## 17. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Deployment fails to resolve the `litellm` package version and fails
- User impact: Developers may fail before the first successful local run: Deployment fails to resolve the `litellm` package version and fails
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/42

## 18. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Path traversal in remote-template scaffolding → arbitrary file write (agents-cli scaffold create --agent <remote>)
- User impact: Developers may fail before the first successful local run: Path traversal in remote-template scaffolding → arbitrary file write (agents-cli scaffold create --agent <remote>)
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/50

## 19. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Provide a bundled GUI client or a standalone desktop app instead of relying on heavy CLI setups
- User impact: Developers may fail before the first successful local run: Provide a bundled GUI client or a standalone desktop app instead of relying on heavy CLI setups
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/21

## 20. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Python version option for agents-cli deploy
- User impact: Developers may fail before the first successful local run: Python version option for agents-cli deploy
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/45

## 21. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: run --mode a2a: agent-card transport endpoint is not pinned to --url; bearer token can be sent to a card-specified host
- User impact: Developers may fail before the first successful local run: run --mode a2a: agent-card transport endpoint is not pinned to --url; bearer token can be sent to a card-specified host
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/46

## 22. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v0.5.0: deploy to agent_runtime builds on the CLI's own Python (sys.version_info), not the project's — fails when a dependency lacks a wheel for that version (e.g. Python 3.14 +...
- User impact: Developers may fail before the first successful local run: v0.5.0: deploy to agent_runtime builds on the CLI's own Python (sys.version_info), not the project's — fails when a dependency lacks a wheel for that version (e.g. Python 3.14 +...
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/36

## 23. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/47

## 24. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/43

## 25. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/google/agents-cli

## 26. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Add a proactive "verify against official docs" step before code generation
- User impact: Developers may misconfigure credentials, environment, or host setup: Add a proactive "verify against official docs" step before code generation
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/44

## 27. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Add an init command to create agents-cli-manifest.yaml for existing ADK projects
- User impact: Developers may misconfigure credentials, environment, or host setup: Add an init command to create agents-cli-manifest.yaml for existing ADK projects
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/25

## 28. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Add an optional AISP eval quality contract for dataset coverage, grading, failure analysis, and optimization traces
- User impact: Developers may misconfigure credentials, environment, or host setup: Add an optional AISP eval quality contract for dataset coverage, grading, failure analysis, and optimization traces
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/49

## 29. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: `adk_a2a` (agent_runtime) scaffold does not set Vertex location before building the A2A agent → card URL stamped with us-central1 for non-us-central1 deploys
- User impact: Developers may misconfigure credentials, environment, or host setup: `adk_a2a` (agent_runtime) scaffold does not set Vertex location before building the A2A agent → card URL stamped with us-central1 for non-us-central1 deploys
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/28

## 30. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: repo init with cicd, for a2a ,adk , tool, and sub agent init.
- User impact: Developers may misconfigure credentials, environment, or host setup: repo init with cicd, for a2a ,adk , tool, and sub agent init.
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/39

## 31. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/google/agents-cli

## 32. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: agents-cli update floods console with Python UnicodeDecodeError tracebacks on non-UTF-8 Windows consoles
- User impact: Developers may hit a documented source-backed failure mode: agents-cli update floods console with Python UnicodeDecodeError tracebacks on non-UTF-8 Windows consoles
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/37

## 33. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: packet_text.keyword_scan | https://github.com/google/agents-cli

## 34. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: Support per-eval-case ADK session state in `agents-cli eval generate`
- User impact: Developers may hit a documented source-backed failure mode: Support per-eval-case ADK session state in `agents-cli eval generate`
- Evidence: failure_mode_cluster:github_issue | https://github.com/google/agents-cli/issues/52

## 35. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/google/agents-cli/issues/52

## 36. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/google/agents-cli

## 37. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/google/agents-cli

## 38. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/google/agents-cli

## 39. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/google/agents-cli

## 40. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/google/agents-cli