agentbase-docs

可观测

这是什么 / 何时用

Observability 覆盖两件事:

前置

使用骨架

关键参数与返回

错误与边界

2.7.0 增量:轨迹评估与监控指标

以下能力落在 Console 评估面与评估 worker / 部署监控侧,公开摄取与查询契约(本页端点)无变化(spec v2.6.0 → v2.7.0 observability 段无新增端点与参数变更):

2.8.0 增量:评估 MCP 工具发现

评估任务可为评估器挂接 MCP 工具:配置前先用受限网关凭据发现该网关上可用的只读 MCP 工具,再在评估配置中圈定要挂接的工具。新增方法 observability.discoverEvalMcpTools(gatewayId, gatewayKeyId) —— POST /observability/evals/mcp/tools,请求体 { gatewayId, gatewayKeyId }(AI Gateway 的网关 ID 与受限 Gateway Key ID);返回该网关暴露的只读(无副作用)MCP 工具清单。scope 为 observability.evals.write;gatewayKeyId 需为绑定该网关的活跃子密钥(显式圈定工具、不含模型 / Agent 权限)。

SDK 类别差异

示例指引

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

批量上报(JSON ingestion)

batch 为 1–100 个事件;全部成功 HTTP 200,任一失败 HTTP 207 Multi-Status,必须逐项检查 errors[]——200/207 都不等于已持久化(异步 worker 落库),回读 404 时做有上限短轮询。429 与可恢复 5xx 用有上限指数退避并复用原外层 id,schema/权限类 4xx 不盲重试;超 100 条按 create-before-update 顺序分批。

import { Client, Observability } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)   // 必须包含 /v1
    .setProject(process.env.APPBASE_PROJECT_ID!)
    .setKey(process.env.APPBASE_API_KEY!);        // 写入 scope observability.ingest.write
const observability = new Observability(client);

const res = await observability.createIngestion({
    batch: [{
        id: crypto.randomUUID(),          // 外层幂等 ID:每个 create/update 事件用新的唯一值
        timestamp: new Date().toISOString(),
        type: 'trace-create',
        body: { id: traceId32Hex, name: 'agent-run' }   // body.id 是实体 ID,更新同一实体保持不变
    }]
});
// 全部成功 HTTP 200;任一失败 HTTP 207 Multi-Status,逐项检查 res.errors[],不能只看是否抛错

OTel Traces 上报

SDK 直传原始 OTLP body 并返回原始响应(本页给 Node SDK 与 REST 形态);其他语言可让 OpenTelemetry exporter 直连同一 REST 端点。

// createOtelTraces(body, contentType?) —— OTLP HTTP 形态(JSON/protobuf,可选 gzip)
const raw = await observability.createOtelTraces(otelBody);
// 不是 OTLP gRPC endpoint;适合接 OpenTelemetry exporter

查询与 Trace 日志

getStatus 为状态探测;Trace 日志查询是独立数据面(scope traceLogs.read)。

const status = await observability.getStatus();   // scope observability.status.read;返回 ingestionEndpoints
// 查询面另有 getTrace / listTraces / getSession / listSessions / getUser / listUsers / queryMetrics / listScores / listScoreConfigs

// Trace 日志:query 必填且只允许一个 traceId:<value> 或 executionId:<value>
const logs = await observability.listLogs({ query: `executionId:${execId}`, limit: 50 });

事实源