PromptRails
View as Markdown

Quickstart

Get up and running with PromptRails in under 5 minutes. Install the SDK, create an API key, execute an agent, and view traces.

Quickstart

This guide walks you through installing the PromptRails SDK, creating an API key, executing your first agent, and viewing the execution trace.

Prerequisites

  • A PromptRails account
  • A workspace with at least one configured agent
  • An LLM credential (e.g., OpenAI API key) added to your workspace

Step 1: Install the SDK

Install the PromptRails SDK for your language of choice.

Python

pip install promptrails

JavaScript / TypeScript

npm install @promptrails/sdk

Go

go get github.com/promptrails/go-sdk

Step 2: Create an API Key

  1. Log in to the PromptRails dashboard
  2. Navigate to Settings > API Keys
  3. Click Create API Key
  4. Give it a name (e.g., "Development Key")
  5. Select the scopes you need. For this quickstart, select * (wildcard) to grant all permissions
  6. Copy the generated key -- it is only shown once

Step 3: Execute an Agent

Use the SDK to execute an agent. You will need the agent ID, which you can find in the dashboard under Agents.

Python

from promptrails import PromptRails
 
client = PromptRails(api_key="your-api-key-here")
 
# Execute an agent
result = client.agents.execute(
    agent_id="your-agent-id",
    input={
        "message": "What is the capital of France?"
    }
)
 
print(result["data"]["output"])

Python (async)

import asyncio
from promptrails import AsyncPromptRails
 
async def main():
    client = AsyncPromptRails(api_key="your-api-key-here")
 
    result = await client.agents.execute(
        agent_id="your-agent-id",
        input={
            "message": "What is the capital of France?"
        }
    )
 
    print(result["data"]["output"])
    await client.close()
 
asyncio.run(main())

JavaScript / TypeScript

import { PromptRails } from '@promptrails/sdk'
 
const client = new PromptRails({
  apiKey: 'your-api-key-here',
})
 
const result = await client.agents.execute('your-agent-id', {
  input: {
    message: 'What is the capital of France?',
  },
})
 
console.log(result.data.output)

Go

package main
 
import (
    "context"
    "fmt"
    "log"
 
    promptrails "github.com/promptrails/go-sdk"
)
 
func main() {
    client := promptrails.NewClient("your-api-key-here")
    ctx := context.Background()
 
    result, err := client.Agents.Execute(ctx, "your-agent-id", &promptrails.ExecuteAgentParams{
        Input: map[string]any{"message": "What is the capital of France?"},
        Sync:  true,
    })
    if err != nil {
        log.Fatal(err)
    }
 
    fmt.Println(result.Data.Output)
}

Step 4: View the Execution

After executing an agent, you can retrieve the execution details including status, output, token usage, and cost.

Python

# List recent executions
executions = client.executions.list(page=1, limit=10)
 
for execution in executions["data"]:
    print(f"ID: {execution['id']}")
    print(f"Status: {execution['status']}")
    print(f"Cost: ${execution['cost']:.6f}")
    print(f"Duration: {execution['duration_ms']}ms")
    print("---")

JavaScript / TypeScript

const executions = await client.executions.list({ page: 1, limit: 10 })
 
for (const execution of executions.data) {
  console.log(`ID: ${execution.id}`)
  console.log(`Status: ${execution.status}`)
  console.log(`Cost: $${execution.cost.toFixed(6)}`)
  console.log(`Duration: ${execution.duration_ms}ms`)
  console.log('---')
}

Go

executions, err := client.Executions.List(ctx, &promptrails.ListExecutionsParams{
    Page:  1,
    Limit: 10,
})
if err != nil {
    log.Fatal(err)
}
 
for _, exec := range executions.Data {
    fmt.Printf("ID: %s\n", exec.ID)
    fmt.Printf("Status: %s\n", exec.Status)
    fmt.Println("---")
}

Step 5: View Traces

Every execution produces a detailed trace showing the full execution flow, including LLM calls, tool invocations, guardrail evaluations, and more.

Python

# Get traces for a specific execution
traces = client.traces.list(execution_id="your-execution-id")
 
for span in traces["data"]:
    print(f"Span: {span['name']} ({span['kind']})")
    print(f"Status: {span['status']}")
    print(f"Duration: {span['duration_ms']}ms")
    if span.get("cost"):
        print(f"Cost: ${span['cost']:.6f}")
    print("---")

JavaScript / TypeScript

const traces = await client.traces.list({
  executionId: 'your-execution-id',
})
 
for (const span of traces.data) {
  console.log(`Span: ${span.name} (${span.kind})`)
  console.log(`Status: ${span.status}`)
  console.log(`Duration: ${span.duration_ms}ms`)
  if (span.cost) {
    console.log(`Cost: $${span.cost.toFixed(6)}`)
  }
  console.log('---')
}

Go

traces, err := client.Traces.List(ctx, &promptrails.ListTracesParams{
    ExecutionID: "your-execution-id",
})
if err != nil {
    log.Fatal(err)
}
 
for _, span := range traces.Data {
    fmt.Printf("Span: %s (%s)\n", span.Name, span.Kind)
    fmt.Printf("Status: %s\n", span.Status)
    fmt.Println("---")
}

Step 6: Use Chat Sessions

For multi-turn conversations, use the chat API to maintain conversation context across messages.

Python

# Create a chat session
session = client.chat.create_session(agent_id="your-agent-id")
 
# Send messages
response = client.chat.send_message(
    session.id,
    content="Hello, tell me about machine learning."
)
print(response.content)
 
# Continue the conversation
response = client.chat.send_message(
    session.id,
    content="Can you give me a specific example?"
)
print(response.content)

JavaScript / TypeScript

// Create a chat session
const session = await client.chat.createSession({
  agentId: 'your-agent-id',
})
 
// Send messages
const response = await client.chat.sendMessage(session.id, {
  content: 'Hello, tell me about machine learning.',
})
console.log(response.content)
 
// Continue the conversation
const followUp = await client.chat.sendMessage(session.id, {
  content: 'Can you give me a specific example?',
})
console.log(followUp.content)

Next Steps

Now that you have executed your first agent, explore these topics to build more sophisticated AI applications:

  • Agents -- Learn about the five agent types and how to configure them
  • Prompts -- Manage versioned prompts with Jinja2 templating
  • Guardrails -- Add safety scanners to your agents
  • MCP Tools -- Give your agents access to external tools
  • Tracing -- Deep-dive into execution observability
  • API Keys and Scopes -- Configure fine-grained access control
PreviousIntroductionNextAgents