createSubagent

createSubagent(ctx, options): AgentBuilder

Defined in: agent/subagent.ts:168

Create a subagent from within a gadget.

This helper simplifies the common pattern of creating nested agents. It automatically:

• Gets the correct AgentBuilder from host exports
• Resolves model with “inherit” support from CLI config
• Shares the parent’s execution tree for cost tracking
• Forwards the abort signal for proper cancellation

Parameters

ctx

ExecutionContext

ExecutionContext passed to gadget’s execute()

options

SubagentOptions

Subagent configuration options

Returns

AgentBuilder

Configured AgentBuilder ready for .ask()

Example

// Basic usage
const agent = createSubagent(ctx, {
  name: "BrowseWeb",
  gadgets: [Navigate, Click],
}).ask("Go to google.com");

// With all options
const agent = createSubagent(ctx, {
  name: "BrowseWeb",
  gadgets: [Navigate, Click, Screenshot],
  systemPrompt: "You are a browser automation agent...",
  model: params.model,  // Runtime override
  defaultModel: "sonnet",
  maxIterations: 20,
  hooks: {
    observers: {
      onLLMCallReady: () => refreshPageState(),
    },
  },
}).ask(params.task);

for await (const event of agent.run()) {
  // Events flow through shared tree automatically
}