agentbase-docs

Agent Runtime(项目内托管智能体)

这是什么 / 何时用

Agent Runtime 是 Agentbase 的托管智能体运行面:把 Agent(模型、提示词、工具、Skill 包、Memory/Knowledge 绑定)作为持久资源运行,Run 事实持久化在服务端,事件经 SSE 增量投递、可断线恢复。2.7.0 起开放项目级 Server API(/agent-runtime/** 共 29 个端点),Web / Node / Python / Go / Java 各 SDK 均新增 AgentRuntime service;2.6.0 及更早版本没有该 service,只能经 Console 消费。

何时用:需要托管运行、断线恢复、工具调用、记忆与知识接入的智能体,而不是把 Agent loop 散落在前端代码里。

Console 的项目内「智能体工作台」保留为组织级演示入口:它走 /agent-runtime/project/** 按需初始化,与本文的 Agent/AgentVersion 产品线相互独立,且不生成到第三方 SDK。自动化与生产集成请用本文的项目级 API + SDK。

核心模型

资源关键边界
Agent组织级主体:name / description / execute(允许执行的角色);生命周期状态 active / disabled / archived
AgentVersionDRAFT 可稀疏更新配置、管理 Skill、绑定 Gateway、发起预览;PUBLISHED 配置不可变(一个 Agent 同时只有一个 Published Version);ARCHIVED 不可配置、不可预览、不接受新调用
Thread / RunRun 在既有 Thread 内创建(返回 202 JSON);Run admission 冻结 Version、Project、Principal 与有效配置快照
Skill package上传到 Draft Version(.zip / .tar.gz / .tgz),内容经 Storage 保存;真实凭据只保存环境变量名或受控引用
ToolClient Tool(客户端执行并回传)、MCP / AI Gateway Tool(服务端执行,受授权目录限制);普通 SERVER Tool runner 尚未提供,声明为 SERVER 会明确失败
EvaluationPublished 面接收 Langfuse 兼容的黑盒 E2E 评测(Dataset webhook envelope),按真实 Agent loop 执行

前置(三种权限面)

角色资源范围认证最小 scope
管理员Organization 下的 Agent / VersionConsole 管理员 Session / JWT + admin mode + Organizationprojects.write
开发者单个 Draft Version ProjectVersion Project API Keyagent-runtime.read / agent-runtime.write
使用者Published Version Project用户 Session / JWT,或仅含执行权限的 API Keyagent-runtime.execute

初始化要点:开发者与使用者面的 setProject 都填 Agent Version 路由标识(agentVersionId)而非普通项目 ID——SDK 把它作为 X-Appwrite-Project 头发送。外部身份不能携带内部 Service Token;Project、Agent Version 与 Published 指针必须一致,跨 Project 访问按未找到处理,不泄露目标资源。

Memory / Knowledge Bases / AI Gateway 等依赖能力按各自文档先配置好。

使用骨架

关键参数与返回

错误与边界

SDK 类别差异

SDKAgentRuntime 面
Node Server(server-sdk/nodejs.md)全量:Draft 配置 / Gateway / 模型 / readiness / Skill / 预览 + Published 调用与评测
Web(client-sdk/web.md)仅 Published 面:Thread / Run / SSE / 消息 / Tool 回传 / 评测;无 Draft 管理能力
Python / Go / Java Server与 Node 同面(Python snake_case 关键字参数、Go 位置参数 + With* 选项、Java 位置参数)
Console(Java / Python / Go)另含组织级 Agent / Version CRUD、发布与状态管理
Console JS(agentbase-console-sdk)无 AgentRuntime service,不要猜测 new AgentRuntime(client) 之类调用

各语言调用示例

每个卡片可切换语言页签(全页同步),卡片与「使用骨架」逐条对应。

Agent 与 Version 管理(组织级)

创建 Agent、创建 Draft Version、发布与状态管理在 Console SDK 的组织级面(Java / Python / Go 的 console 包,Console 管理员 Session + admin mode);JS Console SDK 无 AgentRuntime service,Node / Web 无此能力面,本卡不设对应页签。

import io.agentbase.console.Client;
import io.agentbase.console.services.AgentRuntime;
import java.util.List;

Client consoleClient = new Client()
    .setEndpoint("https://<HOSTNAME>/v1")
    .setProject("console")
    .setJWT("<ownerJwt>")          // 或登录后 setCookie
    .setOrganization("<organizationTeamId>")
    .setMode("admin");             // 管理面
AgentRuntime admin = new AgentRuntime(consoleClient);

// 创建 Agent(execute = 允许执行的角色)
var agent = admin.createAgent("订单客服", "处理订单咨询", List.of("any"));
// 创建 Draft Version(同时创建其 Version Project),发布后旧 Published 转 Archived
admin.createAgentVersion("<agentId>");
admin.publishAgentVersion("<agentId>", "<agentVersionId>");   // readiness 未过返回 409
// 生命周期:active / disabled / archived
admin.updateAgentStatus("<agentId>", io.agentbase.console.enums.Status.ACTIVE);

Draft 配置与就绪检查

开发者面(Version Project API Key):读写模型 / Memory / Knowledge Search / 执行上限配置,绑定 AI Gateway,发布前查 readiness。Web 面无 Draft 管理能力,本卡不设 Web 页签。

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

// 开发者面:setProject 填 Agent Version 路由标识
const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)
    .setProject(process.env.AGENT_VERSION_ID!)
    .setKey(process.env.AGENT_VERSION_API_KEY!);
const runtime = new AgentRuntime(client);

await runtime.updateAgentVersionConfig({
    agentVersionId: process.env.AGENT_VERSION_ID!,
    systemPrompt: '仅基于企业知识回答问题。',
    modelId: '<modelId>',
    modelParameters: { temperature: 0 },
    memoryEnabled: true,
    knowledgeSearchEnabled: true,
    contextWindowTokens: 8192,
    reservedOutputTokens: 1024,
    maxSteps: 12,
    maxDurationMs: 120000,
});
await runtime.updateAgentVersionGateway({ agentVersionId: '<agentVersionId>', gatewayId: '<gatewayId>' });
const models = await runtime.listAgentVersionModels({ agentVersionId: '<agentVersionId>' });
// 发布前:readiness 分项检查 model / gateway / memory / knowledge / skills,顶层 ready=true 才可发布
const readiness = await runtime.getAgentVersionReadiness({ agentVersionId: '<agentVersionId>' });

Skill 包管理

Skill 包(.zip / .tar.gz / .tgz)上传到 Draft Version,经 multipart 上传;真实凭据只保存环境变量名或受控引用。Web 面无此能力,本卡不设 Web 页签。

import { InputFile } from 'agentbase-node-sdk/file';   // InputFile 走 file 子路径导入

await runtime.createAgentVersionSkill({
    agentVersionId: '<agentVersionId>',
    file: InputFile.fromPath('./skills/order-lookup.zip', 'order-lookup.zip'),
});
await runtime.listAgentVersionSkills({ agentVersionId: '<agentVersionId>' });
await runtime.updateAgentVersionSkill({
    agentVersionId: '<agentVersionId>',
    skillId: '<skillId>',
    file: InputFile.fromPath('./skills/order-lookup-v2.zip', 'order-lookup.zip'),
});
await runtime.deleteAgentVersionSkill({ agentVersionId: '<agentVersionId>', skillId: '<skillId>' });

Draft 预览(Preview Thread / Run / SSE)

发布前在 Draft 上验证:预览 Thread → 预览 Run → SSE 事件 → 预览 Client Tool 回传;preview 方法面与 Published 面同构,作用域是 Draft Version。Web 面无预览能力,本卡不设 Web 页签。

const thread = await runtime.createPreviewThread({ agentVersionId: '<agentVersionId>' });
const run = await runtime.createPreviewRun({
    agentVersionId: '<agentVersionId>',
    threadId: thread.thread_id,
    userMessage: '帮我查一下订单 1001 的物流',
});
// SSE:连接后可断线续连;终态后读持久化消息
const stream = await runtime.streamPreviewRunEvents({ agentVersionId: '<agentVersionId>', runId: run.run_id });
// Run 等待 Client Tool 时回传(同一 Run):
await runtime.submitPreviewToolMessage({
    agentVersionId: '<agentVersionId>',
    runId: run.run_id,
    id: '<messageId>',
    role: 'tool',
    toolCallId: '<toolCallId>',
    content: '{"status":"shipped"}',
});
await runtime.cancelPreviewRun({ agentVersionId: '<agentVersionId>', runId: '<runId>' });   // 显式取消

Published Thread 与 Run(含 SSE 续连)

使用者面(用户 Session/JWT 或仅含 agent-runtime.execute 的 API Key):Thread 返回服务端固定的 agent_version_id,Run 返回 202 JSON,事件流是后续的 SSE GET。本卡各语言面齐全。

const thread = await runtime.createThread({ agentId: '<agentId>' });
// thread.agent_version_id 为服务端固定的 Published Version,后续调用都要带上
const run = await runtime.createRun({
    agentId: '<agentId>',
    agentVersionId: thread.agent_version_id,
    threadId: thread.thread_id,
    userMessage: '我的订单什么时候发货?',
});
// 202 JSON 不保持长连接;SSE 是独立 GET,断线用最后收到的 SSE id 续连同一 Run
const stream = await runtime.streamRunEvents({
    runId: run.run_id,
    agentVersionId: thread.agent_version_id,
});
// 收到 RUN_FINISHED / RUN_ERROR / RUN_CANCELLED 后读持久化消息:
const msgs = await runtime.listRunMessages({ runId: run.run_id, agentVersionId: thread.agent_version_id });

Client Tool 回传与 Run 控制

Run 进入 WAITING_CLIENT_TOOL 后,客户端执行 TOOL_CALL_* 事件携带的调用并回传同一 Run;取消必须显式调用,SSE 断开不等于取消。本卡各语言面齐全。

// 回传 Tool 结果(失败也回传同一结构并带 error):
await runtime.submitToolMessage({
    runId: '<runId>',
    agentVersionId: '<agentVersionId>',
    id: '<messageId>',
    role: 'tool',
    toolCallId: '<toolCallId>',
    content: '{"status":"shipped"}',
    // error: '工具执行失败原因',
});
await runtime.cancelRun({ runId: '<runId>', agentVersionId: '<agentVersionId>' });   // 显式取消
const run = await runtime.getRun({ runId: '<runId>', agentVersionId: '<agentVersionId>' });
const calls = await runtime.listModelInvocations({ runId: '<runId>', agentVersionId: '<agentVersionId>' });
const compactions = await runtime.listContextCompactions({
    agentId: '<agentId>', threadId: '<threadId>', agentVersionId: '<agentVersionId>',
});

Evaluation(黑盒 E2E)

对当前 Published Version 触发 Langfuse 兼容的 E2E 评测:每个 Dataset item 创建独立 Thread/Run,跑完整 Agent loop(Memory、RAG、Skill、Tool 都按真实链路执行),Trace 经 Observability 关联。本卡各语言面齐全。

// Published 身份 + agent-runtime.execute;Dataset webhook envelope 经回调交互
const evaluation = await runtime.evaluateAgent({ agentId: '<agentId>' });

示例指引

事实源