agentbase-docs

Server SDK(Go)

Go 后端 / 受控管理脚本以项目 API Key 调用 Server SDK(module agentbase-go-sdk,方法名 PascalCase、service 包小写连排)。API Key 请求跳过行级权限检查(hasRole),只存受控服务端。Node / Java / Python 面见同目录 nodejs.md / java.md / python.md。

制品与安装

要求 go 1.22.5+,SDK 零第三方依赖。不发布到公共 Go module proxy:从 agentbase-sdks release ZIP 解压后,在应用模块 go.mod 中以 replace 指向本地目录(require 版本固定写 v0.0.0),或直接复制源码树 / go mod vendor。下载、校验与 replace 完整命令见 ../examples/go.md「获取与安装」;Go 面自 agentbase-sdks v2.7.0 起交付(2.6.0 无该语言面)。

初始化

facade 包 agentbase-go-sdk/agentbase 提供统一入口:

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>"),                          // 最小 scope 的项目 API Key
)

With* 选项还有 WithTimeout、WithSelfSigned、WithJWT、WithSession、WithOrganization(后三者仅用于 endpoint 明确要求用户身份的受控流程)。

调用约定

必选参数按位置传,可选参数用挂在 service 上的 With* 方法(命名规则 With<方法名><参数名>,全量以模块源码为准);查询用 agentbase-go-sdk/query、ID 用 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"}},
    }),
)

行/文档等列表与详情模型的自定义业务字段不进 struct,经 Decode() 取原始 JSON:

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

功能面导航

服务面与 Node 面同构(facade 全量构造器 NewTablesDB、NewStorage、NewUsers、NewMemory、NewKnowledgeBases、NewLlmGateway、NewAiGateway、NewObservability、NewModeration 等),全量映射见 nodejs.md「功能面导航」;各功能页:数据库、存储、函数、站点、用户、团队、消息、记忆、知识库、LLM Gateway、AI Gateway、可观测、审核、横切服务。

无 Sql 服务(SQL 走 HTTP 形态或 Console SDK,../databases/sql-proxy.md);无 Realtime(客户端能力)。

错误处理

错误统一为 *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()(原始响应体)
}

示例指引

事实源