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 function | HTTP request header / behavior injected | applicable scenarios and security constraints |
|---|---|---|
WithEndpoint(url) | Request base address | Required, e.g. https://appbuild-sit.oceanbase.com/v1 or https://appbuild.oceanbase.com/v1. |
WithProject(projectId) | X-Appwrite-Project | Required, target project ID (e.g. the demo project enterprise-ai-hub-210). |
WithKey(apiKey) | X-Appwrite-Key | The primary server-side authentication method, skips RLS (hasRole), authorized with the minimal scopes. |
WithJWT(jwt) | X-Appwrite-JWT | Calls data-plane APIs on behalf of a specific logged-in user (bound by that user's RLS row-level permissions). |
WithSession(session) | X-Appwrite-Session | Loaded when the server forwards a browser login session Cookie. |
WithOrganization(orgId) | X-Appwrite-Organization | Specifies the organization context for organization-level query and governance APIs (e.g. 69c6d1aa00062e6bb60). |
WithLocale(locale) | X-Appwrite-Locale | Specifies the language for internationalized responses (e.g. zh-CN). |
WithTimeout(duration) | HTTP client timeout | Defaults to 10 seconds; for large file uploads or long-running AI calls, set 30 * time.Second or higher. |
WithSelfSigned(true) | TLS certificate verification toggle | Only 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
Go (Server / Console) complete call syntax: ../examples/go.md