Skip to main content

Fetch Prompts via SDK/API

This guide shows you how to fetch prompt configurations from variants or environments using the Agenta SDK.

Google Colaboratory

Open in Google Colaboratory

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 variant_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.

Find slugs in the web UI

You can copy any of these slugs directly from the Agenta web UI using the Copy Slug action:

  • App slug — app overview page → actions dropdown next to the app title → Copy Slug
  • Variant slug — registry table → row actions (⋯) → Copy Slug
  • Testset slug — testsets table → row actions (⋯) → Copy Slug
  • Evaluator slug — evaluators table → row actions (⋯) → Copy Slug

Each entity also has a Copy ID action in the same menu if you need the UUID instead.

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)

How the request resolves​

You can identify the revision you want with any combination of:

  • application_revision_ref — by id or slug, or by version paired with a application_variant_ref.
  • application_variant_ref — picks the latest revision on that variant.
  • application_ref — picks the latest revision on the application's default variant.
  • environment_ref (+ optional key) — picks the revision currently deployed to that environment under the default key {application_slug}.revision.

You may supply more than one reference. Every reference you send must agree with the resolved revision; if any contradicts, the endpoint returns 400 Bad Request and the response detail names the field that disagreed.

The endpoint also returns 400 when the references are not sufficient to identify a single revision — for example, when only application_revision_ref.version is provided (a per-variant sequence number with no variant context), or when only application_variant_ref.version is provided (variants do not have versions).

Response Format​

The SDK returns the configuration parameters directly as a dictionary. When using the REST API, the response contains the full revision data including configuration under params along with reference metadata:

{
  "params": {
    "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",
        "max_tokens": 150,
        "temperature": 0.7,
        "top_p": 1.0,
        "frequency_penalty": 0.0,
        "presence_penalty": 0.0
      },
      "template_format": "curly"
    }
  },
  "url": "https://cloud.agenta.ai/services/completion",
  "application_ref": {
    "slug": "my-app-slug",
    "id": "..."
  },
  "variant_ref": {
    "slug": "my-variant-slug",
    "version": 2,
    "id": "..."
  },
  "environment_ref": {
    "slug": "production",
    "version": 1,
    "id": "..."
  }
}
Asynchronous Operations in Python SDK

All SDK methods have async counterparts with an a prefix:

async def async_operations():
    # Fetch configuration asynchronously
    config = await ag.ConfigManager.aget_from_registry(...)