Skip to content
Tavora

Go SDK

The Tavora Go SDK provides a typed, context-aware client for every capability the platform exposes. All operations are scoped to a single workspace via API key authentication (tvr_... keys).

Installation

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

Client shape

Section titled “Client shape”

The SDK is deliberately flat — every method is on *Client, no nested service namespaces to remember:

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


client := tavora.NewClient("http://localhost:8080", "tvr_...")
ctx := context.Background()


ws, _ := client.GetWorkspace(ctx)
session, _ := client.CreateAgentSession(ctx, tavora.CreateAgentSessionInput{...})
_ = client.RunAgent(ctx, session.ID, "hello", onEvent)

Every method takes a context.Context as its first argument so callers can cancel, deadline, or trace any request.

What the SDK covers

Section titled “What the SDK covers”
AreaMethods
WorkspaceGetWorkspace
Agents — sessionsCreateAgentSession, ListAgentSessions, GetAgentSession, DeleteAgentSession, RunAgent, GetAgentSystemPrompt
Agents — configs + versionsCreateAgentConfig, ListAgentConfigs, Get/Update/DeleteAgentConfig, SetActiveAgentVersion
Agent versions + deploymentsCreateAgentVersion, ListAgentVersions, GetAgentVersion, UpsertAgentDeployment, ListAgentDeployments
SkillsCreateSkill, ListSkills, GetSkill, DeleteSkill
MCP serversCreateMCPServer, ListMCPServers, GetMCPServer, UpdateMCPServer, DeleteMCPServer, TestMCPServer
KnowledgeCreateStore, ListStores, GetStore, UpdateStore, DeleteStore, UploadDocument, GetDocument, ListDocuments, DeleteDocument, Search
ChatChatCompletion (stateless), CreateConversation, SendMessage, Get/List/DeleteConversation
EvalsCreateSuite, NewSuiteVersion, CreateEvalCase, RunEval, GetEvalRun, ListEvalRuns
PromotionsProposePromotion, ApprovePromotion, RejectPromotion, GetPromotion, ListPendingPromotions
Policies (Phase 14)UpsertToolPolicy, DeleteToolPolicy, ListToolPolicies, ListPendingApprovals, ApproveApprovalRequest, RejectApprovalRequest
Studio (debugging)GetStudioTrace, ReplayFromStep, AnalyzeFix
Scheduled runsCreateScheduledRun, Get/List/DeleteScheduledRun
Prompts + metrics + auditCreatePromptTemplate et al., GetMetrics, ListAuditLog, ExportAuditLog

Authentication

Section titled “Authentication”

All SDK calls send X-API-Key: tvr_... and target /api/sdk/*. Keys are workspace-scoped — one key, one workspace. Create them in the admin UI under Workspace Settings → API keys, or use the tavora-admin api-keys create CLI.

For browser apps that need SDK access without exposing a long-lived key, use the session-token exchange flow — see Browser-side chat.

Error handling

Section titled “Error handling”

Failures return *APIError with StatusCode, Message, and an optional machine-readable Code. Network errors come through as error values from the underlying transport.

if _, err := client.GetAgentSession(ctx, id); err != nil {
    var apiErr *tavora.APIError
    if errors.As(err, &apiErr) && apiErr.StatusCode == 404 {
        // session doesn't exist
    }
}

Streaming

Section titled “Streaming”

RunAgent streams SSE events through a callback:

  • execute_js / execute_js_result — JavaScript body and output from the Goja sandbox.
  • tool_call / tool_result — ADK function-call tools.
  • sandbox_event — primitive-level (fetch, ai, web_search, skill_call, …).
  • response — the model’s user-visible reply.
  • error / done — terminal states. done carries a RunSummary with step count + prompt/completion token totals.

What’s not yet in the SDK

Section titled “What’s not yet in the SDK”
  • CreateTeam / CreateWorkspace — team-level ops stay JWT-only for now (admin UI or tavora-admin).
  • Webhook subscriptions for async notifications.
  • Bulk endpoints.

Next steps

Section titled “Next steps”