Skip to main content
Version: v1.0

Version Prompts

This guide covers how to create variants and commit changes to them using the Agenta SDK.

Google Colaboratory

Open in Google Colaboratory

Creating and Managing Variants​

REST API usage

The REST endpoints used below identify applications, variants, and revisions by UUID. When you only have a slug, resolve it with a prior call to POST /api/applications/query (each example below shows the resolve step inline). The Python SDK handles this automatically.

Create a New Variant​

Use VariantManager.create to create a new variant with initial configuration:

from agenta.sdk.types import PromptTemplate, Message, ModelConfig
from pydantic import BaseModel

# Define your configuration model
class Config(BaseModel):
    prompt: PromptTemplate

# Create the initial configuration
config = Config(
    prompt=PromptTemplate(
        messages=[
            Message(role="system", content="You are an assistant that provides concise answers"),
            Message(role="user", content="Explain {{topic}} in simple terms"),
        ],
        llm_config=ModelConfig(
            model="gpt-3.5-turbo",
            max_tokens=150,
            temperature=0.7,
            top_p=1.0,
            frequency_penalty=0.0,
            presence_penalty=0.0,
        ),
    )
)

# Create the variant
variant = ag.VariantManager.create(
    parameters=config.model_dump(),
    app_slug="my-app-slug",
    variant_slug="my-variant-slug",
)
tip

Use VariantManager.acreate for async variant creation.

This command will create a new variant and initialize it with the first commit containing the parameters provided

  • Parameters:
    • app_slug: The slug of your application.
    • variant_slug: The slug of the new variant.
    • parameters: A dictionary containing the initial configuration parameters.

Note: If a variant with the same slug and version already exists, the SDK will raise an exception.

Sample Output:

{
  "messages": [
    {
      "role": "system",
      "content": "You are an assistant that provides concise answers"
    },
    {
      "role": "user",
      "content": "Explain {{topic}} in simple terms"
    }
  ],
  "llm_config": {
    "model": "gpt-3.5-turbo",
    "max_tokens": 150,
    "temperature": 0.7,
    "top_p": 1.0,
    "frequency_penalty": 0.0,
    "presence_penalty": 0.0
  },
  "template_format": "curly"
}

Committing changes to a variant (Creating a new version in a variant)​

To save changes to a variant (creating a new version), use the VariantManager.commit method with explicit parameters.


config2=Config(
    prompt=PromptTemplate(
        messages=[
            Message(role="system", content="You are an assistant that provides VERY concise answers"),
            Message(role="user", content="Explain {{topic}} in simple terms"),
        ],
        llm_config=ModelConfig(
            model="anthropic/claude-3-5-sonnet-20240620",
            max_tokens=150,
            temperature=0.7,
            top_p=1.0,
            frequency_penalty=0.0,
            presence_penalty=0.0,
        ),
    )
)


# Commit the new version
variant = ag.VariantManager.commit(
    parameters=config2.model_dump(),
    app_slug="my-app-slug",
    variant_slug="my-variant-slug",
)

print("Committed new version of variant:")
print(variant)

# Commit the new version asynchronously (optional)
# async def commit_variant():
#     variant = await ag.VariantManager.acommit(
#         parameters=my_prompt2.model_dump(),
#         app_slug="my-app-slug",
#         variant_slug="my-variant-slug",
#     )

#     print("Committed new version of variant (async):")
#     print(variant)
tip

Use VariantManager.acommit for async version commit.

Immutability

Each commit creates a new version of the variant. Versions are immutable once created.

Sample Output:

{
    "app_id": "01963413-3d39-7650-80ce-3ad5d688da6c",
    "app_slug": "my-app-slug",
    "variant_id": "01968c11-6f7c-7773-b273-922c5807be7b",
    "variant_slug": "my-variant-slug",
    "variant_version": 5,
    "environment_id": null,
    "environment_slug": null,
    "environment_version": null,
    "committed_at": "2025-05-01T07:26:08.935406+00:00",
    "committed_by": "user@agenta.ai",
    "committed_by_id": "0196247a-ec9d-7051-8880-d58279570aa1",
    "deployed_at": null,
    "deployed_by": null,
    "deployed_by_id": null,
    "params": {
        "messages": [
            {
                "name": null,
                "role": "system",
                "content": "You are an assistant that provides concise answers",
                "tool_calls": null,
                "tool_call_id": null
            },
            {
                "name": null,
                "role": "user",
                "content": "Explain {{topic}} in simple terms",
                "tool_calls": null,
                "tool_call_id": null
            }
        ],
        "input_keys": null,
        "llm_config": {
            "model": "gpt-3.5-turbo",
            "tools": null,
            "top_p": 1.0,
            "stream": null,
            "max_tokens": 150,
            "temperature": 0.7,
            "tool_choice": null,
            "response_format": null,
            "presence_penalty": 0.0,
            "frequency_penalty": 0.0
        },
        "user_prompt": null,
        "system_prompt": null,
        "template_format": "curly"
    }
}
warning

The user_prompt and system_prompt are helper fields to populate the messages field in the PromptTemplate. Rely only on the messages field in your code.

Deploying to Environments​

To deploy a variant to an environment, use the DeploymentManager.deploy method with the variant reference and environment_slug: The slug of the environment (development, staging, or production).

deployment = ag.DeploymentManager.deploy(
    app_slug="my-app-slug",
    variant_slug="my-variant-slug",
    variant_version=None,  # Deploys latest version if not specified
    environment_slug="staging"  # Options: development, staging, production
)

print(f"Deployed to {deployment['environment_slug']}")
warning
  • Omitting the revision (SDK variant_version, REST application_revision_ref) deploys the latest revision of the variant.
  • Only predefined environments with slugs development, staging, and production are currently supported.

Sample Output:

Deployed variant to environment:
{
    "app_id": "01963413-3d39-7650-80ce-3ad5d688da6c",
    "app_slug": "completion",
    "variant_id": "01968c11-6f7c-7773-b273-922c5807be7b",
    "variant_slug": "my-variant-slug4",
    "variant_version": 5,
    "environment_id": "01968c14-c35d-7440-bcc8-9def594f017f",
    "environment_slug": "staging",
    "environment_version": 2,
    "committed_at": "2025-05-01T07:26:08.935406+00:00",
    "committed_by": "user@agenta.ai",
    "committed_by_id": "0196247a-ec9d-7051-8880-d58279570aa1",
    "deployed_at": "2025-05-01T13:41:33.149595+00:00",
    "deployed_by": "user@agenta.ai",
    "deployed_by_id": "0196247a-ec9d-7051-8880-d58279570aa1"
}

Fetching a Prompt Configuration​

You can fetch the configurations from a variant reference (app_slug, variant_slug, variant_version) or an environment reference (app_slug, environment_slug). The default behavior when fetching is to fetch the latest configuration from the production environment. If you don't provide a _version parameter but only a variant_slug or an environment_slug, the SDK will fetch the latest version of the variant from the specified environment/variant.

Understanding the PromptTemplate​

When you fetch a prompt configuration, you receive a PromptTemplate object. This object contains all the information needed to format and send your prompt to an LLM provider.

The PromptTemplate includes:

  • messages: An ordered list of chat messages with roles and content
  • llm_config: Model parameters like temperature, max tokens, and the model name
  • template_format: The syntax used for variable placeholders in your prompt
  • input_keys: An optional list of required variables for input validation

Here's what a fetched configuration looks like:

config = ag.ConfigManager.get_from_registry(
    app_slug="my-app-slug"
)

print(config)
# Output:
# {
#   "prompt": {
#     "messages": [
#       {"role": "system", "content": "You are a helpful assistant"},
#       {"role": "user", "content": "Explain {{topic}} in simple terms"}
#     ],
#     "llm_config": {
#       "model": "gpt-3.5-turbo",
#       "temperature": 0.7,
#       "max_tokens": 150
#     },
#     "template_format": "curly"
#   }
# }

Template Format​

The template_format field determines how Agenta replaces variable placeholders in your prompts. Agenta supports three formats:

Curly format (default): Uses double curly braces like {{variable}}. This format is simple and safe. It only replaces variables that were defined in your original template, which helps catch missing inputs early.

"Explain {{topic}} in {{language}}"

Jinja2 format: Uses Jinja2 syntax like {{ variable }} and supports advanced features like loops and filters. Choose this format when you need conditional logic or want to transform variables.

"{% if variable %}...{% endif %}"
tip

Check the reference section for more details on the data format used for prompts.

Default Behavior when fetching​

If you don't provide either variant or environment identifiers, the SDK fetches the latest configuration deployed to the production environment.

config = ag.ConfigManager.get_from_registry(
    app_slug="my-app-slug",
    variant_slug="my-variant-slug",
    variant_version=2  # Optional: fetches latest if not provided
)

print("Fetched configuration from production:")
print(config)

Example Output:

{
  "prompt": {
    "messages": [
      {
        "role": "system",
        "content": "You are an assistant that provides concise answers"
      },
      {
        "role": "user",
        "content": "Explain {{topic}} in simple terms"
      }
    ],
    "llm_config": {
      "model": "gpt-3.5-turbo",
      "top_p": 1.0,
      "max_tokens": 150,
      "temperature": 0.7,
      "presence_penalty": 0.0,
      "frequency_penalty": 0.0
    },
    "template_format": "curly"
  }
}
tip

Agenta provides a helper class PromptTemplate to format the configuration and then use it to generate the prompt.

from openai import OpenAI
from agenta.sdk.types import PromptTemplate

# Fetch configuration
config = ag.ConfigManager.get_from_registry(
    app_slug="my-app-slug"
)

# Format the prompt with variables
prompt = PromptTemplate(**config['prompt']).format(topic="AI")

# Use with OpenAI
client = OpenAI()
response = client.chat.completions.create(
    **prompt.to_openai_kwargs()
)

print(response.choices[0].message.content)

Fetching by Variant Reference​

# Fetch configuration by variant
config = ag.ConfigManager.get_from_registry(
    app_slug="my-app-slug",
    variant_slug="my-variant-slug",
    variant_version=2  # Optional: If not provided, fetches the latest version
)

print("Fetched configuration:")
print(config)

Fetching by Environment Reference​

# Fetch the latest configuration from the staging environment
config = ag.ConfigManager.get_from_registry(
    app_slug="my-app",
    environment_slug="staging",
    environment_version=1  # Optional: If not provided, fetches the latest version
)

print("Fetched configuration from staging:")
print(config)

Deleting a Variant​

To delete a variant, use the VariantManager.delete method.

# Delete a variant
ag.VariantManager.delete(
    app_slug="my-app",
    # app_id="my-app-id",  # you can also use `app_id`
    variant_slug="obsolete-variant"
)

print("Variant deleted successfully.")
info

Archiving is a soft delete. The variant is hidden from queries (unless include_archived: true is passed) and can be restored with POST /applications/variants/{variant_id}/unarchive.

warning
  • Archiving a variant hides all of its revisions.
  • Attempting to archive a variant that is deployed to an environment will fail.

Listing All Variants​

To list all variants of an application, use the VariantManager.list method.

# List all variants (syncrhonously)
variants = ag.VariantManager.list(
    app_slug="my-app"
    # app_id="my-app-id",  # you can also use `app_id`
)

print(variants)

Sample Output:


[{
    "app_id": "01963413-3d39-7650-80ce-3ad5d688da6c",
    "app_slug": "completion",
    "variant_id": "01968aba-9702-7263-a7fd-8b8565753230",
    "variant_slug": "my-variant-slug3",
    "variant_version": 2,
    "environment_id": null,
    "environment_slug": null,
    "environment_version": null,
    "committed_at": "2025-05-01T07:23:26.338901+00:00",
    "committed_by": "user@agenta.ai",
    "committed_by_id": "0196247a-ec9d-7051-8880-d58279570aa1",
    "deployed_at": null,
    "deployed_by": null,
    "deployed_by_id": null,
    "params": {
        "prompt": {
            "messages": [
                {
                    "name": null,
                    "role": "system",
                    "content": "You are an assistant that provides concise answers",
                    "tool_calls": null,
                    "tool_call_id": null
                },
                {
                    "name": null,
                    "role": "user",
                    "content": "Explain {{topic}} in simple terms",
                    "tool_calls": null,
                    "tool_call_id": null
                }
            ],
            "input_keys": null,
            "llm_config": {
                "model": "gpt-3.5-turbo",
                "tools": null,
                "top_p": 1.0,
                "stream": null,
                "max_tokens": 150,
                "temperature": 0.7,
                "tool_choice": null,
                "response_format": null,
                "presence_penalty": 0.0,
                "frequency_penalty": 0.0
            },
            "user_prompt": null,
            "system_prompt": null,
            "template_format": "curly"
        }
    }
}, {
    "app_id": "01963413-3d39-7650-80ce-3ad5d688da6c",
    "app_slug": "completion",
    "variant_id": "01963f1f-28ea-78e1-b390-39d270fe93fe",
    "variant_slug": "key",
    "variant_version": 4,
    "environment_id": null,
    "environment_slug": null,
    "environment_version": null,
    "committed_at": "2025-04-16T15:02:08.874979+00:00",
    "committed_by": "user@agenta.ai",
    "committed_by_id": "0196247a-ec9d-7051-8880-d58279570aa1",
    "deployed_at": null,
    "deployed_by": null,
    "deployed_by_id": null,
    "params": {
        "ag_config": {
            "prompt": {
                "messages": [
                    {
                        "role": "system",
                        "content": "You are an expert in geography"
                    },
                    {
                        "role": "user",
                        "content": "What is the capital of {{country}}? tell me its name in arabic"
                    }
                ],
                "input_keys": [
                    "country"
                ],
                "llm_config": {
                    "model": "gpt-3.5-turbo"
                },
                "template_format": "curly"
            }
        }
    }
}]

Fetching a Variant's History​

To list all versions for a variant of an application, use the VariantManager.history method.

# List all variant versions/history (synchronously)
versions = ag.VariantManager.history(
    variant_slug="variant-slug",
    app_slug="my-app"
    # app_id="my-app-id",  # you can also use `app_id`
)

print(versions)

Sample Output:

Same as VariantManager.list but limited to the history of a specific variant.

Asynchronous Operations in Python SDK

All SDK methods have async counterparts with an a prefix:

async def async_operations():
    # Create variant asynchronously
    variant = await ag.VariantManager.acreate(...)

    # Commit changes asynchronously
    updated_variant = await ag.VariantManager.acommit(...)
On this page