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

# prompt

## PromptVersion

Represents a single version of a prompt template.

## Attributes

id (str): The unique version identifier.
version (int): The version number (1-indexed).
messages (list\[Message]): The prompt messages for this version.
settings (PromptRunSettings | None): The prompt run settings.
created\_at (datetime | None): When the version was created.
updated\_at (datetime | None): When the version was last updated.

## Prompt

Object-centric interface for Splunk AO prompts.

This class provides an intuitive way to work with Splunk AO prompts,
encapsulating prompt management operations including version management.

**Arguments**

* `Known Limitations`:

* `-----------------`: Project Association: The API response schema (BasePromptTemplateResponse) does not
  include project association information. Therefore, `project_id` and `project_name`
  will only be populated for prompts created in the current session via `create()`.
  Prompts retrieved via `get()` or `list()` will have these attributes set to `None`,
  even if they were originally created with a project association.

**Examples**

# Create a new prompt locally, then persist

prompt = Prompt(
name="ml-expert-v1",
messages=\[
Message(role=MessageRole.system, content="You are an expert in ML."),
Message(role=MessageRole.user, content="\{\{input}}"),
],
).create()

# Create a prompt associated with a project

prompt = Prompt(
name="ml-expert-v1",
messages=\[...],
project\_name="My Project",
).create()

# Get an existing prompt

prompt = Prompt.get(name="ml-expert-v1")

# Create a new version with updated messages

prompt.create\_version(messages=\[...])

# List all versions

versions = prompt.list\_versions()

# Select a specific version

prompt.select\_version(2)

# Update prompt name only (use create\_version for content changes)

prompt.update(name="ml-expert-v2")

# Delete a prompt

prompt.delete()

### create

```python theme={null}
def create(self) -> Prompt
```

Persist this prompt to the API.

If project\_id or project\_name is set, associates the prompt with that project.
If neither is set, falls back to SPLUNK\_AO\_PROJECT\_ID or SPLUNK\_AO\_PROJECT env vars.

**Examples**

prompt = Prompt(name="test", messages=\[...]).create()
assert prompt.is\_synced()

### create\_version

```python theme={null}
def create_version(self, messages: builtins.list[Message] | None=None) -> Prompt
```

Create a new version of this prompt template.

This creates an actual new version in the prompt's version history,
not a separate prompt. The new version becomes the selected version.

**Arguments**

* `messages` (`Optional[list[Message]]`): Messages for the new version.
  If not provided, uses the current messages.

### delete

```python theme={null}
def delete(self) -> None
```

Delete this prompt.

**Examples**

prompt = Prompt.get(name="ml-expert-v1")
prompt.delete()

### get

```python theme={null}
def get(cls, *, id: str | None=None, name: str | None=None) -> Prompt | None
```

Get an existing prompt by ID or name.

**Arguments**

* `id` (`Optional[str]`): The prompt ID.
* `name` (`Optional[str]`): The prompt name.

### list

```python theme={null}
def list(cls,
         *,
         name_filter: str | None=None,
         limit: Unset | int=100,
         project_id: str | None=None,
         project_name: str | None=None) -> list[Prompt]
```

List global prompt templates with optional filtering.

**Arguments**

* `name_filter` (`Optional[str]`): Filter prompts by name containing this string.
* `limit` (`Union[Unset, int]`): Maximum number of prompts to return.
* `project_id` (`Optional[str]`): Filter prompts used in this project by ID.
* `project_name` (`Optional[str]`): Filter prompts used in this project by name.

### list\_versions

```python theme={null}
def list_versions(self) -> builtins.list[PromptVersion]
```

List all versions of this prompt template.

**Examples**

prompt = Prompt.get(name="ml-expert-v1")
versions = prompt.list\_versions()
for v in versions:
print(f"Version \{v.version}: \{len(v.messages)} messages")

**Notes**

This method returns `PromptVersion` objects instead of `Prompt` objects
to avoid an N+1 API call problem. Each version's full prompt data would require
a separate API call. To work with a specific version, use
`select_version(version_number)` which selects the version and updates
the prompt's messages and version attributes.

### refresh

```python theme={null}
def refresh(self) -> None
```

Refresh this prompt's state from the API.

Updates all attributes with the latest values from the remote API
and sets the state to SYNCED.

**Examples**

prompt.refresh()
assert prompt.is\_synced()

### save

```python theme={null}
def save(self) -> Prompt
```

Save this prompt to the API.

Behavior depends on the prompt's current state:

* LOCAL\_ONLY: Creates the prompt via create()
* SYNCED: No action needed, already saved
* DIRTY: Persists pending field changes via update()
* FAILED\_SYNC: Raises ValueError — use refresh() to recover or retry the original operation
* DELETED: Raises ValueError

For updating an existing prompt's messages, use create\_version(messages=\[...]) instead.

**Examples**

# Create and save a new prompt

prompt = Prompt(name="my-prompt", messages=\[...])
prompt.save()  # Creates the prompt

# Mutate a field and persist the change

prompt = Prompt.get(name="my-prompt")
prompt.name = "renamed-prompt"  # Transitions to DIRTY
prompt.save()  # Persists the rename via update()

### select\_version

```python theme={null}
def select_version(self, version: int) -> Prompt
```

Set a specific version as the selected/active version.

This updates the prompt's selected version, and the messages
will be updated to reflect the content of the selected version.

**Arguments**

* `version` (`int`): The version number to select (1-indexed).

### update

```python theme={null}
def update(self, *, name: str) -> Prompt
```

Update this prompt's name.

**Examples**

prompt = Prompt.get(name="ml-expert-v1")
prompt.update(name="ml-expert-v2")

# To update messages, use create\_version() instead:

prompt.create\_version(messages=\[
Message(role=MessageRole.system, content="Updated system message"),
Message(role=MessageRole.user, content="\{\{input}}"),
])

**Notes**

The API only supports updating the prompt name. To update messages,
use `create_version()` which creates a new immutable version.
This design ensures traceability and allows rollback to previous versions.

Args:
name (str): New name for the prompt.