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

> Manage prompts with the Python SDK

# Prompts SDK

Manage prompts programmatically. All methods are available on both `client.prompt` (sync) and `(await) client.prompt` for the async client.

## List Prompts

```python theme={null}
from mutagent import Mutagent

with Mutagent() as client:
    result = client.prompt.list_prompts()
    for p in result.get("data", []):
        print(p["name"], "v" + p["version"])
```

Filter by name, version, `is_latest`, or creator:

```python theme={null}
result = client.prompt.list_prompts(
    name="support",
    is_latest=True,
    created_by="user@example.com",
    limit=20,
    offset=0,
)
```

## Create Prompt

MutagenT supports three prompt formats. Use `raw_prompt` for plain text, `human_prompt` for template-based prompts, or `system_prompt` + `human_prompt` for structured prompts. The `name` and `input_schema` fields are required.

<CodeGroup>
  ```python Structured (System + Human) theme={null}
  from mutagent import Mutagent
  from mutagent.models import NameDescriptionVersion

  with Mutagent() as client:
      prompt = client.prompt.create_prompt(
          NameDescriptionVersion(
              name="Support Assistant",
              system_prompt="You are a helpful support agent for {company}.",
              human_prompt="The customer asks: {question}",
              description="Customer support prompt",
              input_schema={
                  "type": "object",
                  "properties": {
                      "company": {"type": "string"},
                      "question": {"type": "string"},
                  },
              },
              tags=["production", "support"],
          )
      )
      print("Created:", prompt["id"])
  ```

  ```python Human Prompt Only theme={null}
  from mutagent import Mutagent
  from mutagent.models import NameDescriptionVersion

  with Mutagent() as client:
      prompt = client.prompt.create_prompt(
          NameDescriptionVersion(
              name="Summarizer",
              human_prompt="Summarize the following text:\n\n{text}",
              input_schema={
                  "type": "object",
                  "properties": {"text": {"type": "string"}},
              },
          )
      )
  ```

  ```python Raw Prompt theme={null}
  from mutagent import Mutagent
  from mutagent.models import NameDescriptionVersion

  with Mutagent() as client:
      prompt = client.prompt.create_prompt(
          NameDescriptionVersion(
              name="Simple Greeting",
              raw_prompt="Hello, welcome to our service!",
              input_schema={},
          )
      )
  ```
</CodeGroup>

<Note>
  Template variables use single braces: `{variable}`. Define matching keys in `input_schema` for validation.
</Note>

### `NameDescriptionVersion` fields

| Field           | Type        | Required | Description                        |
| --------------- | ----------- | -------- | ---------------------------------- |
| `name`          | `str`       | Yes      | Prompt name (max 255 chars)        |
| `input_schema`  | `Any`       | Yes      | JSON Schema for template variables |
| `description`   | `str`       | No       | Human-readable description         |
| `version`       | `str`       | No       | Semantic version string            |
| `is_latest`     | `bool`      | No       | Mark this version as latest        |
| `system_prompt` | `str`       | No       | System prompt text                 |
| `human_prompt`  | `str`       | No       | Human prompt template              |
| `raw_prompt`    | `str`       | No       | Plain text prompt                  |
| `messages`      | `list`      | No       | Chat message array                 |
| `output_schema` | `Any`       | No       | JSON Schema for expected output    |
| `metadata`      | `Any`       | No       | Arbitrary metadata                 |
| `tags`          | `list[str]` | No       | Classification tags                |

## Get Prompt by ID

```python theme={null}
with Mutagent() as client:
    prompt = client.prompt.get_prompt(id_=123)
    print(prompt["name"], "v" + prompt["version"])
```

## Update Prompt

```python theme={null}
from mutagent.models import NameDescriptionIsLatest

with Mutagent() as client:
    updated = client.prompt.update_prompt(
        id_=123,
        body=NameDescriptionIsLatest(
            description="Updated description",
            human_prompt="Revised prompt for {company}.",
            is_latest=True,
            tags=["production", "v2"],
        ),
    )
```

## Delete Prompt

```python theme={null}
with Mutagent() as client:
    client.prompt.delete_prompt(id_=123)

    # Force-delete (even if it has dataset items associated)
    client.prompt.delete_prompt(id_=123, force=True)
```

## Create New Version

Create a new version of an existing prompt. The `new_version` field is required.

```python theme={null}
from mutagent.models import NewVersionChanges, NameDescriptionIsLatest

with Mutagent() as client:
    new_version = client.prompt.create_prompt_version(
        id_=123,
        body=NewVersionChanges(
            new_version="2.0.0",
            changes=NameDescriptionIsLatest(
                human_prompt="Improved prompt for {company}: {question}",
                is_latest=True,
            ),
        ),
    )
    print("New version:", new_version["version"])
```

## List Prompt Versions

```python theme={null}
with Mutagent() as client:
    versions = client.prompt.list_prompt_versions(id_=123)
```

## List Prompt Tags

```python theme={null}
with Mutagent() as client:
    tags = client.prompt.list_prompt_tags()
```

## Async Version

All methods are also available on `AsyncMutagent`:

```python theme={null}
import asyncio
from mutagent import AsyncMutagent
from mutagent.models import NameDescriptionVersion

async def main():
    async with AsyncMutagent() as client:
        prompt = await client.prompt.create_prompt(
            NameDescriptionVersion(
                name="Support Assistant",
                raw_prompt="You are a helpful assistant for {company}.",
                input_schema={"type": "object", "properties": {"company": {"type": "string"}}},
            )
        )
        print("Created:", prompt["id"])

        result = await client.prompt.list_prompts()
        print("Total:", len(result.get("data", [])))

asyncio.run(main())
```

## Prompt Lifecycle

<Mermaid>
  flowchart LR
  A\[create\_prompt] --> B\[Prompt v1.0.0]
  B --> C\[update\_prompt]
  C --> D\[Updated Prompt]
  B --> E\[create\_prompt\_version]
  E --> F\[Prompt v2.0.0]
  F --> G\[is\_latest: True]
</Mermaid>

## Method Reference

| Method                             | Description                   | Namespace       |
| ---------------------------------- | ----------------------------- | --------------- |
| `list_prompts(...)`                | List all prompts with filters | `client.prompt` |
| `create_prompt(body)`              | Create a new prompt           | `client.prompt` |
| `get_prompt(id_)`                  | Get prompt by ID              | `client.prompt` |
| `update_prompt(id_, body)`         | Update prompt fields          | `client.prompt` |
| `delete_prompt(id_, force?)`       | Delete prompt                 | `client.prompt` |
| `create_prompt_version(id_, body)` | Create new version            | `client.prompt` |
| `list_prompt_versions(id_)`        | List all versions of a prompt | `client.prompt` |
| `list_prompt_tags()`               | List all distinct tags        | `client.prompt` |