Docs
Contents

Server SDK(Go)

Go backends / controlled admin scripts call the Server SDK with a project API Key (module agentbase-go-sdk, method names PascalCase, service packages lowercase run together). API Key requests skip row-level permission checks (hasRole); store only on controlled servers. For Node / Java / Python, see nodejs.md / java.md / python.md in the same directory.

Artifacts and installation

Requires go 1.22.5+; the SDK has zero third-party dependencies. It is not published to the public Go module proxy: extract from the agentbase-sdks release ZIP, then in your application module point replace at the local directory with a go.mod directive (require version fixed as v0.0.0), or copy the source tree / go mod vendor directly. For the full download, verification, and replace commands, see ../examples/go.md "Obtaining and installing"; the Go surface has been delivered since agentbase-sdks v2.7.0 (2.6.0 had no such language surface).

Initialization

The facade package agentbase-go-sdk/agentbase provides a unified entry point:

import "agentbase-go-sdk/agentbase"

cl := agentbase.NewClient(
    agentbase.WithEndpoint("https://appbuild.oceanbase.com/v1"),   // SIT: https://appbuild-sit.oceanbase.com/v1
    agentbase.WithProject("<PROJECT_ID>"),
    agentbase.WithKey("<SERVER_API_KEY>"),                          // Project API Key with minimal scope
)

Alongside With*, options include WithTimeout, WithSelfSigned, WithJWT, WithSession, WithOrganization (the last three are only for controlled flows where the endpoint explicitly requires a user identity).

Calling conventions

Pass required parameters positionally; for optional parameters use the With* methods attached to the service (naming rule With<方法名><参数名>; the module source is authoritative for the full list); queries use agentbase-go-sdk/query and IDs use agentbase-go-sdk/id:

tables := agentbase.NewTablesDB(cl)

_, err := tables.CreateTable("app-db", "tasks", "Tasks",
    tables.WithCreateTableRowSecurity(true),
    tables.WithCreateTableEnabled(true),
    tables.WithCreateTableColumns([]models.DatabaseColumnDefinition{
        {Key: "title", Type: "string", Size: 256, Required: true},
    }),
    tables.WithCreateTableIndexes([]models.DatabaseIndexDefinition{
        {Key: "idx_title", Type: "unique", Attributes: []string{"title"}},
    }),
)

Custom business fields of list and detail models such as rows/documents do not go into structs; fetch the raw JSON via Decode():

row, err := tables.GetRow("app-db", "tasks", "<rowId>")
payload := map[string]interface{}{}
_ = row.Decode(&payload)

Client configuration options, cursor pagination, and file upload in practice

agentbase.NewClient uses the Functional Options pattern to construct the client; all services share that client instance via agentbase.New<Service>(cl):

NewClient option functionHTTP request header / behavior injectedapplicable scenarios and security constraints
WithEndpoint(url)Request base addressRequired, e.g. https://appbuild-sit.oceanbase.com/v1 or https://appbuild.oceanbase.com/v1.
WithProject(projectId)X-Appwrite-ProjectRequired, target project ID (e.g. the demo project enterprise-ai-hub-210).
WithKey(apiKey)X-Appwrite-KeyThe primary server-side authentication method, skips RLS (hasRole), authorized with the minimal scopes.
WithJWT(jwt)X-Appwrite-JWTCalls data-plane APIs on behalf of a specific logged-in user (bound by that user's RLS row-level permissions).
WithSession(session)X-Appwrite-SessionLoaded when the server forwards a browser login session Cookie.
WithOrganization(orgId)X-Appwrite-OrganizationSpecifies the organization context for organization-level query and governance APIs (e.g. 69c6d1aa00062e6bb60).
WithLocale(locale)X-Appwrite-LocaleSpecifies the language for internationalized responses (e.g. zh-CN).
WithTimeout(duration)HTTP client timeoutDefaults to 10 seconds; for large file uploads or long-running AI calls, set 30 * time.Second or higher.
WithSelfSigned(true)TLS certificate verification toggleOnly for private test instances with self-signed certificates; strictly forbidden to enable in production.

Complete example of cursor pagination, custom struct decoding, and file upload

The following example shows how, in a Go backend, to iterate the customer_tickets support ticket table in the business database enterprise_biz_db (using query.CursorAfter cursor pagination and row.Decode to decode business fields), upload a file (file.NewInputFile), and perform backoff retries on 429/5xx errors:

package main

import (
	"errors"
	"fmt"
	"os"
	"time"

	"agentbase-go-sdk/agentbase"
	agentbaseclient "agentbase-go-sdk/client"
	"agentbase-go-sdk/file"
	"agentbase-go-sdk/id"
	"agentbase-go-sdk/query"
)

type TicketPayload struct {
	ID       string `json:"$id"`
	TicketNo string `json:"ticketNo"`
	Title    string `json:"title"`
	Status   string `json:"status"`
	Priority string `json:"priority"`
}

func main() {
	cl := agentbase.NewClient(
		agentbase.WithEndpoint("https://appbuild-sit.oceanbase.com/v1"),
		agentbase.WithProject("enterprise-ai-hub-210"),
		agentbase.WithKey(os.Getenv("APPBASE_API_KEY")),
		agentbase.WithTimeout(30*time.Second),
	)
	tables := agentbase.NewTablesDB(cl)
	storage := agentbase.NewStorage(cl)

	// 1. Fetch open support tickets with cursor pagination and decode into strongly typed structs
	cursor := ""
	pageSize := 50
	for {
		queries := []string{
			query.Equal("status", []interface{}{"open", "in_progress"}),
			query.OrderAsc("$id"),
			query.Limit(pageSize),
		}
		if cursor != "" {
			queries = append(queries, query.CursorAfter(cursor))
		}

		page, err := tables.ListRows("enterprise_biz_db", "customer_tickets",
			tables.WithListRowsQueries(queries),
			tables.WithListRowsTotal(false), // Disable count(*) to improve pagination performance on large tables
		)
		if err != nil {
			var aerr *agentbaseclient.AgentbaseError
			if errors.As(err, &aerr) {
				fmt.Printf("HTTP %d: %s\n", aerr.GetStatusCode(), aerr.GetMessage())
			}
			break
		}
		if len(page.Rows) == 0 {
			break
		}
		for _, row := range page.Rows {
			var t TicketPayload
			_ = row.Decode(&t)
			fmt.Printf("Ticket %s [%s]: %s\n", t.TicketNo, t.Priority, t.Title)
		}
		if len(page.Rows) < pageSize {
			break
		}
		cursor = page.Rows[len(page.Rows)-1].Id
	}

	// 2. Upload local files to the knowledge base document bucket kb_enterprise_docs
	inputFile := file.NewInputFile("/tmp/智能客服SOP标准作业手册.md", "智能客服SOP标准作业手册.md")
	uploaded, err := storage.CreateFile("kb_enterprise_docs", id.Unique(), inputFile)
	if err == nil {
		fmt.Println("Uploaded file ID:", uploaded.Id)
	}
}

Using together with the Console SDK (agentbase-console-go-sdk)

The Go deliverable provides both a Server SDK (agentbase-go-sdk) and a Console SDK (agentbase-console-go-sdk). Within the same Go module, you can import both modules via two replace directives of go.mod, and use package aliases (e.g. serverfacade "agentbase-go-sdk/agentbase" and consolefacade "agentbase-console-go-sdk/agentbase") to distinguish project data-plane from management control-plane calls (see ../console-sdk/go.md for details).

Feature surface navigation

The service surface is isomorphic to the Node surface (full facade constructors NewTablesDB, NewStorage, NewUsers, NewMemory, NewKnowledgeBases, NewLlmGateway, NewAiGateway, NewObservability, NewModeration, etc.); for the full mapping see nodejs.md "Feature surface navigation"; feature pages: Databases, Storage, Functions, Sites, Users, Teams, Messaging, memory, knowledge base, LLM Gateway, AI Gateway, Observability, Moderation, Cross-cutting services.

No Sql service (SQL uses the HTTP form or the Console SDK, see ../databases/sql-proxy.md); no Realtime (client-side capability).

Error Handling

Errors are uniformly *client.AgentbaseError (agentbase-go-sdk/client):

import (
	"errors"

	agentbaseclient "agentbase-go-sdk/client"
)

_, err := tables.GetRow("app-db", "tasks", "missing-row")
var aerr *agentbaseclient.AgentbaseError
if errors.As(err, &aerr) && aerr.GetStatusCode() == 404 {
	// not found; GetMessage() / GetResponse() (raw response body) are also available
}

Example Guide