> ## Documentation Index
> Fetch the complete documentation index at: https://docs.standardagentbuilder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# definePrompt

> Reference for prompt configuration, tools, and subagent relationships

## Signature

```typescript theme={null}
import { definePrompt } from '@standardagents/builder';

export default definePrompt({
  // PromptDefinition
});
```

## PromptDefinition (first pass)

```typescript theme={null}
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

```typescript theme={null}
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

## Related

* [defineAgent](/api-reference/define/agent)
* [Subagents](/core-concepts/subagents)