Go examples
Initialization and usage for each feature point of the Go Server SDK (module agentbase-go-sdk, method names in PascalCase, service packages lowercase with no separators) and the Console SDK (module agentbase-console-go-sdk). Coordinates are based on the current published surface of agentbase-sdks v2.10.0 (ZIP artifact release terminal state) (the 2.6.0 iteration had no Go deliverable; this language surface starts from 2.7.0, and the gap is logged in changelogs/2.6.0.md); requires go 1.22.5+, and the SDK has zero third-party dependencies.
Fetch and install (replace pointing to a local module)
Not published to the public Go module proxy; after downloading and verifying, use replace to point to a local directory, or directly copy the source tree / go mod vendor:
BUNDLE_DIR="$(mktemp -d)"
BASE_URL="https://code.alipay.com/obai/agentbase-sdks/releases/download/v2.10.0"
curl -fsSL -o "$BUNDLE_DIR/agentbase-go-sdk-2.10.0.zip" "$BASE_URL/agentbase-go-sdk-2.10.0.zip"
curl -fsSL -o "$BUNDLE_DIR/agentbase-console-go-sdk-2.10.0.zip" "$BASE_URL/agentbase-console-go-sdk-2.10.0.zip"
curl -fsSL -o "$BUNDLE_DIR/SHA256SUMS" "$BASE_URL/SHA256SUMS"
(cd "$BUNDLE_DIR" && sha256sum -c --ignore-missing SHA256SUMS)
unzip "$BUNDLE_DIR/agentbase-go-sdk-2.10.0.zip" -d "$BUNDLE_DIR"
unzip "$BUNDLE_DIR/agentbase-console-go-sdk-2.10.0.zip" -d "$BUNDLE_DIR"
(cd "$BUNDLE_DIR/agentbase-go-sdk-2.10.0" && sha256sum -c SHA256SUMS)
(cd "$BUNDLE_DIR/agentbase-console-go-sdk-2.10.0" && sha256sum -c SHA256SUMS)Application module go.mod (the module path has no major suffix, and the required version is pinned to v0.0.0):
require agentbase-go-sdk v0.0.0
require agentbase-console-go-sdk v0.0.0
replace agentbase-go-sdk => /path/to/agentbase-go-sdk-2.10.0
replace agentbase-console-go-sdk => /path/to/agentbase-console-go-sdk-2.10.0Then run go mod tidy / go build as usual; the SDK has zero dependencies and requires no additional network resolution.
Server SDK 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"), // Includes /v1; SIT is https://appbuild-sit.oceanbase.com/v1
agentbase.WithProject("<PROJECT_ID>"),
agentbase.WithKey("<SERVER_API_KEY>"), // Project API Key with minimal scope
)With* options also include WithTimeout, WithSelfSigned, WithProject, WithKey, WithJWT, WithSession, WithOrganization (only WithJWT / WithSession / WithOrganization are used for controlled flows explicitly required by the endpoint; they are not a general substitute for API Keys). Do not write API Keys, JWTs, or Sessions into source code, command history, logs, or version control.
Calling conventions
Required parameters are passed by position, and optional parameters use the With* method 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:
import (
"agentbase-go-sdk/agentbase"
"agentbase-go-sdk/id"
"agentbase-go-sdk/models"
"agentbase-go-sdk/query"
)
tables := agentbase.NewTablesDB(cl)
_, err := tables.Create("app-db", "App")
_, 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"}},
}),
)
_, err = tables.CreateRow("app-db", "tasks", id.Unique())
rows, err := tables.ListRows("app-db", "tasks",
[]string{query.OrderDesc("$createdAt"), query.Limit(25)})For lists/indexes type, follow the feature documentation databases.
DocumentsDB and transactions
DocumentsDB (agentbase.NewDocumentsDB) is the document semantic surface of TablesDB; typed transaction:
documents := agentbase.NewDocumentsDB(cl)
tx, err := documents.CreateTransaction()
_, err = documents.CreateOperations(tx.Id,
documents.WithCreateOperationsOperations([]models.DocumentsDBTransactionOperation{{
DatabaseId: "app-db",
CollectionId: "tasks",
DocumentId: "doc-1",
Action: "create", // create/update/upsert/delete/increment/...
Data: map[string]interface{}{"title": "tx doc"},
}}))
_, err = documents.UpdateTransaction(tx.Id, documents.WithUpdateTransactionCommit(true))
// or documents.WithUpdateTransactionRollback(true) to roll backUsers, teams, and storage
import (
"agentbase-go-sdk/agentbase"
"agentbase-go-sdk/file"
"agentbase-go-sdk/id"
)
users := agentbase.NewUsers(cl)
created, err := users.Create(id.Unique(),
users.WithCreateEmail("user@example.com"),
users.WithCreatePassword("<password>"),
users.WithCreateName("Example User"))
_ = created
teams := agentbase.NewTeams(cl)
_, err = teams.Create("my-team", "My Team", teams.WithCreateRoles([]string{"owner"}))
storage := agentbase.NewStorage(cl)
_, err = storage.CreateBucket("attachments", "附件",
storage.WithCreateBucketFileSecurity(true),
storage.WithCreateBucketEnabled(true))
uploaded, err := storage.CreateFile("attachments", id.Unique(),
file.NewInputFile("./report.pdf", "report.pdf"))
view, err := storage.GetFileView("attachments", uploaded.Id) // *[]byteThe response body of a server-side user session creation does not contain the secret (it exists only in the a_session_<projectId> cookie); when a user-state client is needed, read that cookie and then call agentbase.NewClient(agentbase.WithSession(secret), ...).
Reading row data (Decode)
Custom business fields of list/detail models do not enter the struct; row data is obtained as raw JSON via Decode():
row, err := tables.GetRow("app-db", "tasks", "<rowId>")
payload := map[string]interface{}{}
_ = row.Decode(&payload)
title, _ := payload["title"].(string)Console SDK initialization
The Go Console SDK (module agentbase-console-go-sdk) and the Server module can be consumed together via replace (both facade packages are named agentbase; use an alias at import):
require (
agentbase-console-go-sdk v0.0.0
agentbase-go-sdk v0.0.0
)
replace agentbase-go-sdk => /path/to/agentbase-go-sdk-2.10.0
replace agentbase-console-go-sdk => /path/to/agentbase-console-go-sdk-2.10.0The Console login response body contains no session secret (it lives only in the a_session_console cookie); first fetch the cookie via raw HTTP, then attach it to the Console SDK client:
import (
consolefacade "agentbase-console-go-sdk/agentbase"
"agentbase-go-sdk/agentbase"
)
consoleClient := consolefacade.NewClient(
consolefacade.WithEndpoint("https://appbuild.oceanbase.com/v1"),
consolefacade.WithProject("console"),
)
consoleClient.AddHeader("origin", "https://appbuild.oceanbase.com")
consoleClient.AddHeader("x-forwarded-host", "appbuild.oceanbase.com")
consoleClient.AddHeader("Cookie", "a_session_console="+cookieFromLoginResponse)
consoleTeams := consolefacade.NewTeams(consoleClient)
consoleProjects := consolefacade.NewProjects(consoleClient)
_, _ = consoleTeams.Create("my-team", "My Team", consoleTeams.WithCreateRoles([]string{"owner"}))
project, _ := consoleProjects.Create("unique()", "My Project", "my-team")
key, _ := consoleProjects.CreateKey(project.Id, "server key", []string{
"users.read", "users.write", "teams.read", "teams.write",
})
fmt.Println(key.Secret) // API Key used by the Server SDKThe Console service surface includes account, teams, projects, users, proxy, migrations, etc.; calling conventions are consistent with the Server module.
Memory / Knowledge Bases / gateway and observability
Themed capabilities (Memory, Knowledge Bases, LLM Gateway, AI Gateway, Observability, Moderation, etc.) are used via the facade full constructors (NewMemory, NewKnowledgeBases, NewLlmGateway, NewAiGateway, NewObservability, NewModeration, etc.); the method surface is isomorphic to the Node SDK . For parameters and return structures, see each feature's documentation (agent workbench, memory, knowledge base, LLM and AI Gateway, observability, etc.); for JavaScript equivalents, see the corresponding sections of javascript.md. Per-method Go signatures follow the module source code.
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
}