Run Prompt

result = client.prompts.run(slug, variables?, options?)
# Async
result = await client.prompts.arun(slug, variables?, options?)

class RunResult(BaseModel):
    text: str | None           # The generated text (None when only tool calls)
    span_id: str               # Unique span identifier
    trace_id: str              # Trace identifier for session grouping
    prompt_version: int        # Version of the prompt used
    latency_ms: int            # Request latency in milliseconds
    usage: TokenUsage
    cost: float                # Cost in USD
    finish_reason: FinishReason | None  # Why the model stopped ("stop", "length", "tool_calls")
    tool_calls: list[ToolCall] | None   # Tool calls made by the model
    structured_output: dict | None      # Structured output when using JSON schema
    messages: list[LocalPromptMessage] | None  # Full conversation for multi-turn continuation

result = client.prompts.run("welcome-email", {
    "name": "Alice",
    "product": "Tracia",
})

print(result.text)
# "Dear Alice, Welcome to Tracia!..."

from tracia import RunOptions

result = client.prompts.run(
    "welcome-email",
    {"name": "Alice", "product": "Tracia"},
    RunOptions(
        model="gpt-4",
        tags=["onboarding", "email"],
        user_id="user_123",
        session_id="session_abc",
    ),
)

from tracia import RunOptions

result = client.prompts.run(
    "welcome-email",
    {"name": "Alice", "product": "Tracia"},
    RunOptions(version=3),
)

print(result.prompt_version)  # 3

result = client.prompts.run("welcome-email", {"name": "Alice"})

print(f"Latency: {result.latency_ms}ms")
print(f"Tokens: {result.usage.total_tokens}")
print(f"Cost: ${result.cost:.4f}")
print(f"Span ID: {result.span_id}")
print(f"Prompt Version: {result.prompt_version}")

result = await client.prompts.arun("welcome-email", {"name": "Alice"})
print(result.text)

import json
from tracia import RunOptions, LocalPromptMessage

# 1. First call - model returns tool calls
result = client.prompts.run("assistant", {"question": "Weather in Tokyo?"})

if result.finish_reason == "tool_calls" and result.tool_calls:
    # 2. Execute tools locally
    weather_data = get_weather(result.tool_calls[0].arguments["location"])

    # 3. Continue with tool results
    result2 = client.prompts.run(
        "assistant",
        None,
        RunOptions(
            messages=[
                *result.messages,
                LocalPromptMessage(
                    role="tool",
                    tool_call_id=result.tool_calls[0].id,
                    tool_name="get_weather",
                    content=json.dumps(weather_data),
                ),
            ],
            trace_id=result.trace_id,
            parent_span_id=result.span_id,
        ),
    )

    print(result2.text)
    # "The weather in Tokyo is 22°C and sunny."

from tracia import RunOptions

result1 = client.prompts.run("step-1", {"input": "data"})

result2 = client.prompts.run(
    "step-2",
    {"input": result1.text},
    RunOptions(
        trace_id=result1.trace_id,
        parent_span_id=result1.span_id,
    ),
)

from tracia import TraciaError, TraciaErrorCode

try:
    result = client.prompts.run("welcome-email", {"name": "Alice"})
except TraciaError as error:
    if error.code == TraciaErrorCode.NOT_FOUND:
        print("Prompt does not exist")
    elif error.code == TraciaErrorCode.MISSING_VARIABLES:
        print("Missing required variables")
    elif error.code == TraciaErrorCode.PROVIDER_ERROR:
        print(f"LLM provider error: {error.message}")