Tweak agent builder & agent template

Author: jahooma

backend/src/templates/agents/agent-builder.ts

@@ -111,9 +111,9 @@ export const agentBuilder = (model: Model): Omit<AgentTemplate, 'id'> => {
       '',
       '## Best Practices:',
       '',
-      '1. **Purpose-Driven**: Each agent should have a clear, specific purpose',
+      '1. **Use as few fields as possible**: Leave out fields that are not needed to reduce complexity. Use as few fields as possible to accomplish the task.',
       '2. **Minimal Tools**: Only include tools the agent actually needs',
-      '3. **Clear Prompts**: Write clear, specific system prompts',
+      '3. **Clear and Concise Prompts**: Write clear, specific prompts that have no unnecessary words',
       '4. **Consistent Naming**: Follow naming conventions (kebab-case for IDs)',
       '5. **Appropriate Model**: Choose the right model for the task complexity',
       '',
@@ -141,8 +141,8 @@ export const agentBuilder = (model: Model): Omit<AgentTemplate, 'id'> => {
 
 For new agents, analyze their request and create a complete agent template that:
 - Has a clear purpose and appropriate capabilities
+- Leaves out fields that are not needed.
 - Uses only the tools it needs
-- Has a well-written system prompt
 - Follows naming conventions
 - Is properly structured
 
@@ -156,25 +156,10 @@ For editing existing agents:
 When editing, always start by reading the current agent file to understand its structure before making changes. Ask clarifying questions if needed, then create or update the template file in the appropriate location.
 
 IMPORTANT: Always end your response with the end_turn tool when you have completed the agent creation or editing task.`,
-    stepPrompt: `Continue working on the agent template creation or editing. Focus on:
-- Understanding the requirements
-- Creating or updating a well-structured template
-- Following best practices
-- Ensuring the agent will work effectively for its intended purpose
-- For edits: preserving existing functionality while making requested changes
-
-IMPORTANT: Always end your response with the end_turn tool when you have completed the agent creation or editing task.`,
+    stepPrompt: '',
 
     // Generator function that defines the agent's execution flow
-    handleSteps: function* ({
-      agentState,
-      prompt,
-      params,
-    }: {
-      agentState: any
-      prompt: string | undefined
-      params: Record<string, any> | undefined
-    }) {
+    handleSteps: function* ({ agentState, prompt, params }) {
       // Step 1: Create directory structure
       yield {
         toolName: 'run_terminal_command',
@@ -252,12 +237,6 @@ Please create the complete agent template now.`,
 
       // Step 5: Complete agent creation process
       yield 'STEP_ALL'
-
-      // Step 6: End the turn explicitly
-      yield {
-        toolName: 'end_turn',
-        args: {},
-      }
     },
   }
 }

common/src/templates/agent-template.d.ts

@@ -43,10 +43,11 @@ export interface AgentConfig {
   // Prompts
   // ============================================================================
 
-  /** Prompt for when to spawn this agent as a subagent. Include the main purpose and use cases. */
+  /** Prompt for when to spawn this agent as a subagent. Include the main purpose and use cases.
+   * This field is key if the agent is a subagent and intended to be spawned. */
   parentPrompt?: string
 
-  /** Background information for the agent. Prefer using instructionsPrompt for agent instructions. */
+  /** Background information for the agent. Fairly optional. Prefer using instructionsPrompt for agent instructions. */
   systemPrompt?: string
 
   /** Instructions for the agent.
@@ -55,7 +56,7 @@ export interface AgentConfig {
   instructionsPrompt?: string
 
   /** Prompt inserted at each agent step. Powerful for changing the agent's behavior,
-   * but prefer instructionsPrompt for most instructions. */
+   * but usually not necessary for smart models. Prefer instructionsPrompt for most instructions. */
   stepPrompt: string
 
   /** Instructions for specific parent agents on when to spawn this agent as a subagent. */
@@ -65,19 +66,26 @@ export interface AgentConfig {
   // Input and Output
   // ============================================================================
 
-  /** The input schema required to spawn the agent. Provide a prompt string and/or a params object. */
+  /** The input schema required to spawn the agent. Provide a prompt string and/or a params object or none.
+   * 80% of the time you want just a prompt string with a description:
+   * inputSchema: {
+   *   prompt: { type: 'string', description: 'A description of what info would be helpful to the agent' }
+   * }
+   */
   inputSchema?: {
     prompt?: { type: 'string'; description?: string }
     params?: JsonSchema
   }
 
-  /** Whether to include conversation history (defaults to true) */
+  /** Whether to include conversation history. Defaults to false.
+   * Use this if the agent needs to know all the previous messages in the conversation.
+   */
   includeMessageHistory?: boolean
 
   /** How the agent should output a response to its parent (defaults to 'last_message')
    * last_message: The last message from the agent, typcically after using tools.
    * all_messages: All messages from the agent, including tool calls and results.
-   * json: Make the agent output a structured JSON object. Can be used with outputSchema or without if you want freeform json output.
+   * json: Make the agent output a JSON object. Can be used with outputSchema or without if you want freeform json output.
    */
   outputMode?: 'last_message' | 'all_messages' | 'json'
 
@@ -97,14 +105,35 @@ export interface AgentConfig {
    *
    * Or use 'return' to end the turn.
    *
-   * Example:
+   * Example 1:
    * function* handleSteps({ agentStep, prompt, params}) {
    *   const { toolResult } = yield {
    *     toolName: 'read_files',
    *     args: { paths: ['file1.txt', 'file2.txt'] }
    *   }
    *   yield 'STEP_ALL'
    * }
+   *
+   * Example 2:
+   * handleSteps: function* ({ agentState, prompt, params }) {
+   *   while (true) {
+   *     yield {
+   *       toolName: 'spawn_agents',
+   *       args: {
+   *         agents: [
+   *         {
+   *           agent_type: 'thinker',
+   *           prompt: 'Think deeply about the user request',
+   *         },
+   *       ],
+   *     },
+   *   }
+   *   const { toolResult: thinkResult } = yield 'STEP'
+   *   if (thinkResult?.toolName === 'end_turn') {
+   *     break
+   *   }
+   * }
+   * }
    */
   handleSteps?: (
     context: AgentStepContext