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

# definePrompt

> Complete API reference for defining and configuring prompts

## Overview

Prompts define the instructions and configuration for LLM interactions in Standard Agents. Each prompt specifies system instructions, model configuration, tools, input validation, and context options.

> [card] Key Features
>
> * **File-based**: Defined in `agents/prompts/` directory
> * **Auto-discovered**: No manual registration required
> * **Type-safe**: Full TypeScript support with Zod validation
> * **Composable**: Prompts can be exposed as tools for other prompts
> * **Hot-reloadable**: Changes trigger HMR in development

## Quick Start

Create a new prompt in `agents/prompts/`:

```typescript agents/prompts/customer_support.ts theme={null}
import { definePrompt } from '@standardagents/spec';

export default definePrompt({
  name: 'customer_support',
  toolDescription: 'Handle customer support inquiries',
  prompt: `You are a helpful customer support agent.
Always be polite and try to resolve issues quickly.`,
  model: 'gpt-4o',
  includeChat: true,
});
```

Reference it in an agent:

```typescript agents/agents/support_agent.ts theme={null}
import { defineAgent } from '@standardagents/spec';

export default defineAgent({
  name: 'support_agent',
  sideA: {
    prompt: 'customer_support',  // References the prompt above
  },
  sideB: { human: true },
});
```

## Configuration Options

**name** `string` *required*

Unique identifier for this prompt. Use snake\_case.

```typescript theme={null}
name: 'customer_support'
```

**toolDescription** `string` *required*

Description shown when prompt is exposed as a tool. Always required for potential tool use.

```typescript theme={null}
toolDescription: 'Search for information and provide relevant results'
```

**prompt** `string` *required*

The system instructions sent to the LLM. Supports template variables using `{{variableName}}` syntax.

```typescript theme={null}
prompt: `You are helping {{userName}} with their request.
Current date: {{currentDate}}
Customer tier: {{customerTier}}`
```

**model** `string` *required*

Name of the model configuration to use. Must be defined in `agents/models/`.

```typescript theme={null}
model: 'gpt-4o'
```

> [!NOTE]
>
> Every prompt is callable as a tool.
> The deprecated `exposeAsTool` field has no effect.

**includeChat** `boolean` (default: false)

Include full chat history in LLM context.

```typescript theme={null}
includeChat: true
```

**includePastTools** `boolean` (default: false)

Include past tool call results in context.

```typescript theme={null}
includePastTools: true
```

**parallelToolCalls** `boolean` (default: false)

Allow the model to return multiple tool calls.

```typescript theme={null}
parallelToolCalls: false
```

**toolChoice** `'auto' | 'none' | 'required'` (default: 'auto')

Tool calling strategy:

* `'auto'`: LLM decides whether to use tools
* `'none'`: Disable tool calling
* `'required'`: Force the LLM to call at least one tool

```typescript theme={null}
toolChoice: 'required'
```

**requiredSchema** `ZodSchema`

Zod schema for input validation when called as tool.

```typescript theme={null}
requiredSchema: z.object({
  userId: z.string().describe('The user ID to look up'),
  includeHistory: z.boolean().optional().describe('Include transaction history'),
})
```

**tools** `(string | SubpromptConfig | PromptToolConfig)[]` (default: \[])

Available callable names, subprompt settings, and static tool options.

```typescript theme={null}
tools: [
  'search_knowledge_base',
  { name: 'create_ticket', includeErrors: true },
]
```

An exposed agent referenced in `tools` performs a handoff in the current thread.
Persistent child relationships belong in an owning agent side's `subagents` array.
Subagent relationship configuration in a prompt tool entry is a definition-time error.

**hooks** `string[]`

Hook IDs to run when this prompt is active. References hooks by their unique `id` property from `agents/hooks/`. If not specified, falls back to agent-level hooks.

```typescript theme={null}
hooks: ['limit_to_20_messages', 'log_tool_calls']
```

**reasoning** `ReasoningConfig`

Extended thinking configuration for models that support it.

```typescript theme={null}
reasoning: {
  level: 100,
  maxTokens: 10000,
}
```

## Tools in Prompts

Tools are callable capabilities exposed to LLMs. They can be:

> [card] Functions
>
> Custom code defined in `agents/tools/`

> [card] Prompts
>
> Other prompts exposed as tools (sub-prompts)

> [card] Agents
>
> Entire agents exposed as tools (handoffs)

### Adding Tools

```typescript theme={null}
definePrompt({
  name: 'support_prompt',
  tools: [
    'search_knowledge_base',                    // Simple reference
    { name: 'create_ticket' },                  // Object form
    { name: 'sub_prompt', includeErrors: true }, // With options
  ],
  // ...
});
```

### SubpromptConfig options

**name** `string` *required*

Name of the tool

**includeTextResponse** `boolean` (default: true)

Include text response from sub-prompt execution

**includeToolCalls** `boolean` (default: true)

Include tool call details from sub-prompt

**includeErrors** `boolean` (default: true)

Include error details from sub-prompt

**initUserMessageProperty** `string`

Property from tool arguments to use as initial user message

### PromptToolConfig options

```typescript theme={null}
{
  name: 'web_search',
  env: { SEARCH_CONTEXT: 'documentation' },
  options: { searchContextSize: 'high' },
}
```

`env` scopes environment values to the invocation.
`options` contains static tool options.
The deprecated `tenvs` alias remains available for environment values.
The admin `GET /api/prompts/:name` response retains `tools[].options` unchanged.
Prompt list and detail responses include the model display name in `model_name`.
Their `model_provider` field contains a provider name for icon lookup.

## Input Validation

Define input validation with Zod schemas:

```typescript theme={null}
import { definePrompt } from '@standardagents/spec';
import { z } from 'zod';

export default definePrompt({
  name: 'user_lookup',
  toolDescription: 'Look up user information',
  prompt: 'You help find user information...',
  model: 'gpt-4o',
  requiredSchema: z.object({
    userId: z.string().describe('The user ID to look up'),
    includeHistory: z.boolean().optional().describe('Include transaction history'),
  }),
});
```

### Supported Zod Types

> [accordion] Complete list of supported types
>
> | Zod Type | Example | Notes |
> | - | - | - |
> | `z.string()` | `z.string().min(1)` | Text values |
> | `z.number()` | `z.number().positive()` | Numeric values |
> | `z.boolean()` | `z.boolean()` | True/false |
> | `z.null()` | `z.null()` | Null value |
> | `z.literal()` | `z.literal('active')` | Exact value |
> | `z.enum()` | `z.enum(['a', 'b'])` | One of values |
> | `z.array()` | `z.array(z.string())` | Arrays |
> | `z.object()` | `z.object({...})` | Objects |
> | `z.record()` | `z.record(z.string())` | Dynamic keys |
> | `z.union()` | `z.union([...])` | Multiple types |
> | `z.optional()` | `z.string().optional()` | Optional field |
> | `z.nullable()` | `z.string().nullable()` | Can be null |
> | `z.default()` | `z.number().default(10)` | Default value |

**Note:** Maximum nesting depth is 7 levels.

## Extended Thinking

Configure extended thinking for models that support it:

```typescript theme={null}
definePrompt({
  name: 'complex_analysis',
  prompt: 'You analyze complex problems...',
  model: 'claude-sonnet',
  reasoning: {
    level: 100,          // 0 to 100
    maxTokens: 10000,    // Maximum reasoning tokens
    exclude: false,      // Include reasoning in response
    include: true,       // Send earlier reasoning back on later requests (default)
  },
});
```

### Reasoning Options

**level** `number`

A prompt can set `reasoning.level` from 0 to 100. An unset level uses the model's default. Level 0 means no reasoning. Each provider maps the level to the nearest option the model declares.

A prompt's `reasoning.level` replaces a native effort value in `providerOptions`. Other `providerOptions` keys remain. Without a level, `providerOptions` apply as provided. Native effort values in a model's `providerOptions` remain valid.

Saved prompt input with `reasoning.effort` fails validation. A published package prompt with `reasoning.effort` loads with a warning. The runtime ignores that field.

**maxTokens** `number`

Maximum tokens for reasoning (Anthropic, Google, Qwen)

**exclude** `boolean` (default: false)

Use reasoning internally but exclude from response

**include** `boolean` (default: true)

Send the stored reasoning of earlier assistant messages back to the model on later requests. Set `false` to stop sending it. The reasoning stays in the message record either way.

## Exposing Prompts as Tools

Every prompt is callable as a tool:

```typescript theme={null}
// agents/prompts/code_reviewer.ts
definePrompt({
  name: 'code_reviewer',
  toolDescription: 'Review code for bugs and improvements',
  prompt: `You are an expert code reviewer.
Analyze the provided code for:
- Bugs and potential issues
- Performance improvements
- Best practices violations`,
  model: 'gpt-4o',
  requiredSchema: z.object({
    code: z.string().describe('Code to review'),
    language: z.string().describe('Programming language'),
  }),
});
```

Use in another prompt:

```typescript theme={null}
// agents/prompts/developer_assistant.ts
definePrompt({
  name: 'developer_assistant',
  toolDescription: 'Help developers with coding tasks',
  prompt: 'You are a helpful coding assistant...',
  model: 'gpt-4o',
  tools: ['code_reviewer'],  // Use the prompt tool
});
```

### Sub-Prompt Execution Flow

When an LLM calls a prompt tool:

1. **Tool call received**: Parent prompt receives tool call with arguments
2. **Validation**: Arguments validated against `requiredSchema`
3. **Sub-prompt execution**: New execution context created
4. **Message hierarchy**: Messages stored with `parent_id` and `depth`
5. **Result rollup**: Sub-prompt response returned as tool result
6. **Parent continues**: Parent LLM receives result and continues

## Examples

### Basic Conversation

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

export default definePrompt({
  name: 'assistant',
  toolDescription: 'General assistant for conversations',
  prompt: `You are a helpful assistant.
Provide clear, accurate, and friendly responses.`,
  model: 'gpt-4o',
  includeChat: true,
});
```

### Customer Support with Tools

```typescript theme={null}
import { definePrompt } from '@standardagents/spec';
import { z } from 'zod';

export default definePrompt({
  name: 'customer_support',
  toolDescription: 'Handle customer support inquiries',
  prompt: `You are a customer support agent for Acme Corp.

Your responsibilities:
- Answer questions about products and services
- Help resolve issues on first contact
- Create support tickets when needed
- Escalate to specialists for complex issues

Always be professional and empathetic.`,
  model: 'gpt-4o',
  includeChat: true,
  tools: [
    'search_knowledge_base',
    'lookup_customer',
    { name: 'create_ticket', includeErrors: true },
  ],
});
```

### Data Analysis with Reasoning

```typescript theme={null}
import { definePrompt } from '@standardagents/spec';
import { z } from 'zod';

export default definePrompt({
  name: 'data_analyst',
  toolDescription: 'Analyze data and generate insights',
  prompt: `You are a data analyst expert.
Analyze the provided data and return actionable insights.
Use statistical analysis when appropriate.`,
  model: 'gpt-4o',
  reasoning: {
    level: 66,
    exclude: false,
  },
  requiredSchema: z.object({
    data: z.string().describe('Data to analyze (JSON format)'),
    question: z.string().describe('Analysis question'),
    format: z.enum(['summary', 'detailed', 'json']).default('summary'),
  }),
  tools: [
    'calculate_statistics',
    'generate_chart',
  ],
});
```

### Orchestrator

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

export default definePrompt({
  name: 'orchestrator',
  toolDescription: 'Coordinate complex multi-step tasks',
  prompt: `You are a task orchestrator.
Break down complex requests into steps and coordinate execution.
Use specialized prompts for specific tasks.`,
  model: 'gpt-4o',
  includeChat: true,
  includePastTools: true,
  tools: [
    'data_analyst',      // Sub-prompt
    'code_reviewer',     // Sub-prompt
    'research_agent',    // Agent tool
    'search_web',        // Function tool
  ],
});
```

## Type Definitions

### Canonical prompt types

Import the current types from the package:

```typescript theme={null}
import type {
  PromptDefinition,
  PromptToolConfig,
  SubpromptConfig,
  PromptInput,
} from '@standardagents/spec';
```

A prompt's `tools` array accepts callable names, `SubpromptConfig`, and `PromptToolConfig`.
`SubpromptConfig` controls result filters and initial message mappings.
`PromptToolConfig` supplies scoped environment values and static options.

### ReasoningConfig

```typescript theme={null}
interface ReasoningConfig {
  /** Reasoning level from 0 to 100 */
  level?: number;

  /** Maximum tokens for reasoning */
  maxTokens?: number;

  /** Use reasoning internally but exclude from response */
  exclude?: boolean;

  /** Send earlier reasoning back on later requests (default true) */
  include?: boolean;
}
```

### PromptInput Type Helper

Extract the input type from a prompt definition:

```typescript theme={null}
import type { PromptInput } from '@standardagents/spec';
import myPrompt from './my_prompt';

type MyPromptInput = PromptInput<typeof myPrompt>;
// { userId: string; options?: { format: 'json' | 'text' } }
```

## Best Practices

> [accordion] Write Clear System Prompts
>
> ```typescript theme={null}
> // Good - clear structure and expectations
> definePrompt({
>   name: 'support_agent',
>   prompt: `You are a customer support agent for Acme Corp.
>
> ## Your Role
> - Answer questions about products and services
> - Help resolve issues on first contact
> - Create tickets for complex issues
>
> ## Guidelines
> - Be professional and empathetic
> - Ask clarifying questions when needed
> - Never share internal information
>
> ## Available Tools
> Use these tools to help customers:
> - search_knowledge_base: Find product information
> - create_ticket: Create support tickets`,
>   // ...
> });
>
> // Avoid - vague instructions
> definePrompt({
>   name: 'support_agent',
>   prompt: 'Help customers.',
>   // ...
> });
> ```

> [accordion] Use Descriptive Tool Descriptions
>
> ```typescript theme={null}
> // Good - specific and actionable
> definePrompt({
>   name: 'search_prompt',
>   toolDescription: 'Search the knowledge base for product information, FAQs, and troubleshooting guides. Returns relevant articles.',
>   // ...
> });
>
> // Avoid - too vague
> definePrompt({
>   name: 'search_prompt',
>   toolDescription: 'Search stuff',
>   // ...
> });
> ```

> [accordion] Validate Inputs with Zod
>
> ```typescript theme={null}
> // Good - detailed schema with descriptions
> requiredSchema: z.object({
>   customerId: z.string().min(1).describe('Customer ID from CRM'),
>   issue: z.string().min(10).describe('Description of the issue'),
>   priority: z.enum(['low', 'medium', 'high']).default('medium'),
> }).strict()
>
> // Avoid - no validation
> requiredSchema: z.object({
>   data: z.any(),
> })
> ```

> [accordion] Enable includeChat for Conversations
>
> ```typescript theme={null}
> // For conversational prompts
> definePrompt({
>   name: 'chat_assistant',
>   includeChat: true,  // Needed for context
>   // ...
> });
>
> // For single-shot tasks
> definePrompt({
>   name: 'code_formatter',
>   includeChat: false,  // No history needed
>   // ...
> });
> ```

## File Structure

```
agents/
└── prompts/
    ├── customer_support.ts   # export default definePrompt({...})
    ├── data_analyst.ts       # export default definePrompt({...})
    └── orchestrator.ts       # export default definePrompt({...})
```

**Requirements:**

* One prompt per file
* Default export required
* Use snake\_case for file names

## Related Documentation

> [card] [Models](https://docs.standardagents.ai/api-reference/models)
>
> Define model configurations

> [card] [Tools](https://docs.standardagents.ai/api-reference/tools)
>
> Create custom function tools

> [card] [Agents](https://docs.standardagents.ai/api-reference/agents)
>
> Configure agents that use prompts

> [card] [Hooks](https://docs.standardagents.ai/api-reference/hooks)
>
> Intercept execution at various points


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.