Go 示例
示例中的 <APPBASE_ENDPOINT_WITH_V1>、<APPBASE_CONSOLE_ORIGIN> 和 <APPBASE_CONSOLE_HOST> 均需按实际使用位置替换为目标环境信息;先确认环境再运行。
Go Server SDK(module agentbase-go-sdk,方法名 PascalCase、service 包小写连排)与 Console SDK(module agentbase-console-go-sdk)的初始化与各功能点调用写法。坐标按 agentbase-sdks 当前发布面 v2.12.0(ZIP 制品 release 终态)(2.6.0 迭代无 Go 交付,该语言面自 2.7.0 起,缺口登记见 changelogs/2.6.0.md);要求 go 1.22.5+,SDK 零第三方依赖。
获取与安装(replace 指向本地模块)
不发布到公共 Go module proxy;下载校验后以 replace 指向本地目录,或直接复制源码树 / go mod vendor:
BUNDLE_DIR="$(mktemp -d)"
BASE_URL="https://code.alipay.com/obai/agentbase-sdks/releases/download/v2.12.0"
curl -fsSL -o "$BUNDLE_DIR/agentbase-go-sdk-2.12.0.zip" "$BASE_URL/agentbase-go-sdk-2.12.0.zip"
curl -fsSL -o "$BUNDLE_DIR/agentbase-console-go-sdk-2.12.0.zip" "$BASE_URL/agentbase-console-go-sdk-2.12.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.12.0.zip" -d "$BUNDLE_DIR"
unzip "$BUNDLE_DIR/agentbase-console-go-sdk-2.12.0.zip" -d "$BUNDLE_DIR"
(cd "$BUNDLE_DIR/agentbase-go-sdk-2.12.0" && sha256sum -c SHA256SUMS)
(cd "$BUNDLE_DIR/agentbase-console-go-sdk-2.12.0" && sha256sum -c SHA256SUMS)应用模块 go.mod(模块路径无 major 后缀,require 版本固定写 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.12.0
replace agentbase-console-go-sdk => /path/to/agentbase-console-go-sdk-2.12.0随后正常 go mod tidy / go build;SDK 零依赖,不需要额外网络解析。
Server SDK 初始化
facade 包 agentbase-go-sdk/agentbase 提供统一入口:
import (
"errors"
"net/http"
"agentbase-go-sdk/agentbase"
)
cl := agentbase.NewClient(
agentbase.WithEndpoint("<APPBASE_ENDPOINT_WITH_V1>"), // 含 /v1;SIT 为 https://appbuild-sit.oceanbase.com/v1
agentbase.WithProject("<PROJECT_ID>"),
agentbase.WithKey("<SERVER_API_KEY>"), // 最小 scope 的项目 API Key
)
cl.Client.CheckRedirect = func(_ *http.Request, _ []*http.Request) error {
return errors.New("refuse redirects")
}With* 选项还有 WithTimeout、WithSelfSigned、WithProject、WithKey、WithJWT、WithSession、WithOrganization(仅 WithJWT / WithSession / WithOrganization 用于 endpoint 明确要求的受控流程,不是 API Key 的通用替代)。不要把 API Key、JWT、Session 写入源码、命令历史、日志和版本库。
调用约定
必选参数按位置传,可选参数用挂在 service 上的 With* 方法(命名规则 With<方法名><参数名>,全量以模块源码为准);查询用 agentbase-go-sdk/query,ID 用 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)})列/索引 type 以功能点文档数据库为准。
DocumentsDB 与事务
DocumentsDB(agentbase.NewDocumentsDB)是 TablesDB 的 document 语义面;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))
// 或 documents.WithUpdateTransactionRollback(true) 回滚用户、团队与存储
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) // *[]byte服务端创建用户 session 的返回体不含 secret(只在 a_session_<projectId> cookie 里);需要用户态 client 时读取该 cookie 后 agentbase.NewClient(agentbase.WithSession(secret), ...)。
行数据的读取(Decode)
列表/详情模型的自定义业务字段不进 struct,行数据经 Decode() 取原始 JSON:
row, err := tables.GetRow("app-db", "tasks", "<rowId>")
payload := map[string]interface{}{}
_ = row.Decode(&payload)
title, _ := payload["title"].(string)Console SDK 初始化
Go Console SDK(module agentbase-console-go-sdk)与 Server module 可同时 replace 消费(facade 包名均为 agentbase,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.12.0
replace agentbase-console-go-sdk => /path/to/agentbase-console-go-sdk-2.12.0Console 登录响应体不含 session secret(只在 a_session_console cookie),先经原始 HTTP 取 cookie 再挂到 Console SDK client:
import (
consolefacade "agentbase-console-go-sdk/agentbase"
"agentbase-go-sdk/agentbase"
)
consoleClient := consolefacade.NewClient(
consolefacade.WithEndpoint("<APPBASE_ENDPOINT_WITH_V1>"),
consolefacade.WithProject("console"),
)
consoleClient.AddHeader("origin", "<APPBASE_CONSOLE_ORIGIN>")
consoleClient.AddHeader("x-forwarded-host", "<APPBASE_CONSOLE_HOST>")
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",
})
_ = key // 将此次创建响应中的密钥直接保存到凭据管理系统。Console 服务面含 account、teams、projects、users、proxy、migrations 等;调用约定与 Server module 一致。
Memory / Knowledge Bases / 网关与观测
专题能力(Memory、Knowledge Bases、LLM Gateway、AI Gateway、Observability、Moderation 等)经 facade 全量构造器(NewMemory、NewKnowledgeBases、NewLlmGateway、NewAiGateway、NewObservability、NewModeration 等)使用,方法面与 Node SDK 同构。参数与返回结构见各功能点文档(智能体工作台、记忆、知识库、模型与 AI 网关、可观测等);JavaScript 写法对照见 javascript.md 对应小节,逐方法的 Go 签名以模块源码为准。
错误处理
错误统一为 *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()(原始响应体)
}