🍰 PromptLayer

Version, test, and monitor every prompt and agent with robust evals, tracing, and regression sets.

This library provides convenient access to the PromptLayer API from applications written in python.

pip install promptlayer

Optional extras (learn more):

pip install "promptlayer[openai-agents]"
pip install "promptlayer[claude-agents]"

To follow along, you need a PromptLayer API key. Once logged in, go to Settings to generate a key.

Create a client and fetch a prompt template from PromptLayer:

from promptlayer import PromptLayer

pl = PromptLayer(api_key="pl_xxxxx")

prompt = pl.templates.get(
    "support-reply",
    {
        "input_variables": {
            "customer_name": "Ada",
            "question": "How do I reset my password?",
        }
    },
)

print(prompt["prompt_template"])

Async client:

import asyncio

from promptlayer import AsyncPromptLayer


async def main():
    pl = AsyncPromptLayer(api_key="pl_xxxxx")

    prompt = await pl.templates.get(
        "support-reply",
        {
            "input_variables": {
                "customer_name": "Ada",
                "question": "How do I reset my password?",
            }
        },
    )

    print(prompt["prompt_template"])


asyncio.run(main())

Every method has an async version.

You can also use the client as a proxy around supported provider SDKs:

from promptlayer import PromptLayer

pl = PromptLayer(api_key="pl_xxxxx")
openai = pl.openai

response = openai.chat.completions.create(
    model="gpt-4.1-mini",
    messages=[{"role": "user", "content": "Say hello in one short sentence."}],
    pl_tags=["proxy-example"],
)

PromptLayer(...) and AsyncPromptLayer(...) accept these parameters:

• api_key: str | None = None: Your PromptLayer API key. If omitted, the SDK looks for PROMPTLAYER_API_KEY.
• enable_tracing: bool = False: Enables OpenTelemetry tracing export to PromptLayer.
• base_url: str | None = None: Overrides the PromptLayer API base URL. If omitted, the SDK uses PROMPTLAYER_BASE_URL or the default API URL.
• throw_on_error: bool = True: Controls whether SDK methods raise PromptLayer exceptions or return None for many API errors.
• cache_ttl_seconds: int = 0: Enables in-memory prompt-template caching when greater than 0.

The SDK relies on the following environment variables:

The main resources surfaced by PromptLayer and AsyncPromptLayer are:

Note: When tracing is enabled, spans are exported to PromptLayer using OpenTelemetry.

Optional modules that are imported directly rather than accessed through the client:

The SDK raises PromptLayerError as the base exception for SDK failures, with more specific subclasses for common API and validation cases.

By default, the clients raise these exceptions. If you initialize PromptLayer or AsyncPromptLayer with throw_on_error=False, many resource methods return None instead of raising on PromptLayer API errors.

When enabled, the SDK caches fetched prompt templates in memory for faster repeat reads, locally re-renders them with new variables, and falls back to stale cache on temporary API failures.

• Caching is disabled by default and is enabled by setting cache_ttl_seconds when creating PromptLayer or AsyncPromptLayer.
• The cache applies to prompt templates fetched through client.templates.get(...).
• Cached entries are stored in memory and keyed by prompt name, version, label, provider, and model.
• Requests that include metadata_filters or model_parameter_overrides bypass the cache.
• Templates that require server-side rendering behavior, such as placeholder messages or tool-variable expansion, are not cached for local rendering.
• If a cached template is stale and PromptLayer returns a transient error, the SDK can serve the stale cached version as a fallback.
• You can clear cached entries with client.invalidate(...) or client.templates.invalidate(...).