# Quickstart

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

Source: https://0.0.0.0:8080/docs/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**

```bash
pip install promptrails
```

**JavaScript / TypeScript**

```bash
npm install @promptrails/sdk
```

**Go**

```bash
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**

```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)**

```python
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**

```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**

```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**

```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**

```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**

```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**

```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**

```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**

```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**

```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**

```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](/docs/agents) -- Learn about the five agent types and how to configure them
- [Prompts](/docs/prompts) -- Manage versioned prompts with Jinja2 templating
- [Guardrails](/docs/guardrails) -- Add safety scanners to your agents
- [MCP Tools](/docs/mcp-tools) -- Give your agents access to external tools
- [Tracing](/docs/tracing) -- Deep-dive into execution observability
- [API Keys and Scopes](/docs/api-keys-and-scopes) -- Configure fine-grained access control