feat(backend/copilot): gate decompose_goal on library-similarity check

autogpt_platform/backend/backend/copilot/sdk/agent_generation_guide.md

@@ -5,121 +5,74 @@ generate the agent JSON yourself using block schemas, then validate and save.
 
 ### Clarifying — Before or During Building
 
-Use `ask_question` whenever the user's intent is ambiguous — whether
-that's before starting or midway through the workflow. Common moments:
-
-- **Before building**: output format, delivery channel, data source, or
-  trigger is unspecified.
-- **During block discovery**: multiple blocks could fit and the user
-  should choose.
-- **During JSON generation**: a wiring decision depends on user
-  preference.
-
-Steps:
-1. Call `find_block` (or another discovery tool) to learn what the
-   platform actually supports for the ambiguous dimension.
-2. Call `ask_question` with a concrete question listing the discovered
-   options (e.g. "The platform supports Gmail, Slack, and Google Docs —
-   which should the agent use for delivery?").
-3. **Wait for the user's answer** before continuing.
-
-**Skip this** when the goal already specifies all dimensions (e.g.
-"scrape prices from Amazon and email me daily").
-
-### Before Building: Show the Plan
-
-Start agent generation by calling `decompose_goal` once to display your
-build plan to the user as a step-by-step UI card.
-
-1. Analyze the user's request and break it into plain-English steps
-   describing **what the agent will do for the user**, not which blocks
-   you will add or how they connect. For a YouTube summarizer that
-   might be: "Accept a YouTube URL from the user", "Fetch the video's
-   transcript", "Generate a timestamped summary", "Return the summary
-   to the user".
-2. Call `decompose_goal` with those steps. Do not write any text before
-   or after the tool call — the platform renders the plan UI card
-   automatically, so any extra text duplicates the display.
-3. Continue immediately with the workflow below in the same turn. The
-   plan card is informational only — there is no approval step, no
-   countdown, and no need to wait for the user.
-
-The `description` is user-facing and must read as plain English to a
-non-technical user. The platform records the block name and action on
-the same step via the separate `block_name` and `action` fields — those
-fields carry the technical detail. Do not put block class names
-("AgentInputBlock", "AgentOutputBlock", "TranscribeYoutubeVideoBlock"),
-internal types, or wiring verbs ("wire", "connect", "link") inside
-`description`.
-
-For simple goals (1-2 blocks), keep steps brief (2-3 steps).
-For complex goals, use as many steps as needed.
+Use `ask_question` whenever the user's intent is ambiguous — before
+starting or mid-workflow. Typical gaps: output format, delivery channel,
+data source, trigger, or a choice between candidate blocks.
 
+Discover the platform's real options first (e.g. `find_block`), then
+call `ask_question` listing those options ("The platform supports
+Gmail, Slack, and Google Docs — which for delivery?") and **wait for
+the answer**.
+
+**Skip** when the goal already specifies every dimension (e.g. "scrape
+prices from Amazon and email me daily").
 
 ### Workflow for Creating/Editing Agents
 
-1. **If creating a new agent from a user goal (REQUIRED before `create_agent`)**:
-   First call
-   `find_library_agent(for_creation=true, goal_summary="<one-sentence summary of what the user wants>")`
-   to check whether the user already has a functionally similar agent. The
-   tool runs a hybrid semantic + lexical similarity search over the user's
-   library and returns either:
-   - `AgentsFoundResponse` with candidates whose descriptions are prefixed
-     with `[N% match]`. **Surface these to the user**, preserving the match
-     prefix, and ask whether they want to reuse one before you build a new
-     agent. If they pick an existing agent, run it with `run_agent` —
-     **do not** call `create_agent`.
-   - `NoResultsResponse` — no functionally similar agent exists, so you may
-     proceed with `create_agent`.
-
-   `create_agent` enforces this check as a hard gate (`require_library_check`)
-   and will refuse otherwise. If the user has been shown matches and
-   explicitly tells you to build a new one anyway, retry `create_agent`
-   with `library_check_ack=true` to bypass the gate for that call.
-   **Never set `library_check_ack=true` proactively** — only after the
-   user has seen the matches and chosen to build new.
-
-   Builder-bound sessions (when the user is already editing a specific
-   agent in the Builder) bypass this gate automatically — no
-   pre-flight call is needed there.
-
-2. **If editing**: First narrow to the specific agent by UUID, then fetch its
+1. **Library check (REQUIRED before `create_agent`)**: Call
+   `find_library_agent(for_creation=true, goal_summary="<one-sentence summary>")`
+   to look for a functionally similar agent the user already owns. If
+   matches are returned, surface them to the user with the `[N% match]`
+   prefix preserved and ask before building new; if they pick one, run
+   it with `run_agent`. If the user has seen matches and explicitly
+   tells you to build anyway, retry `create_agent` with
+   `library_check_ack=true` — **never set this proactively**. Builder-
+   bound sessions bypass this gate automatically.
+
+2. **Show the plan**: Once step 1 is past, call `decompose_goal` with
+   plain-English steps that describe **what the agent does for the
+   user**, not blocks or wiring — e.g. for a YouTube summarizer:
+   "Accept a YouTube URL", "Fetch the transcript", "Generate a
+   timestamped summary", "Return the summary". The platform renders
+   the card; don't write text around the call and don't wait —
+   continue building in the same turn. Keep `description` plain
+   English; put block class names and wiring verbs in the separate
+   `block_name` and `action` fields.
+3. **If editing**: First narrow to the specific agent by UUID, then fetch its
    graph: `find_library_agent(query="<agent_id>", include_graph=true)`. This
    returns the full graph structure (nodes + links). **Never edit blindly** —
    always inspect the current graph first so you know exactly what to change.
    Avoid using `include_graph=true` with broad keyword searches, as fetching
    multiple graphs at once is expensive and consumes LLM context budget.
-3. **Discover blocks**: Call `find_block(query, include_schemas=true, for_agent_generation=true)` to
+4. **Discover blocks**: Call `find_block(query, include_schemas=true, for_agent_generation=true)` to
    search for relevant blocks. This returns block IDs, names, descriptions,
    and full input/output schemas. The `for_agent_generation=true` flag is
    required to surface graph-only blocks such as AgentInputBlock,
    AgentDropdownInputBlock, AgentOutputBlock, OrchestratorBlock,
    and WebhookBlock and MCPToolBlock. (When running MCP tools interactively
    in CoPilot outside agent generation, use `run_mcp_tool` instead.)
-4. **Find library agents for sub-agent composition**: Call `find_library_agent`
+5. **Find library agents for sub-agent composition**: Call `find_library_agent`
    (default mode, no `for_creation` flag) to discover reusable agents that
    can be composed as sub-agents via `AgentExecutorBlock`. This is distinct
    from the create-time similarity check in step 1 — here you're looking
    for building blocks, not asking "does the user already have this?".
-5. **Generate/modify JSON**: Build or modify the agent JSON using block schemas:
-   - Use block IDs from step 3 as `block_id` in nodes
+6. **Generate/modify JSON**: Build or modify the agent JSON using block schemas:
+   - Use block IDs from step 4 as `block_id` in nodes
    - Wire outputs to inputs using links
    - Set design-time config in `input_default`
    - Use `AgentInputBlock` for values the user provides at runtime
    - When editing, apply targeted changes and preserve unchanged parts
-6. **Write to workspace**: Save the JSON to a workspace file so the user
+7. **Write to workspace**: Save the JSON to a workspace file so the user
    can review it: `write_workspace_file(filename="agent.json", content=...)`
-7. **Validate**: Call `validate_agent_graph` with the agent JSON to check
+8. **Validate**: Call `validate_agent_graph` with the agent JSON to check
    for errors
-8. **Fix if needed**: Call `fix_agent_graph` to auto-fix common issues,
+9. **Fix if needed**: Call `fix_agent_graph` to auto-fix common issues,
    or fix manually based on the error descriptions. Iterate until valid.
-9. **Save**: Call `create_agent` (new) or `edit_agent` (existing) with
-   the final `agent_json`. For `create_agent`, the library similarity gate
-   from step 1 must have been satisfied (either matches were shown to the
-   user, or pass `library_check_ack=true` after explicit user confirmation).
-10. **Dry-run**: ALWAYS call `run_agent` with `dry_run=True` and
+10. **Save**: Call `create_agent` (new) or `edit_agent` (existing) with
+    the final `agent_json`.
+11. **Dry-run**: ALWAYS call `run_agent` with `dry_run=True` and
     `wait_for_result=120` to verify the agent works end-to-end.
-11. **Inspect & fix**: Check the dry-run output for errors. If issues are
+12. **Inspect & fix**: Check the dry-run output for errors. If issues are
     found, call `edit_agent` to fix and dry-run again. Repeat until the
     simulation passes or the problems are clearly unfixable.
     See "REQUIRED: Dry-Run Verification Loop" section below for details.