Subagents are defined primarily as native tools! They are rewritten to be spawn_agents calls

Author: jahooma

common/src/tools/params/tool/spawn-agents.ts

@@ -31,10 +31,14 @@ const inputSchema = z
     `Spawn multiple agents and send a prompt and/or parameters to each of them. These agents will run in parallel. Note that that means they will run independently. If you need to run agents sequentially, use spawn_agents with one agent at a time instead.`,
   )
 const description = `
-Use this tool to spawn agents to help you complete the user request. Each agent has specific requirements for prompt and params based on their inputSchema.
+Use this tool to spawn agents to help you complete the user request. Each agent has specific requirements for prompt and params based on their tools schema.
 
 The prompt field is a simple string, while params is a JSON object that gets validated against the agent's schema.
 
+Each agent available is already defined as another tool, or, dynamically defined later in the conversation.
+
+You can call agents either as direct tool calls (e.g., \`example-agent\`) or use \`spawn_agents\`. Both formats work, but **prefer using spawn_agents** because it allows you to spawn multiple agents in parallel for better performance. When using direct tool calls, the schema is flat (prompt is a field alongside other params), whereas spawn_agents uses nested \`prompt\` and \`params\` fields.
+
 Example:
 ${$getNativeToolCallExampleString({
   toolName,

packages/agent-runtime/src/run-agent-step.ts

@@ -13,6 +13,7 @@ import { getAgentStreamFromTemplate } from './prompt-agent-stream'
 import { runProgrammaticStep } from './run-programmatic-step'
 import { additionalSystemPrompts } from './system-prompt/prompts'
 import { getAgentTemplate } from './templates/agent-registry'
+import { buildAgentToolSet } from './templates/prompts'
 import { getAgentPrompt } from './templates/strings'
 import { getToolSet } from './tools/prompts'
 import { processStream } from './tools/stream-parser'
@@ -639,6 +640,15 @@ export async function loopAgentSteps(
           },
         })) ?? ''
 
+  // Build agent tools (agents as direct tool calls) for non-inherited tools
+  const agentTools = useParentTools
+    ? {}
+    : await buildAgentToolSet({
+        ...params,
+        spawnableAgents: agentTemplate.spawnableAgents,
+        agentTemplates: localAgentTemplates,
+      })
+
   const tools = useParentTools
     ? parentTools
     : await getToolSet({
@@ -652,6 +662,7 @@ export async function loopAgentSteps(
           }
           return cachedAdditionalToolDefinitions
         },
+        agentTools,
       })
 
   const hasUserMessage = Boolean(

packages/agent-runtime/src/templates/prompts.ts

@@ -1,14 +1,141 @@
 import { getAgentTemplate } from './agent-registry'
 import { buildArray } from '@codebuff/common/util/array'
 import { schemaToJsonStr } from '@codebuff/common/util/zod-schema'
+import { z } from 'zod/v4'
 
 import type { AgentTemplate } from '@codebuff/common/types/agent-template'
 import type { Logger } from '@codebuff/common/types/contracts/logger'
 import type { ParamsExcluding } from '@codebuff/common/types/function-params'
 import type { AgentTemplateType } from '@codebuff/common/types/session-state'
-import { getToolCallString } from '@codebuff/common/tools/utils'
+import type { ToolSet } from 'ai'
 
-export async function buildSpawnableAgentsDescription(
+/**
+ * Gets the short agent name from a fully qualified agent ID.
+ * E.g., 'codebuff/file-picker@1.0.0' -> 'file-picker'
+ */
+export function getAgentShortName(agentType: AgentTemplateType): string {
+  const withoutVersion = agentType.split('@')[0]
+  const parts = withoutVersion.split('/')
+  return parts[parts.length - 1]
+}
+
+/**
+ * Builds a flat input schema for an agent tool by combining prompt and params.
+ * E.g., { prompt?: string, ...paramsFields }
+ */
+export function buildAgentFlatInputSchema(agentTemplate: AgentTemplate): z.ZodType {
+  const { inputSchema } = agentTemplate
+  
+  // Start with an empty object schema
+  let schemaFields: Record<string, z.ZodType> = {}
+  
+  // Add prompt field if defined
+  if (inputSchema?.prompt) {
+    schemaFields.prompt = inputSchema.prompt.optional()
+  }
+  
+  // Merge params fields directly into the schema (flat structure)
+  if (inputSchema?.params) {
+    // Get the shape of the params schema if it's an object
+    const paramsJsonSchema = z.toJSONSchema(inputSchema.params, { io: 'input' })
+    if (paramsJsonSchema.properties) {
+      for (const [key, propSchema] of Object.entries(paramsJsonSchema.properties)) {
+        // Skip if we already have a prompt field
+        if (key === 'prompt') continue
+        
+        // Create a zod schema from the JSON schema property
+        const isRequired = (paramsJsonSchema.required as string[] | undefined)?.includes(key)
+        // Use z.any() with description since we can't perfectly reconstruct the original zod type
+        const fieldSchema = z.any().describe(
+          (propSchema as any).description || `Parameter: ${key}`
+        )
+        schemaFields[key] = isRequired ? fieldSchema : fieldSchema.optional()
+      }
+    }
+  }
+  
+  return z.object(schemaFields).describe(
+    agentTemplate.spawnerPrompt || `Spawn the ${agentTemplate.displayName} agent`
+  )
+}
+
+/**
+ * Builds AI SDK tool definitions for spawnable agents.
+ * These tools allow the model to call agents directly as tool calls.
+ */
+export async function buildAgentToolSet(
+  params: {
+    spawnableAgents: AgentTemplateType[]
+    agentTemplates: Record<string, AgentTemplate>
+    logger: Logger
+  } & ParamsExcluding<
+    typeof getAgentTemplate,
+    'agentId' | 'localAgentTemplates'
+  >,
+): Promise<ToolSet> {
+  const { spawnableAgents, agentTemplates } = params
+  
+  const toolSet: ToolSet = {}
+  
+  for (const agentType of spawnableAgents) {
+    const agentTemplate = await getAgentTemplate({
+      ...params,
+      agentId: agentType,
+      localAgentTemplates: agentTemplates,
+    })
+    
+    if (!agentTemplate) continue
+    
+    const shortName = getAgentShortName(agentType)
+    const inputSchema = buildAgentFlatInputSchema(agentTemplate)
+    
+    // Use the same structure as other tools in toolParams
+    toolSet[shortName] = {
+      description: agentTemplate.spawnerPrompt || `Spawn the ${agentTemplate.displayName} agent`,
+      inputSchema,
+    }
+  }
+  
+  return toolSet
+}
+
+/**
+ * Builds the description of a single agent for the system prompt.
+ */
+function buildSingleAgentDescription(
+  agentType: AgentTemplateType,
+  agentTemplate: AgentTemplate | null,
+): string {
+  if (!agentTemplate) {
+    // Fallback for unknown agents
+    return `- ${agentType}: Dynamic agent (description not available)
+prompt: {"description": "A coding task to complete", "type": "string"}
+params: None`
+  }
+  
+  const { inputSchema } = agentTemplate
+  const inputSchemaStr = inputSchema
+    ? [
+        `prompt: ${schemaToJsonStr(inputSchema.prompt)}`,
+        `params: ${schemaToJsonStr(inputSchema.params)}`,
+      ].join('\n')
+    : ['prompt: None', 'params: None'].join('\n')
+
+  return buildArray(
+    `- ${agentType}: ${agentTemplate.spawnerPrompt}`,
+    agentTemplate.includeMessageHistory &&
+      'This agent can see the current message history.',
+    agentTemplate.inheritParentSystemPrompt &&
+      "This agent inherits the parent's system prompt for prompt caching.",
+    inputSchemaStr,
+  ).join('\n')
+}
+
+/**
+ * Builds the full spawnable agents specification for subagent instructions.
+ * This is used when inheritSystemPrompt is true to tell subagents which agents they can spawn.
+ */
+export async function buildFullSpawnableAgentsSpec(
   params: {
     spawnableAgents: AgentTemplateType[]
     agentTemplates: Record<string, AgentTemplate>
@@ -18,7 +145,7 @@ export async function buildSpawnableAgentsDescription(
     'agentId' | 'localAgentTemplates'
   >,
 ): Promise<string> {
-  const { spawnableAgents, agentTemplates, logger } = params
+  const { spawnableAgents, agentTemplates } = params
   if (spawnableAgents.length === 0) {
     return ''
   }
@@ -37,43 +164,11 @@ export async function buildSpawnableAgentsDescription(
   )
 
   const agentsDescription = subAgentTypesAndTemplates
-    .map(([agentType, agentTemplate]) => {
-      if (!agentTemplate) {
-        // Fallback for unknown agents
-        return `- ${agentType}: Dynamic agent (description not available)
-prompt: {"description": "A coding task to complete", "type": "string"}
-params: None`
-      }
-      const { inputSchema } = agentTemplate
-      const inputSchemaStr = inputSchema
-        ? [
-            `prompt: ${schemaToJsonStr(inputSchema.prompt)}`,
-            `params: ${schemaToJsonStr(inputSchema.params)}`,
-          ].join('\n')
-        : ['prompt: None', 'params: None'].join('\n')
-
-      return buildArray(
-        `- ${agentType}: ${agentTemplate.spawnerPrompt}`,
-        agentTemplate.includeMessageHistory &&
-          'This agent can see the current message history.',
-        agentTemplate.inheritParentSystemPrompt &&
-          "This agent inherits the parent's system prompt for prompt caching.",
-        inputSchemaStr,
-      ).join('\n')
-    })
+    .map(([agentType, agentTemplate]) => buildSingleAgentDescription(agentType, agentTemplate))
     .filter(Boolean)
     .join('\n\n')
 
-  return `\n\n## Spawnable Agents
-
-Use the spawn_agents tool to spawn agents to help you complete the user request.
-
-Notes:
-- You can not call the agents as tool names directly: you must use the spawn_agents tool with the correct parameters to spawn them!
-- There are two types of input arguments for agents: prompt and params. The prompt is a string, and the params is a json object. Some agents require only one or the other, some require both, and some require none.
-- Below are the *only* available agents by their agent_type. Other agents may be referenced earlier in the conversation, but they are not available to you.
-
-Spawn only the below agents:
+  return `You are a subagent that can only spawn the following agents using the spawn_agents tool:
 
 ${agentsDescription}`
 }

packages/agent-runtime/src/templates/strings.ts

@@ -4,7 +4,7 @@ import { schemaToJsonStr } from '@codebuff/common/util/zod-schema'
 import { z } from 'zod/v4'
 
 import { getAgentTemplate } from './agent-registry'
-import { buildSpawnableAgentsDescription } from './prompts'
+import { buildFullSpawnableAgentsSpec } from './prompts'
 import { PLACEHOLDER, placeholderValues } from './types'
 import {
   getGitChangesPrompt,
@@ -108,8 +108,6 @@ export async function formatPrompt(
     [PLACEHOLDER.REMAINING_STEPS]: () => `${agentState.stepsRemaining!}`,
     [PLACEHOLDER.PROJECT_ROOT]: () => fileContext.projectRoot,
     [PLACEHOLDER.SYSTEM_INFO_PROMPT]: () => getSystemInfoPrompt(fileContext),
-    [PLACEHOLDER.TOOLS_PROMPT]: async () => '',
-    [PLACEHOLDER.AGENTS_PROMPT]: () => buildSpawnableAgentsDescription(params),
     [PLACEHOLDER.USER_CWD]: () => fileContext.cwd,
     [PLACEHOLDER.USER_INPUT_PROMPT]: () => escapeString(lastUserInput ?? ''),
     [PLACEHOLDER.INITIAL_AGENT_PROMPT]: () =>
@@ -144,11 +142,6 @@ export async function formatPrompt(
 }
 type StringField = 'systemPrompt' | 'instructionsPrompt' | 'stepPrompt'
 
-const additionalPlaceholders = {
-  systemPrompt: [PLACEHOLDER.TOOLS_PROMPT, PLACEHOLDER.AGENTS_PROMPT],
-  instructionsPrompt: [],
-  stepPrompt: [],
-} satisfies Record<StringField, string[]>
 export async function getAgentPrompt<T extends StringField>(
   params: {
     agentTemplate: AgentTemplate
@@ -164,7 +157,7 @@ export async function getAgentPrompt<T extends StringField>(
     'prompt' | 'tools' | 'spawnableAgents'
   > &
     ParamsExcluding<
-      typeof buildSpawnableAgentsDescription,
+      typeof buildFullSpawnableAgentsSpec,
       'spawnableAgents' | 'agentTemplates'
     >,
 ): Promise<string | undefined> {
@@ -178,11 +171,6 @@ export async function getAgentPrompt<T extends StringField>(
   } = params
 
   let promptValue = agentTemplate[promptType.type]
-  for (const placeholder of additionalPlaceholders[promptType.type]) {
-    if (!promptValue.includes(placeholder)) {
-      promptValue += `\n\n${placeholder}`
-    }
-  }
 
   let prompt = await formatPrompt({
     ...params,
@@ -202,18 +190,25 @@ export async function getAgentPrompt<T extends StringField>(
   if (promptType.type === 'instructionsPrompt' && agentState.agentType) {
     // Add subagent tools message when using parent's tools for prompt caching
     if (useParentTools) {
-      addendum +=
-        `\n\nYou are a subagent that only has access to the following tools: ${agentTemplate.toolNames.join(', ')}. Do not attempt to use any other tools.`
+      addendum += `\n\nYou are a subagent that only has access to the following tools: ${agentTemplate.toolNames.join(', ')}. Do not attempt to use any other tools.`
+
+      // For subagents with inheritSystemPrompt, include full spawnable agents spec
+      // since the parent's system prompt may not have these agents listed
+      if (agentTemplate.spawnableAgents.length > 0) {
+        addendum +=
+          '\n\n' +
+          (await buildFullSpawnableAgentsSpec({
+            ...params,
+            spawnableAgents: agentTemplate.spawnableAgents,
+            agentTemplates,
+          }))
+      }
+    } else if (agentTemplate.spawnableAgents.length > 0) {
+      // For non-inherited tools, agents are already defined as tools with full schemas,
+      // so we just list the available agent IDs here
+      addendum += `\n\nYou can spawn the following agents: ${agentTemplate.spawnableAgents.join(', ')}.`
     }
 
-    addendum +=
-      '\n\n' +
-      (await buildSpawnableAgentsDescription({
-        ...params,
-        spawnableAgents: agentTemplate.spawnableAgents,
-        agentTemplates,
-      }))
-
     // Add output schema information if defined
     if (agentTemplate.outputSchema) {
       addendum += '\n\n## Output Schema\n\n'

packages/agent-runtime/src/templates/types.ts

@@ -13,7 +13,6 @@ export type { AgentTemplate, StepGenerator, StepHandler }
 
 const placeholderNames = [
   'AGENT_NAME',
-  'AGENTS_PROMPT',
   'CONFIG_SCHEMA',
   'FILE_TREE_PROMPT_SMALL',
   'FILE_TREE_PROMPT',
@@ -24,7 +23,6 @@ const placeholderNames = [
   'PROJECT_ROOT',
   'REMAINING_STEPS',
   'SYSTEM_INFO_PROMPT',
-  'TOOLS_PROMPT',
   'USER_CWD',
   'USER_INPUT_PROMPT',
 ] as const

packages/agent-runtime/src/tools/prompts.ts

@@ -272,8 +272,9 @@ ${toolDescriptions.join('\n\n')}
 export async function getToolSet(params: {
   toolNames: string[]
   additionalToolDefinitions: () => Promise<CustomToolDefinitions>
+  agentTools: ToolSet
 }): Promise<ToolSet> {
-  const { toolNames, additionalToolDefinitions } = params
+  const { toolNames, additionalToolDefinitions, agentTools } = params
 
   const toolSet: ToolSet = {}
   for (const toolName of toolNames) {
@@ -289,5 +290,10 @@ export async function getToolSet(params: {
     } as Omit<typeof toolDefinition, 'inputSchema'> & { inputSchema: z.ZodType }
   }
 
+  // Add agent tools (agents as direct tool calls)
+  for (const [toolName, toolDefinition] of Object.entries(agentTools)) {
+    toolSet[toolName] = toolDefinition
+  }
+
   return toolSet
 }