Skip to main content

​
Signature

import { definePrompt } from '@standardagents/builder';

export default definePrompt({
  // PromptDefinition
});

​
PromptDefinition (first pass)

interface PromptDefinition {
  name: string;
  toolDescription: string;
  prompt: string | PromptPart[];
  model: string;

  exposeAsTool?: boolean;
  includeChat?: boolean;
  includePastTools?: boolean;
  toolChoice?: 'auto' | 'none' | 'required';
  requiredSchema?: ZodSchema;
  hooks?: string[];
  reasoning?: {
    effort?: 'low' | 'medium' | 'high';
    maxTokens?: number;
    include?: boolean;
    exclude?: boolean;
  };

  tools?: Array<
    | string
    | SubpromptConfig
    | PromptToolConfig
    | SubagentToolConfig
  >;
}

interface SubagentToolConfig {
  name: string;
  blocking?: boolean;
  initUserMessageProperty?: string;
  initAttachmentsProperty?: string;
  initAgentNameProperty?: string;
  immediate?: boolean | {
    nameEnv?: string;
    descriptionEnv?: string;
    scopedEnv?: string[];
  };
  resumable?:
    | false
    | {
        receives_messages: 'side_a' | 'side_b';
        maxInstances?: number;
      };
}

​
Subagent Semantics

SubagentToolConfig defines behavior on the relationship between this prompt and a callable dual_ai agent.
  • non-resumable subagents behave like direct tool calls
  • resumable subagents are lifecycle-managed by runtime tools
  • initial payload/name mappings are controlled by init*Property options
  • immediate: true runs the child immediately when the prompt activates
  • immediate: { ... } makes the relationship explicit: nameEnv and descriptionEnv are the only envs exposed to the internal bootstrap model, while scopedEnv is copied to the child thread but remains runtime-only
For resumable subagents, runtime tools are injected:
  • subagent_create
  • subagent_message
subagent_create requires a non-empty name argument for the spawned child instance. subagent_create.arguments is shaped from the prompt schema on the child side selected by resumable.receives_messages. AgentBuilder persists those values with the child thread, exposes them to both child sides as ThreadState.arguments, and makes top-level keys available to prompt variable interpolation.

​
Example: orchestrator with resumable non-blocking subagent

definePrompt({
  name: 'asset_orchestrator',
  toolDescription: 'Coordinates subagent asset generation.',
  prompt: 'Spawn and coordinate subagents to generate assets.',
  model: 'base_model',
  tools: [
    {
      name: 'topdown_asset_subagent',
      blocking: false,
      initUserMessageProperty: 'message',
      initAttachmentsProperty: 'attachments',
      initAgentNameProperty: 'name',
      resumable: {
        receives_messages: 'side_a',
        maxInstances: 20,
      },
    },
  ],
});

​
Attachment Mapping Notes

When initAttachmentsProperty is used for subagents:
  • source attachment paths are validated in parent thread
  • files are copied parent -> child filesystem
  • child receives rewritten destination-local paths