Python SDK

from promptrails import PromptRails
 
client = PromptRails(
    api_key="your-api-key",
    base_url="https://api.promptrails.ai",  # default
    timeout=30.0,                             # seconds, default
    max_retries=3                             # default
)

from promptrails import AsyncPromptRails
 
client = AsyncPromptRails(
    api_key="your-api-key",
    base_url="https://api.promptrails.ai",
    timeout=30.0,
    max_retries=3
)

# Sync
with PromptRails(api_key="your-api-key") as client:
    result = client.agents.list()
 
# Async
async with AsyncPromptRails(api_key="your-api-key") as client:
    result = await client.agents.list()

agents = client.agents.list(page=1, limit=20)
 
for agent in agents["data"]:
    print(f"{agent['name']} ({agent['type']})")

prompt = client.prompts.create(
    name="Summarizer",
    description="Summarizes text"
)
 
version = client.prompts.create_version(
    prompt_id=prompt["data"]["id"],
    system_prompt="You are a concise summarizer.",
    user_prompt="Summarize: {{ text }}",
    temperature=0.5,
    message="Initial version"
)

session = client.chat.create_session(agent_id="agent-id")
 
response = client.chat.send_message(
    session.id,
    content="What is PromptRails?"
)
print(response.content)

from promptrails import (
    ContentEvent,
    DoneEvent,
    ErrorEvent,
    ExecutionEvent,
    ThinkingEvent,
    ToolEndEvent,
    ToolStartEvent,
)
 
session = client.chat.create_session(agent_id="agent-id")
 
for event in client.chat.send_message_stream(
    session.id, content="What is PromptRails?"
):
    if isinstance(event, ExecutionEvent):
        print("execution_id:", event.execution_id)
    elif isinstance(event, ThinkingEvent):
        print("[thinking]", event.content)
    elif isinstance(event, ToolStartEvent):
        print("[tool_start]", event.name)
    elif isinstance(event, ToolEndEvent):
        print("[tool_end]", event.name, event.summary)
    elif isinstance(event, ContentEvent):
        print(event.content, end="", flush=True)
    elif isinstance(event, DoneEvent):
        print("\n[done]", event.token_usage)
    elif isinstance(event, ErrorEvent):
        print("[error]", event.message)
        break

async for event in aclient.chat.send_message_stream(
    session.id, content="hello"
):
    ...

for event in client.executions.stream(execution_id):
    if isinstance(event, ContentEvent):
        print(event.content, end="", flush=True)
    elif isinstance(event, DoneEvent):
        break

results = client.memories.search(
    agent_id="agent-id",
    query="refund policy",
    limit=5
)

client.scores.create(
    trace_id="trace-id",
    name="quality",
    data_type="numeric",
    value=4.5,
    source="manual"
)

client.approvals.decide(
    approval_id="approval-id",
    decision="approved",
    reason="Looks good"
)

from promptrails import (
    ChainAgentConfig,
    PromptLink,
    SimpleAgentConfig,
)
 
# Simple agent — one prompt per execution
simple = SimpleAgentConfig(
    prompt_id="prompt-id",
    approval_required=False,
)
 
# Chain agent — prompts run sequentially
chain = ChainAgentConfig(
    prompt_ids=[
        PromptLink(prompt_id="p1", role="step1", sort_order=0),
        PromptLink(prompt_id="p2", role="step2", sort_order=1),
    ],
)
 
client.agents.create_version(
    agent_id="agent-id",
    version="1.0.0",
    config=simple,
    set_current=True,
)

from promptrails.tracing import Tracer
 
tracer = Tracer(api_key="pr_...")
 
with tracer.span("agent-run", kind="agent") as root:
    root.set_input({"q": "weather?"})
    with tracer.span("llm-call", kind="llm") as llm:
        llm.set_model("gpt-4o").set_usage(prompt_tokens=120, completion_tokens=30)
 
tracer.flush()

pip install "promptrails[langchain]"   # or [openai], [anthropic], [google], [otel]

# LangChain
from promptrails.tracing.integrations.langchain import PromptRailsCallbackHandler
chain.invoke(inputs, config={"callbacks": [PromptRailsCallbackHandler(tracer)]})
 
# OpenAI
from promptrails.tracing.integrations.openai import trace_openai
client = trace_openai(OpenAI(), tracer)
 
# Anthropic
from promptrails.tracing.integrations.anthropic import trace_anthropic
client = trace_anthropic(Anthropic(), tracer)
 
# Google GenAI
from promptrails.tracing.integrations.google import trace_google
client = trace_google(genai.Client(), tracer)

from promptrails import VERSION
print(VERSION)  # "0.7.0"

from promptrails.exceptions import (
    PromptRailsError,
    ValidationError,
    UnauthorizedError,
    ForbiddenError,
    NotFoundError,
    RateLimitError,
    ServerError,
)
 
try:
    result = client.agents.execute(agent_id="invalid-id", input={})
except NotFoundError as e:
    print(f"Agent not found: {e.message}")
except ValidationError as e:
    print(f"Invalid input: {e.message}")
    print(f"Details: {e.details}")
except RateLimitError as e:
    print(f"Rate limited: {e.message}")
except UnauthorizedError as e:
    print(f"Invalid API key: {e.message}")
except ForbiddenError as e:
    print(f"Insufficient permissions: {e.message}")
except ServerError as e:
    print(f"Server error ({e.status_code}): {e.message}")
except PromptRailsError as e:
    print(f"Unexpected error: {e.message}")

import asyncio
from promptrails import AsyncPromptRails
 
async def main():
    async with AsyncPromptRails(api_key="your-api-key") as client:
        # All methods are awaitable
        agents = await client.agents.list()
 
        result = await client.agents.execute(
            agent_id=agents["data"][0]["id"],
            input={"message": "Hello"}
        )
 
        print(result["data"]["output"])
 
asyncio.run(main())

# Page-based pagination
page1 = client.agents.list(page=1, limit=20)
page2 = client.agents.list(page=2, limit=20)