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

# Prompts Overview

> Manage and version your AI prompts with MutagenT

# Prompt Management

MutagenT provides a complete prompt management system with versioning, variables, and lifecycle management. Centralize your prompts, track changes, and optimize performance systematically.

## Prompt Lifecycle

<Mermaid>
  flowchart LR
  A\["Create<br />Draft"] --> B\["Test<br />Playground"] --> C\["Evaluate<br />Dataset"] --> D\["Optimize<br />Auto-optimize"] --> E\["Deploy<br />Published"]

  style A fill:#64748B,color:#fff
  style B fill:#06B6D4,color:#000
  style C fill:#F59E0B,color:#000
  style D fill:#7C3AED,color:#fff
  style E fill:#10B981,color:#000
</Mermaid>

<Note>
  Each stage in the lifecycle builds on the previous. Start with a draft, test in the playground, validate with datasets, optimize automatically, and deploy with confidence.
</Note>

## Key Features

<CardGroup cols={2}>
  <Card title="Version Control" icon="code-branch" href="/platform/prompts/versioning">
    Track changes with full version history. Compare versions, rollback when needed, and maintain audit trails.
  </Card>

  <Card title="Template Variables" icon="brackets-curly" href="/platform/prompts/variables">
    Dynamic content with type-safe variables. Create reusable templates that adapt to different inputs.
  </Card>

  <Card title="Evaluation" icon="chart-line" href="/platform/evaluations/overview">
    Measure quality with automated testing. Use G-Eval, semantic similarity, and custom metrics.
  </Card>

  <Card title="Optimization" icon="wand-magic-sparkles" href="/platform/optimization/overview">
    Automatically improve prompts through AI-driven mutation and selection cycles.
  </Card>
</CardGroup>

## Prompt Content Types

MutagenT supports three content types when creating a prompt. Use exactly one:

| Content Type       | Fields                             | Use Case                                                          |
| ------------------ | ---------------------------------- | ----------------------------------------------------------------- |
| **Raw Prompt**     | `rawPrompt`                        | Single prompt text with `{variables}`                             |
| **System + Human** | `systemPrompt` + `humanPrompt`     | Structured system instructions paired with a user-facing template |
| **Messages Array** | Array of `{role, content}` objects | Full chat-format messages (system, user, assistant)               |

## Prompt Structure

```typescript theme={null}
interface Prompt {
  id: number;                                // Unique identifier
  name: string;                              // Display name
  description?: string;                      // Optional description
  version: string;                           // Semantic version (e.g., "1.0.0")
  isLatest: boolean;                         // Whether this is the latest version
  systemPrompt?: string;                     // System-level instructions
  humanPrompt?: string;                      // User-facing prompt template
  rawPrompt?: string;                        // Raw prompt text
  inputSchema: Record<string, any>;          // JSON Schema for input variables
  outputSchema?: Record<string, any>;        // JSON Schema for expected output
  metadata?: Record<string, any>;            // Arbitrary metadata
  tags?: string[];                           // Organization tags
  createdBy?: string;                        // Creator email
  createdAt: string;                         // ISO 8601 timestamp
  updatedAt: string;                         // ISO 8601 timestamp
}
```

## Quick Example

<CodeGroup>
  ```typescript SDK theme={null}
  import { Mutagent } from '@mutagent/sdk';

  const client = new Mutagent({ apiKey: process.env.MUTAGENT_API_KEY });

  // Create a prompt with rawPrompt content type
  const prompt = await client.prompt.createPrompt({
    name: 'Customer Support',
    rawPrompt: `You are a support agent for {company_name}.

  Help the customer with their question:
  {customer_question}

  Be helpful, professional, and concise.`,
    inputSchema: {
      company_name: { type: 'string' },
      customer_question: { type: 'string' },
    },
    description: 'Main customer support prompt template',
  });

  console.log('Created prompt:', prompt.id);
  ```

  ```bash CLI theme={null}
  # Create with raw prompt text
  mutagent prompts create \
    --name "Customer Support" \
    --raw "You are a support agent for {company_name}. Help with: {customer_question}"

  # Create with system + human prompts
  mutagent prompts create \
    --name "Customer Support" \
    --system "You are a support agent for {company_name}." \
    --human "Help the customer with: {customer_question}"

  # Create with raw prompt text
  mutagent prompts create \
    --name "Customer Support" \
    --raw "Help the customer with their request."
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.mutagent.io/api/prompt \
    -H "x-api-key: mt_xxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Customer Support",
      "rawPrompt": "You are a support agent for {company_name}...",
      "inputSchema": {
        "company_name": {"type": "string"},
        "customer_question": {"type": "string"}
      }
    }'
  ```
</CodeGroup>

<Tip>
  The CLI warns if you accidentally use double-brace `{{variable}}` syntax. MutagenT uses single-brace `{variable}` syntax for template variables.
</Tip>

## Prompt Organization

Organize prompts effectively within your workspace:

<AccordionGroup>
  <Accordion title="Naming Conventions">
    Use clear, descriptive names that indicate the prompt's purpose:

    * `customer-support-v1`
    * `code-review-assistant`
    * `data-extraction-json`
  </Accordion>

  <Accordion title="Use Descriptions">
    Add descriptions to document:

    * What the prompt does
    * Expected inputs and outputs
    * Any special considerations
  </Accordion>

  <Accordion title="Group Related Prompts">
    Use consistent naming prefixes for related prompts:

    * `support-*` for customer support
    * `sales-*` for sales workflows
    * `internal-*` for internal tools
  </Accordion>

  <Accordion title="Use Input/Output Schemas">
    Define `inputSchema` and `outputSchema` as JSON Schema objects to document expected parameters and responses:

    ```json theme={null}
    {
      "inputSchema": {
        "customer_name": {"type": "string"},
        "order_id": {"type": "string"}
      },
      "outputSchema": {
        "action": {"type": "string", "enum": ["refund", "replace", "escalate"]},
        "response": {"type": "string"}
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Versioning" icon="code-branch" href="/platform/prompts/versioning">
    Learn how to track and manage prompt versions
  </Card>

  <Card title="Variables" icon="brackets-curly" href="/platform/prompts/variables">
    Create dynamic prompts with template variables
  </Card>
</CardGroup>