Go & TypeScript SDKs

Two official SDKs consume the same /api/sdk/* surface:

• tavora-sdk-go — Go SDK, full unit-test coverage against a httptest.Server mock harness.
• @tavora/sdk — TypeScript SDK. Runs in Node ≥ 20 and any browser with native fetch. Zero runtime dependencies.

Both SDKs are deliberately flat — every capability is a method on the client, no nested service namespaces. The Go variant takes a context.Context as its first argument on every method so callers can cancel, deadline, or trace any request.

Installation

Go

go get github.com/tavora-ai/tavora-sdk-go

TypeScript

npm install @tavora/sdk

Client shape

Go

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

client := tavora.NewClient("https://api.tavora.ai", "tvr_...")
ctx := context.Background()

app, _ := client.GetApp(ctx)
session, _ := client.CreateAgentSession(ctx, tavora.CreateAgentSessionInput{
    AgentID: "agent_...",
})
_ = client.RunAgent(ctx, session.ID, "Summarise my docs.", onEvent)

TypeScript

import { Client } from '@tavora/sdk';

const client = new Client('https://api.tavora.ai', 'tvr_...');

const app = await client.getApp();
const session = await client.createAgentSession({
  agent_id: 'agent_...',
});
for await (const evt of client.runAgent(session.id, 'Summarise my docs.')) {
  if (evt.type === 'response') console.log(evt.content);
}

Authoring vs runtime

A Tavora agent’s configuration (persona, skills, MCP, evals, indexes, model) is authored as files under your local tavora/ folder and shipped via the tavora CLI (init / dev / deploy). The SDK is the runtime channel your product uses to drive an already-deployed agent.

The SDK does not create, edit, or version agents — that path runs through the CLI’s source-sync verbs. The closest the SDK gets is the low-level sourceSync / sourceDeploy family, which is what the CLI itself uses internally; most application code shouldn’t touch them.

What the SDKs cover

Area	Methods
App	getApp, getMetrics
Agents — sessions	createAgentSession, listAgentSessions, getAgentSession, deleteAgentSession, runAgent (SSE), respondToAgentInput, getAgentSystemPrompt
Agent configs + history	listAgentConfigs, getAgentConfig, deleteAgentConfig, listAgentVersions, getAgentVersion, updateAgentSettings, runAgentEval, listAgentEvalRuns
Indexes (RAG containers)	createIndex, listIndexes, getIndex, updateIndex, deleteIndex
Documents	uploadDocument, getDocument, getDocumentByName, listDocuments, listDocumentVersions, deleteDocument, deleteDocumentHard, search, searchDocuments
Secret vaults	createSecretVault, listSecretVaults, get/update/deleteSecretVault, listSecrets, putSecret, deleteSecret (API never returns plaintext)
Skills	listSkills, getSkill, getSkillAuthoringGuide (read-only — skills are authored as .js/.md files under tavora/agents/<id>/skills/)
Chat	chatCompletion (stateless), createConversation, listConversations, getConversation, deleteConversation, sendMessage
Evals (advisory)	listEvalCases, listEvalRuns, getEvalRun, listSuites, getSuite. Eval cases are authored in tavora/agents/<id>/evals/*.json; trigger runs per agent via runAgentEval above.
Session forensics	getStudioTrace, replayFromStep (SSE), analyzeFix
Scheduled runs	createScheduledRun, get/list/updateScheduledRun, deleteScheduledRun
Code-first source (advanced)	sourceSync, sourceValidate, sourceDeploy, sourceRename, sourceDelete — used by the tavora CLI to author agents from a local folder. Application code rarely calls these directly.
Audit log	listAuditLog, exportAuditLog (JSON or CSV bytes for SOC2 evidence)

Full per-endpoint reference (path, payload shape, error codes) lives in the REST API page; the SDKs are thin wrappers over that surface.

What’s not in the SDK

• Agent CRUD + draft/publish/revert — use the tavora CLI (init / dev / deploy). The browser’s /agents/:id page is a read-only control plane.
• MCP server registration — declared inline in agent.jsonc → mcp and ships through sourceSync. There’s no per-server CRUD endpoint anymore.
• Skill / eval case CRUD — authored as files under the agent’s folder, the same way.
• Tool policies + approvals — removed in the 2026-05-13 MVP slim-down.
• createTeam / createApp — team-level ops stay JWT-only (admin UI or tavora-admin).
• Webhook subscriptions for async notifications (on roadmap).

Authentication

All SDK calls send X-API-Key: tvr_... and target /api/sdk/*. Keys are app-scoped — one key, one app. Mint one through the admin web UI (covered in the platform’s internal docs, not here) and store it with tavora login so the CLI picks it up too.

For browser apps that can’t safely hold a long-lived key, use the session-token exchange — see Browser-based chat.

Error handling

Failures return a typed error with code, message, and a structured details map. Helper checks promote programmatic recovery:

Go

doc, err := client.GetDocument(ctx, id)
if err != nil {
    if conflict, ok := tavora.AsVersionConflict(err); ok {
        // re-read, merge, retry with conflict.CurrentVersion
    }
    var apiErr *tavora.APIError
    if errors.As(err, &apiErr) && apiErr.StatusCode == 404 {
        // not found
    }
}

TypeScript

import { asVersionConflict, isNotFound } from '@tavora/sdk';

try {
  await client.getDocument(id);
} catch (err) {
  const conflict = asVersionConflict(err);
  if (conflict) {
    // retry with conflict.currentVersion
  } else if (isNotFound(err)) {
    // 404
  }
}

Streaming agent runs

runAgent streams SSE events. Per-step tokens reports LLM cost in real time; EventType* constants disambiguate the event kind:

• execute_js / execute_js_result — the JS the agent wrote, and what the sandbox returned.
• tool_call / tool_result — function-call tools.
• sandbox_event — primitive-level (fetch, ai, search, skill_call, …).
• response — the model’s user-visible reply.
• input_request — the agent paused for user input from inside the sandbox; respond via respondToAgentInput.
• error / done — terminal states. done carries a summary with step count + token totals.

Resource model — what to use when

Use this	When
Indexes + Documents	Knowledge you want recalled by meaning. Documents inside an Index get chunked + embedded.
Secret vaults	Envelope-encrypted credentials the platform resolves internally for the LLM router, MCP auth.tokenRef, and other tool surfaces. The API never returns plaintext.
Your backend (via MCP)	Customer file storage, structured records, OAuth, schema rules, end-user auth — everything that isn’t agent state. MCP servers are declared inline in agent.jsonc → mcp.

Customer file blobs and structured records belong in your backend (PocketBase / Supabase / your own DB), exposed to the agent via MCP. Tavora is the agent layer, not a backend-as-a-service.

Next steps

• Client reference — base URL, options, debug hooks.
• MCP in code-first agents — how agent.jsonc → mcp flows through sourceSync.
• Browser-based chat — browser usage via session-minted keys.
• REST API — direct HTTP reference.