Skip to content
Tavora

Quickstart

Get up and running with Tavora in 5 minutes. This guide walks you through initializing the Go SDK, uploading a document, searching it, and running an agent.

Prerequisites

Section titled “Prerequisites”
  • A Tavora workspace with an API key (create one in Workspace Settings → API keys at /platform)
  • Go 1.25+ installed

Install the SDK

Section titled “Install the SDK”
Terminal window
go get github.com/tavora-ai/tavora-sdk-go

Initialize the client

Section titled “Initialize the client”
package main


import (
    "context"
    "fmt"
    "log"


    tavora "github.com/tavora-ai/tavora-sdk-go"
)


func main() {
    client := tavora.NewClient(
        "http://localhost:8080", // or https://api.tavora.ai
        "tvr_your-api-key",
    )
    ctx := context.Background()


    // Sanity-check the connection.
    ws, err := client.GetWorkspace(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Connected to workspace: %s\n", ws.Name)
}

Every SDK method is a direct call on *Client — no nested service namespaces. Methods are context-aware so you can cancel, deadline, or trace any request.

Upload a document

Section titled “Upload a document”
// Create a store (a collection of related documents).
store, err := client.CreateStore(ctx, tavora.CreateStoreInput{
    Name:        "Support docs",
    Description: "FAQ and product manuals",
})
if err != nil {
    log.Fatal(err)
}


// Upload a file. Chunking + embedding runs in the background.
doc, err := client.UploadDocument(ctx, tavora.UploadDocumentInput{
    StoreID:  store.ID,
    FilePath: "./faq.md",
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Uploaded %s (status: %s)\n", doc.ID, doc.Status)

Poll client.GetDocument(ctx, doc.ID) until Status == "ready" before searching — embeddings are computed asynchronously by a River job.

Search the knowledge base

Section titled “Search the knowledge base”
results, err := client.Search(ctx, tavora.SearchInput{
    Query:   "what document formats are supported?",
    StoreID: store.ID,
    Limit:   5,
})
if err != nil {
    log.Fatal(err)
}
for _, r := range results {
    fmt.Printf("%.2f — %s\n", r.Score, r.Snippet)
}

Run an agent

Section titled “Run an agent”

Agent sessions are the canonical path for anything that needs reasoning, tool use, or multi-step work. One session = one ongoing conversation; each turn goes through the Goja sandbox where the agent can fetch, ai, search, require('<mcp-server>'), and more.

session, err := client.CreateAgentSession(ctx, tavora.CreateAgentSessionInput{
    Title: "First agent chat",
    SystemPrompt: "You are a helpful assistant. Use execute_js for " +
        "computation or multi-step work.",
})
if err != nil {
    log.Fatal(err)
}


err = client.RunAgent(ctx, session.ID, "Summarise my FAQ in 3 bullets.",
    func(evt tavora.AgentEvent) {
        switch evt.Type {
        case "execute_js":
            fmt.Printf("[js] %s\n", evt.Content)
        case "response":
            fmt.Printf("\n%s\n", evt.Content)
        case "done":
            if evt.Summary != nil {
                fmt.Printf("[%d steps, %d+%d tokens]\n",
                    evt.Summary.Steps,
                    evt.Summary.Tokens.Prompt,
                    evt.Summary.Tokens.Completion)
            }
        }
    })
if err != nil {
    log.Fatal(err)
}

RunAgent streams execution events over SSE — execute_js, execute_js_result, tool_call, tool_result, sandbox_event, response, and done. Reuse the same session ID across turns to keep conversation history.

Next steps

Section titled “Next steps”