docs: add missing warnings for key ADK footguns and workflow gaps#86
Merged
AaronForinton merged 3 commits intomainfrom Apr 17, 2026
Merged
docs: add missing warnings for key ADK footguns and workflow gaps#86AaronForinton merged 3 commits intomainfrom
AaronForinton merged 3 commits intomainfrom
Conversation
Addresses gaps identified from a real end-to-end AI-agent build that caused significant lost time due to missing or unclear documentation. Gap 1 — No local runtime: - testing.md: add prominent warning that there is no poly serve or local simulator - what-is-the-adk.md: clarify the ADK manages config files and does not execute agents Gap 2 — API keys are workspace-scoped: - prerequisites.md: add warning that poly init lists all projects visible to the key; if you see the wrong projects, you likely have the wrong key - also removes a garbled duplicate "Local requirements" section left over from an earlier edit Gap 3 — Platform-provisioned resources cannot be created via ADK: - voice_settings.md, chat_settings.md, agent_settings.md, speech_recognition.md: add note that greeting, style prompt, disclaimer, personality, role, and ASR settings are created by Agent Studio on project init and can only be updated, not created; push will fail with NotImplementedError if the file exists locally without a matching .agent_studio_config entry Gap 4 — Don't copy project directories: - anti-patterns.md: add new section explaining why copying a project directory to a different project causes push failures; correct approach is poly init + poly pull Gap 6 — No poly merge command: - tutorials/build-an-agent.md: add note at Steps 10 and Workflow 2 Step 7 that merging requires the Agent Studio web UI; there is no poly merge CLI command Minor gaps: - tutorials/build-an-agent.md: mark chat/ as optional in the project structure diagram - tutorials/build-an-agent.md: add tip in AI-agent Workflow 2 Step 3 to run poly docs --all immediately after poly pull, before generating any files Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ording American English: - tutorials/build-an-agent.md: Initialise → Initialize (heading + table), Customise → Customize (heading), Dialogue → Dialog (card) - reference/topics.md: dialogue → dialog - reference/experimental_config.md: Behaviour → Behavior Platform-provisioned notes accuracy: - voice_settings.md, chat_settings.md, agent_settings.md, speech_recognition.md, anti-patterns.md: replace "initialised in Agent Studio" / "an initialised project" with "created by the platform" / "any Agent Studio project" The original wording implied the project had to be set up via the Agent Studio browser UI. In practice these resources are provisioned server-side at project creation time regardless of how the project is created, so the notes are accurate for pure ADK / Claude Code workflows that start from an API key alone. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Addresses the documentation gaps identified from a real end-to-end AI-agent workflow build (Bella Vista reservation assistant) that caused significant lost time. Each change adds a targeted note or warning where the docs were silent on a real failure mode.
Motivation
A systematic audit against a live implementation identified six gaps where the docs' silence or vagueness caused actual blockers — not theoretical ones. Several required digging through source code to resolve.
Changes
Gap 1 — No local runtime
testing.md: prominent warning that there is nopoly serveor local simulator; all execution is in Agent Studio Sandboxwhat-is-the-adk.md: clarify the ADK manages config files and does not execute agentsGap 2 — API keys are workspace-scoped
prerequisites.md: warning thatpoly initlists all projects visible to the key; seeing unexpected projects means the wrong key is in use; also removes a garbled duplicate section from a previous editGap 3 — Platform-provisioned resources cannot be created via ADK
voice_settings.md,chat_settings.md,agent_settings.md,speech_recognition.md: note on each page that greeting/style prompt/disclaimer/personality/role/ASR settings are provisioned by Agent Studio on project init and can only be updated, not created; pushing them into a project without a matching.agent_studio_configentry fails withNotImplementedError: Create operation not supportedGap 4 — Don't copy project directories
anti-patterns.md: new section explaining why copying a project directory to a different project causes push failures (.agent_studio_configIDs, platform-provisioned resources); correct approach ispoly init+poly pullGap 6 — No
poly mergecommandtutorials/build-an-agent.md: note at Workflow 1 Step 10 and Workflow 2 Step 7 that merging requires the Agent Studio web UI; there is no CLI commandMinor gaps
tutorials/build-an-agent.md: markchat/as optional in the project structure diagramtutorials/build-an-agent.md: add tip in AI-agent Workflow 2 Step 3 to runpoly docs --allimmediately afterpoly pull, before generating any files — without it, a coding agent has no schema context and will hallucinate resource structureWhat was not addressed
poly mergeCLI command — this is a code change, not a doc change; documented as a known gap--environment404) —cli.mdalready partially covers branch environment behavior; the failure mode may be platform-specific and is not clearly reproducibleTest strategy
Checklist
ruff check .andruff format --check .passpytestpassespolyCLI interface (or migration path documented)