PromptRails
Sign inGet started →
View as Markdown

Go SDK

Use PromptRails from Go services with a small client for agents, prompts, executions, traces, and scores.

Best for

Engineers building against the API, SDKs, CLI, MCP, or local tooling

The official Go SDK for PromptRails provides a fully typed client for interacting with the PromptRails API from any Go application.

Use the Go SDK when a Go service needs to execute agents, send traces, inspect runs, or manage workspace resources from backend code. You do not need it for product-side experimentation; use Studio, chat, triggers, or Agent UI deployments first when the workflow can be tested without code.

For production services, keep the API key scoped to the operations the service actually performs and use traces to verify runtime behavior.

Installation

go get github.com/promptrails/go-sdk@v0.6.0

Requires Go 1.21 or later.

Current release: v0.6.0 — adds the standalone tracing package for sending spans to PromptRails from any code. See the changelog.

Technical detailsClient setup and resource reference

Client Initialization

import promptrails "github.com/promptrails/go-sdk"
 
client := promptrails.NewClient("your-api-key")

With Options

import (
    "time"
    promptrails "github.com/promptrails/go-sdk"
)
 
client := promptrails.NewClient("your-api-key",
    promptrails.WithBaseURL("https://api.promptrails.ai"),  // default
    promptrails.WithTimeout(30 * time.Second),               // default
    promptrails.WithMaxRetries(3),                           // default
)

Configuration

OptionTypeDefaultDescription
WithBaseURLstringhttps://api.promptrails.aiAPI base URL
WithTimeouttime.Duration30sHTTP request timeout
WithMaxRetriesint3Maximum retry attempts on 5xx

The API key is sent via the X-API-Key header with every request.

Available Resources

ResourceFieldDescription
Agentsclient.AgentsAgent CRUD, versioning, execution
Promptsclient.PromptsPrompt CRUD, versioning, execution
Executionsclient.ExecutionsExecution listing and details
Credentialsclient.CredentialsCredential management
Data Sourcesclient.DataSourcesData source CRUD, versioning, execution
Chatclient.ChatSend messages to chat sessions
Tracesclient.TracesTrace listing and filtering
Costsclient.CostsCost analysis and summaries
MCP Toolsclient.MCPToolsMCP tool management
Approvalsclient.ApprovalsApproval request management
Scoresclient.ScoresScoring and evaluation
A2Aclient.A2AAgent-to-Agent protocol
Agent Triggersclient.AgentTriggersAgent trigger management (generic webhook, Slack, Telegram, Teams, WhatsApp, schedule)

Common Operations

Execute an Agent

ctx := context.Background()
 
result, err := client.Agents.Execute(ctx, "agent-id", &promptrails.ExecuteAgentParams{
    Input: map[string]any{"message": "Hello, world!"},
    Sync:  true,
})
if err != nil {
    log.Fatal(err)
}
 
fmt.Println(result.Data.Output)
Technical detailsMore Go SDK operations

List Agents

agents, err := client.Agents.List(ctx, &promptrails.ListAgentsParams{
    Page:  1,
    Limit: 20,
})
if err != nil {
    log.Fatal(err)
}
 
for _, agent := range agents.Data {
    fmt.Printf("%s (%s)\n", agent.Name, agent.Type)
}

Create a Prompt

prompt, err := client.Prompts.Create(ctx, &promptrails.CreatePromptParams{
    Name:        "Summarizer",
    Description: "Summarizes text",
})
if err != nil {
    log.Fatal(err)
}
 
fmt.Println(prompt.Data.ID)

View Executions

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, Status: %s\n", exec.ID, exec.Status)
}

Approve an Execution

err := client.Approvals.Decide(ctx, "approval-id", &promptrails.DecideApprovalParams{
    Decision: "approved",
    Reason:   "Looks good",
})

Stream a Chat Turn

Chat.SendMessageStream posts a user message and returns a *ChatStream that yields typed events on the same HTTP connection. Cancel by cancelling ctx; always defer stream.Close().

session, err := client.Chat.CreateSession(ctx, &promptrails.CreateSessionParams{
    AgentID: "agent-id",
})
if err != nil {
    log.Fatal(err)
}
 
stream, err := client.Chat.SendMessageStream(ctx, session.ID, &promptrails.SendMessageParams{
    Content: "What is PromptRails?",
})
if err != nil {
    log.Fatal(err)
}
defer stream.Close()
 
for stream.Next() {
    switch e := stream.Event().(type) {
    case *promptrails.ExecutionEvent:
        log.Printf("execution_id: %s", e.ExecutionID)
    case *promptrails.ThinkingEvent:
        log.Printf("[thinking] %s", e.Content)
    case *promptrails.ToolStartEvent:
        log.Printf("[tool_start] %s", e.Name)
    case *promptrails.ToolEndEvent:
        log.Printf("[tool_end] %s (%s)", e.Name, e.Summary)
    case *promptrails.ContentEvent:
        fmt.Print(e.Content)
    case *promptrails.DoneEvent:
        fmt.Printf("\n[done] %d tokens\n", e.TokenUsage.TotalTokens)
    case *promptrails.ErrorEvent:
        log.Fatalf("[error] %s", e.Message)
    }
}
if err := stream.Err(); err != nil {
    log.Fatal(err)
}

Stream an Existing Execution

When an execution was started outside a chat (e.g. Agents.Execute), subscribe to its live event stream:

stream, err := client.Executions.Stream(ctx, executionID)
if err != nil {
    log.Fatal(err)
}
defer stream.Close()
 
for stream.Next() {
    if e, ok := stream.Event().(*promptrails.ContentEvent); ok {
        fmt.Print(e.Content)
    }
}
Technical detailsGo SDK advanced details

Typed Agent Config

Agents.CreateVersion takes a typed AgentConfig — an interface implemented by the five concrete variants. Each concrete type's MarshalJSON injects the required type discriminator.

import promptrails "github.com/promptrails/go-sdk"
 
// Simple agent — one prompt per execution
simple := promptrails.SimpleAgentConfig{
    PromptID: "prompt-id",
}
 
// Chain agent — prompts run sequentially
chain := promptrails.ChainAgentConfig{
    PromptIDs: []promptrails.PromptLink{
        {PromptID: "p1", Role: "step1", SortOrder: 0},
        {PromptID: "p2", Role: "step2", SortOrder: 1},
    },
}
 
_, err := client.Agents.CreateVersion(ctx, "agent-id", &promptrails.CreateVersionParams{
    Version:    "1.0.0",
    Config:     simple, // or chain, MultiAgentConfig, WorkflowAgentConfig, CompositeAgentConfig
    SetCurrent: true,
})

See Agent Versioning for the per-type field reference.

Tracing

The github.com/promptrails/go-sdk/tracing package sends spans to PromptRails from any code, without managing your prompts or agents on the platform. It depends only on the standard library and needs an API key with the traces:write scope.

import "github.com/promptrails/go-sdk/tracing"
 
tracer := tracing.NewTracer("pr_...")
defer tracer.Shutdown()
 
_ = tracer.Span(ctx, "agent-run", tracing.KindAgent, func(ctx context.Context, root *tracing.Span) error {
    root.SetInput(map[string]any{"q": "weather?"})
    return tracer.Span(ctx, "llm-call", tracing.KindLLM, func(ctx context.Context, llm *tracing.Span) error {
        // SetUsage(promptTokens, completionTokens, totalTokens); pass -1 for an
        // unknown count — total is computed from prompt+completion when it is -1.
        llm.SetModel("gpt-4o").SetUsage(120, 30, -1)
        return nil
    })
})

Spans created from a child context automatically share the trace and link to their parent. OpenTelemetry users can point a standard OTLP/HTTP exporter at the PromptRails OTLP endpoint instead — see the Tracing guide.

SDK Version

import promptrails "github.com/promptrails/go-sdk"
 
fmt.Println(promptrails.Version) // "0.6.0"

Every request is sent with User-Agent: promptrails-go/<version> so backend telemetry can attribute traffic to the SDK release.

Error Handling

The SDK returns typed errors for different HTTP status codes. Use errors.As to handle specific error types:

import "errors"
 
result, err := client.Agents.Execute(ctx, "invalid-id", &promptrails.ExecuteAgentParams{
    Input: map[string]any{},
})
if err != nil {
    var notFound *promptrails.NotFoundError
    var validation *promptrails.ValidationError
    var unauthorized *promptrails.UnauthorizedError
    var forbidden *promptrails.ForbiddenError
    var rateLimit *promptrails.RateLimitError
    var serverErr *promptrails.ServerError
 
    switch {
    case errors.As(err, &notFound):
        fmt.Printf("Agent not found: %s\n", notFound.Message)
    case errors.As(err, &validation):
        fmt.Printf("Invalid input: %s\n", validation.Message)
    case errors.As(err, &unauthorized):
        fmt.Printf("Invalid API key: %s\n", unauthorized.Message)
    case errors.As(err, &forbidden):
        fmt.Printf("Insufficient permissions: %s\n", forbidden.Message)
    case errors.As(err, &rateLimit):
        fmt.Printf("Rate limited: %s\n", rateLimit.Message)
    case errors.As(err, &serverErr):
        fmt.Printf("Server error: %s\n", serverErr.Message)
    default:
        fmt.Printf("Unexpected error: %v\n", err)
    }
}

Error Types

ErrorHTTP StatusDescription
ValidationError400Invalid request parameters
UnauthorizedError401Invalid or missing API key
QuotaExceededError402Plan quota exceeded
ForbiddenError403Insufficient permissions or IP/origin restriction
NotFoundError404Resource not found
RateLimitError429Rate limit exceeded
ServerError5xxServer-side error
APIErrorAnyBase type for all API errors

All error types embed APIError which includes:

  • StatusCode -- HTTP status code
  • Message -- Human-readable error message
  • Code -- Optional error code string
  • Details -- Optional map with additional error details

Context Support

All SDK methods require a context.Context as the first argument, enabling cancellation and timeouts:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
 
result, err := client.Agents.Execute(ctx, "agent-id", &promptrails.ExecuteAgentParams{
    Input: map[string]any{"message": "Hello"},
    Sync:  true,
})

Pagination

List endpoints return paginated responses:

// Page-based pagination
page1, _ := client.Agents.List(ctx, &promptrails.ListAgentsParams{Page: 1, Limit: 20})
page2, _ := client.Agents.List(ctx, &promptrails.ListAgentsParams{Page: 2, Limit: 20})
 
fmt.Printf("Total: %d, Pages: %d\n", page1.Meta.Total, page1.Meta.TotalPages)
PreviousJavaScript SDKNextCLI