feat(copilot): add goal decomposition step before agent building

autogpt_platform/backend/backend/api/features/chat/routes.py

@@ -64,6 +64,7 @@
     NoResultsResponse,
     SetupRequirementsResponse,
     SuggestedGoalResponse,
+    TaskDecompositionResponse,
     UnderstandingUpdatedResponse,
 )
 from backend.copilot.tracking import track_user_message
@@ -1264,6 +1265,7 @@ async def health_check() -> dict:
     | DocPageResponse
     | MCPToolsDiscoveredResponse
     | MCPToolOutputResponse
+    | TaskDecompositionResponse
 )
 
 

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

@@ -26,6 +26,19 @@ Steps:
 **Skip this** when the goal already specifies all dimensions (e.g.
 "scrape prices from Amazon and email me daily").
 
+### Before Building: Goal Decomposition (REQUIRED)
+
+Before running the workflow below, ALWAYS decompose the goal first:
+
+1. Analyze the user's request and break it into logical build steps (e.g.
+   "add input block", "add AI summarizer", "wire blocks together").
+2. Call `decompose_goal` with those steps.
+3. **STOP — do not proceed until the user approves the plan.**
+4. Only after approval, continue with "Workflow for Creating/Editing Agents".
+
+For simple goals (1-2 blocks), keep steps brief (2-3 steps).
+For complex goals, decompose into 4-8 steps max.
+
 ### Workflow for Creating/Editing Agents
 
 1. **If editing**: First narrow to the specific agent by UUID, then fetch its

autogpt_platform/backend/backend/copilot/tools/__init__.py

@@ -17,6 +17,7 @@
 from .continue_run_block import ContinueRunBlockTool
 from .create_agent import CreateAgentTool
 from .customize_agent import CustomizeAgentTool
+from .decompose_goal import DecomposeGoalTool
 from .edit_agent import EditAgentTool
 from .feature_requests import CreateFeatureRequestTool, SearchFeatureRequestsTool
 from .find_agent import FindAgentTool
@@ -59,6 +60,7 @@
     "ask_question": AskQuestionTool(),
     "create_agent": CreateAgentTool(),
     "customize_agent": CustomizeAgentTool(),
+    "decompose_goal": DecomposeGoalTool(),
     "edit_agent": EditAgentTool(),
     "find_agent": FindAgentTool(),
     "find_block": FindBlockTool(),

autogpt_platform/backend/backend/copilot/tools/decompose_goal.py

@@ -0,0 +1,145 @@
+"""DecomposeGoalTool - Breaks agent-building goals into sub-instructions."""
+
+import logging
+from typing import Any
+
+from backend.copilot.model import ChatSession
+
+from .base import BaseTool
+from .models import (
+    DecompositionStepModel,
+    ErrorResponse,
+    TaskDecompositionResponse,
+    ToolResponseBase,
+)
+
+logger = logging.getLogger(__name__)
+
+# Matches the guide's "4-8 steps max" constraint.
+MAX_STEPS = 8
+DEFAULT_ACTION = "add_block"
+VALID_ACTIONS = {"add_block", "connect_blocks", "configure", "add_input", "add_output"}
+
+
+class DecomposeGoalTool(BaseTool):
+    """Tool for decomposing an agent goal into sub-instructions."""
+
+    @property
+    def name(self) -> str:
+        return "decompose_goal"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Break down an agent-building goal into logical sub-instructions. "
+            "Each step maps to one task (e.g. add a block, wire connections, "
+            "configure settings). ALWAYS call this before create_agent to show "
+            "the user your plan and get approval."
+        )
+
+    @property
+    def parameters(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "goal": {
+                    "type": "string",
+                    "description": "The user's agent-building goal.",
+                },
+                "steps": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "description": {
+                                "type": "string",
+                                "description": "Human-readable step description.",
+                            },
+                            "action": {
+                                "type": "string",
+                                "description": (
+                                    "Action type: 'add_block', 'connect_blocks', "
+                                    "'configure', 'add_input', 'add_output'."
+                                ),
+                                "enum": list(VALID_ACTIONS),
+                            },
+                            "block_name": {
+                                "type": "string",
+                                "description": "Block name if adding a block.",
+                            },
+                        },
+                        "required": ["description", "action"],
+                    },
+                    "description": "List of sub-instructions for the plan.",
+                },
+            },
+            "required": ["goal", "steps"],
+        }
+
+    async def _execute(
+        self,
+        user_id: str | None,
+        session: ChatSession,
+        goal: str | None = None,
+        steps: list[Any] | None = None,
+        **kwargs,
+    ) -> ToolResponseBase:
+        session_id = session.session_id if session else None
+
+        if not goal:
+            return ErrorResponse(
+                message="Please provide a goal to decompose.",
+                error="missing_goal",
+                session_id=session_id,
+            )
+
+        if not steps:
+            return ErrorResponse(
+                message="Please provide at least one step in the plan.",
+                error="missing_steps",
+                session_id=session_id,
+            )
+
+        if len(steps) > MAX_STEPS:
+            return ErrorResponse(
+                message=f"Too many steps ({len(steps)}). Keep the plan to {MAX_STEPS} steps max.",
+                error="too_many_steps",
+                session_id=session_id,
+            )
+
+        decomposition_steps: list[DecompositionStepModel] = []
+        for i, step in enumerate(steps):
+            if not isinstance(step, dict):
+                return ErrorResponse(
+                    message=f"Step {i + 1} is malformed — expected an object.",
+                    error="invalid_step",
+                    session_id=session_id,
+                )
+            description = step.get("description", "")
+            if not description or not description.strip():
+                return ErrorResponse(
+                    message=f"Step {i + 1} is missing a description.",
+                    error="empty_description",
+                    session_id=session_id,
+                )
+            action = step.get("action", DEFAULT_ACTION)
+            if action not in VALID_ACTIONS:
+                action = DEFAULT_ACTION
+            decomposition_steps.append(
+                DecompositionStepModel(
+                    step_id=f"step_{i + 1}",
+                    description=description,
+                    action=action,
+                    block_name=step.get("block_name"),
+                    status="pending",
+                )
+            )
+
+        return TaskDecompositionResponse(
+            message=f"Here's the plan to build your agent ({len(decomposition_steps)} steps):",
+            goal=goal,
+            steps=decomposition_steps,
+            step_count=len(decomposition_steps),
+            requires_approval=True,
+            session_id=session_id,
+        )