> ## 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.

# Prompts

> Configure model behavior, tools, and subagent tool relationships

## What Are Prompts?

Prompts define:

* system instructions (`prompt`)
* model (`model`)
* available tools (`tools`)
* optional context controls and validation

Prompts are auto-discovered from `agents/prompts/`.

## Basic Example

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

export default definePrompt({
  name: 'orchestrator_prompt',
  toolDescription: 'Orchestrates specialized work.',
  prompt: 'Delegate tasks to the right tools and summarize outcomes.',
  model: 'base_model',
  includeChat: true,
  tools: ['search_docs'],
});
```

## Tool Types in `tools`

`tools` accepts multiple forms:

* `string` callable name
* `SubpromptConfig` for prompt-tool options
* `PromptToolConfig` for tool-level options
* `SubagentToolConfig` for `dual_ai` subagent relationships

## Subagent Tool Configuration

Use `SubagentToolConfig` to define parent -> child behavior:

```typescript theme={null}
tools: [
  {
    name: 'topdown_asset_subagent',
    blocking: false,
    immediate: {
      nameEnv: 'ASSET_INSTANCE_NAME',
      descriptionEnv: 'ASSET_INSTANCE_DESCRIPTION',
      scopedEnv: ['ASSET_API_KEY'],
    },
    initUserMessageProperty: 'message',
    initAttachmentsProperty: 'attachments',
    initAgentNameProperty: 'name',
    resumable: {
      receives_messages: 'side_a',
      maxInstances: 20,
    },
  },
],
```

### Important Fields

* `blocking`: wait for child completion or return immediately
* `resumable`: persistent child instances with message routing
* `initUserMessageProperty`: map args to child initial message
* `initAttachmentsProperty`: map args to child initial attachment paths
* `initAgentNameProperty`: map args to child thread display name
* `immediate`: `true` for default immediate boot, or an object when you want explicit `nameEnv` / `descriptionEnv` hints and runtime-only `scopedEnv` transfer

## Resumable Runtime Tools

When a prompt has resumable subagent configs, AgentBuilder injects runtime tools:

* `subagent_create`
* `subagent_message`

`subagent_create` requires a non-empty `name` argument. Use a concise stable child-instance label rather than leaving the thread anonymous.

`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.

Non-resumable subagents behave like normal tool calls and are not created via lifecycle tools.

## Context and Validation

Useful options:

* `includeChat`
* `includePastTools`
* `toolChoice`
* `requiredSchema`
* `reasoning`
* `hooks`

## Best Practices

* Keep orchestrator prompts focused on delegation + synthesis
* Put strict production/QA logic into the child `dual_ai` agent
* Use explicit `init*Property` mappings for predictable payloads
* Use the object form of `immediate` when per-instance boot should derive from safe name/description envs without exposing secrets
* Set reasonable `maxInstances` on resumable children

## Related Docs

* [Subagents](/core-concepts/subagents)
* [Agents](/core-concepts/agents)
* [definePrompt](/api-reference/define/prompt)