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 |
| AgentVersion | DRAFT 可稀疏更新配置、管理 Skill、绑定 Gateway、发起预览;PUBLISHED 配置不可变(一个 Agent 同时只有一个 Published Version);ARCHIVED 不可配置、不可预览、不接受新调用 |
| Thread / Run | Run 在既有 Thread 内创建(返回 202 JSON);Run admission 冻结 Version、Project、Principal 与有效配置快照 |
| Skill package | 上传到 Draft Version(.zip / .tar.gz / .tgz),内容经 Storage 保存;真实凭据只保存环境变量名或受控引用 |
| Tool | Client Tool(客户端执行并回传)、MCP / AI Gateway Tool(服务端执行,受授权目录限制);普通 SERVER Tool runner 尚未提供,声明为 SERVER 会明确失败 |
| Evaluation | Published 面接收 Langfuse 兼容的黑盒 E2E 评测(Dataset webhook envelope),按真实 Agent loop 执行 |
前置(三种权限面)
| 角色 | 资源范围 | 认证 | 最小 scope |
|---|---|---|---|
| 管理员 | Organization 下的 Agent / Version | Console 管理员 Session / JWT + admin mode + Organization | projects.write |
| 开发者 | 单个 Draft Version Project | Version Project API Key | agent-runtime.read / agent-runtime.write |
| 使用者 | Published Version Project | 用户 Session / JWT,或仅含执行权限的 API Key | agent-runtime.execute |
初始化要点:开发者与使用者面的 setProject 都填 Agent Version 路由标识(agentVersionId)而非普通项目 ID——SDK 把它作为 X-Appwrite-Project 头发送。外部身份不能携带内部 Service Token;Project、Agent Version 与 Published 指针必须一致,跨 Project 访问按未找到处理,不泄露目标资源。
Memory / Knowledge Bases / AI Gateway 等依赖能力按各自文档先配置好。
使用骨架
- (组织级)创建 Agent 与 Draft Version:Console SDK 创建 Agent → 创建 Draft Version(同时创建它的 Version Project)。
- 配置 Draft:读写 config(模型、Memory、Knowledge Search、执行上限)、绑定 Gateway、列出可用模型、上传 Skill 包;
readiness在发布前分项检查 model / gateway / memory / knowledge / skills。 - Draft 预览:建预览 Thread → 预览 Run → SSE 事件 → Client Tool 回传,验证通过后再发布。
- (组织级)发布:校验 readiness 并发布 Draft Version,旧 Published Version 转为 Archived。
- Published 调用:创建 Thread(返回服务端固定的
agent_version_id)→ 创建 Run(202,不保持长连接)→ 连接 SSE 事件流;断线用最后收到的 SSEid续连同一 Run;终态后读持久化消息。 - 工具与控制:Client Tool 结果回传同一 Run;显式取消 Run;读取 Run 消息、模型调用与 Thread 的 context compactions。
- 评测:对当前 Published Version 触发黑盒 E2E 评测。
关键参数与返回
updateAgentVersionConfig(Draft,稀疏更新,全部可选):systemPrompt(空串用平台默认)、memoryEnabled/knowledgeSearchEnabled、memoryEmbeddingModelId/memoryEmbeddingDimensions、modelId/modelParameters、contextWindowTokens/reservedOutputTokens/maxSteps/maxDurationMs。- 创建 Run:必填
agentVersionId/threadId/userMessage;返回 202 JSON(含run_id),不直接保持长连接。支持Idempotency-Key头(1–128 bytes):同 scope、同 key、同请求返回原 Run(200 +idempotent_replay=true);同 key 对应不同请求返回 409。调用方必须保存并复用 key。 - SSE 事件流:断线后把最后收到的 SSE
id作为lastEventId/Last-Event-ID重连同一 Run;收到RUN_FINISHED/RUN_ERROR/RUN_CANCELLED后读持久化消息。 - Tool 结果回传:必填
id/role/toolCallId/content,可选error;Tool 失败也用同一结构回传并带error。 - readiness:只有顶层
ready=true才能发布,未就绪发布返回 409。 - 列表方法统一
limit+after游标分页。 - Node / Web SDK 的 AgentRuntime 方法返回未建模的
Promise<{}>,字段名以 REST 响应(snake_case,如thread_id、agent_version_id、run_id)为准。
错误与边界
- Run 开始后再改 Draft 配置不影响进行中的 Run;结果与日志按启动时的配置快照解释。
- SSE 断开不会取消 Run;取消必须显式调用取消方法。游标早于 Redis 保留窗口时返回
409 stream_cursor_expired——此时先读持久化 Run / Message 终态,不新建重复 Run。 - Client Tool 未回传时 Run 处于等待工具结果状态;恢复必须回到同一 Run,不能新建第二个 Run。
- 未授权 MCP / AI Gateway Tool 不出现在目录中,直接调用也失败;
SERVERTool 明确返回不支持,不会假装执行成功。 - Client Tool 需先在 AI Gateway 创建为
MCP_CLIENT并绑定到 Draft Version;Agent Identity 必须为ACTIVE且显式配置toolAllowlist。tool_approval_required是独立的WAITING_TOOL_APPROVAL,不能当 Client Tool 处理;审批恢复必须复用原参数、原Idempotency-Key与 approval request ID。 - Memory / Knowledge / Gateway 调用使用平台签发的内部可信上下文,客户端不能覆盖 project、tenant 或 principal;观测只记录允许的固定字段,不默认记录原始 Prompt、Tool 参数或凭据。
- 删除或清理项目前,Agent、runtime binding 与 Skill object 参与清理门禁,不要绕过项目删除的 dry run 与逐项结果检查(见 organization/project-governance.md)。
SDK 类别差异
| SDK | AgentRuntime 面 |
|---|---|
| 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 无此能力面,本卡不设对应页签。
- Java(Console)
- Python(Console)
- Go(Console)
- REST(curl)
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);from agentbase_console.client import Client
from agentbase_console.enums.status import Status
from agentbase_console.services.agent_runtime import AgentRuntime
client = Client()
client.set_endpoint('https://<HOSTNAME>/v1')
client.set_project('console')
client.set_jwt('<ownerJwt>')
client.set_mode('admin') # 管理面
admin = AgentRuntime(client)
admin.create_agent(name='订单客服', description='处理订单咨询', execute=['any'])
admin.create_agent_version(agent_id='<agentId>') # 同时创建其 Version Project
admin.publish_agent_version(agent_id='<agentId>', agent_version_id='<agentVersionId>') # readiness 未过返回 409
admin.update_agent_status(agent_id='<agentId>', status=Status.ACTIVE) # active / disabled / archivedimport (
"agentbase-console-go-sdk/agentbase"
"agentbase-console-go-sdk/client"
)
cl := client.New(
agentbase.WithEndpoint("https://<HOSTNAME>/v1"),
agentbase.WithProject("console"),
agentbase.WithJWT("<ownerJwt>"),
agentbase.WithOrganization("<organizationTeamId>"),
agentbase.WithMode("admin"), // 管理面
)
admin := agentbase.NewAgentRuntime(cl)
admin.CreateAgent("订单客服",
admin.WithCreateAgentDescription("处理订单咨询"),
admin.WithCreateAgentExecute([]string{"any"}))
admin.CreateAgentVersion("<agentId>") // 同时创建其 Version Project
admin.PublishAgentVersion("<agentId>", "<agentVersionId>") // readiness 未过返回 409
admin.UpdateAgentStatus("<agentId>", "active") // active / disabled / archived# 组织级管理面:Console Session/JWT + admin mode + Organization 头
curl -sS -X POST "$APPBASE_ENDPOINT/agent-runtime/agents" \
-H 'Content-Type: application/json' \
-H 'X-Appwrite-Project: console' \
-H "X-Appwrite-JWT: $APPBASE_OWNER_JWT" \
-H 'X-Appwrite-Mode: admin' \
-H "X-Appwrite-Organization: $APPBASE_ORGANIZATION_TEAM_ID" \
-d '{"name":"订单客服","description":"处理订单咨询","execute":["any"]}'
# Draft Version:POST /agent-runtime/agents/{agentId}/versions
# 发布:POST /agent-runtime/agents/{agentId}/versions/{agentVersionId}/publish(readiness 未过 409)
# 状态:PATCH /agent-runtime/agents/{agentId}/status {"status":"active|disabled|archived"}Draft 配置与就绪检查
开发者面(Version Project API Key):读写模型 / Memory / Knowledge Search / 执行上限配置,绑定 AI Gateway,发布前查 readiness。Web 面无 Draft 管理能力,本卡不设 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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>' });import io.agentbase.services.AgentRuntime;
AgentRuntime runtime = new AgentRuntime(client); // client.setProject("<agentVersionId>").setKey(...)
runtime.updateAgentVersionConfig("<agentVersionId>",
"仅基于企业知识回答问题。", // systemPrompt
true, true, // memoryEnabled / knowledgeSearchEnabled
null, null, // memoryEmbeddingModelId / memoryEmbeddingDimensions
"<modelId>", null, // modelId / modelParameters
8192L, 1024L, 12L, 120000L);// contextWindowTokens / reservedOutputTokens / maxSteps / maxDurationMs
runtime.updateAgentVersionGateway("<agentVersionId>", "<gatewayId>");
runtime.listAgentVersionModels("<agentVersionId>");
runtime.getAgentVersionReadiness("<agentVersionId>"); // 顶层 ready=true 才可发布from agentbase.services.agent_runtime import AgentRuntime
runtime = AgentRuntime(client) # client.set_project('<agentVersionId>').set_key(...)
runtime.update_agent_version_config(
agent_version_id='<agentVersionId>',
system_prompt='仅基于企业知识回答问题。',
model_id='<modelId>',
model_parameters={'temperature': 0},
memory_enabled=True,
knowledge_search_enabled=True,
context_window_tokens=8192,
reserved_output_tokens=1024,
max_steps=12,
max_duration_ms=120000)
runtime.update_agent_version_gateway(agent_version_id='<agentVersionId>', gateway_id='<gatewayId>')
runtime.list_agent_version_models(agent_version_id='<agentVersionId>')
runtime.get_agent_version_readiness(agent_version_id='<agentVersionId>') # 顶层 ready=true 才可发布rt := agentbase.NewAgentRuntime(cl) // cl:client.New(WithEndpoint/WithProject("<agentVersionId>")/WithKey)
rt.UpdateAgentVersionConfig("<agentVersionId>",
rt.WithUpdateAgentVersionConfigSystemPrompt("仅基于企业知识回答问题。"),
rt.WithUpdateAgentVersionConfigModelId("<modelId>"),
rt.WithUpdateAgentVersionConfigMemoryEnabled(true),
rt.WithUpdateAgentVersionConfigKnowledgeSearchEnabled(true),
rt.WithUpdateAgentVersionConfigContextWindowTokens(8192),
rt.WithUpdateAgentVersionConfigMaxSteps(12))
rt.UpdateAgentVersionGateway("<agentVersionId>", "<gatewayId>")
rt.ListAgentVersionModels("<agentVersionId>")
rt.GetAgentVersionReadiness("<agentVersionId>") // 顶层 ready=true 才可发布# 开发者面:X-Appwrite-Project 填 Agent Version 路由标识 + Version Project API Key
curl -sS -X PATCH "$APPBASE_ENDPOINT/agent-runtime/agent-versions/$AGENT_VERSION_ID/config" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $AGENT_VERSION_ID" -H "X-Appwrite-Key: $AGENT_VERSION_API_KEY" \
-d '{"system_prompt":"仅基于企业知识回答问题。","model_id":"<modelId>","memory_enabled":true,"knowledge_search_enabled":true,"context_window_tokens":8192,"max_steps":12}'
# Gateway:GET/PUT .../agent-versions/{id}/gateway(PUT 体 {"gateway_id":"..."})
# 模型:GET .../agent-versions/{id}/models;就绪:GET .../agent-versions/{id}/readinessSkill 包管理
Skill 包(.zip / .tar.gz / .tgz)上传到 Draft Version,经 multipart 上传;真实凭据只保存环境变量名或受控引用。Web 面无此能力,本卡不设 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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>' });import io.agentbase.models.InputFile;
runtime.createAgentVersionSkill("<agentVersionId>",
InputFile.fromPath("./skills/order-lookup.zip"), null); // 末位为 onProgress 回调
runtime.listAgentVersionSkills("<agentVersionId>");
runtime.updateAgentVersionSkill("<agentVersionId>", "<skillId>",
InputFile.fromPath("./skills/order-lookup-v2.zip"), null);
runtime.deleteAgentVersionSkill("<agentVersionId>", "<skillId>");from agentbase.input_file import InputFile
runtime.create_agent_version_skill(
agent_version_id='<agentVersionId>',
file=InputFile.from_path('./skills/order-lookup.zip'))
runtime.list_agent_version_skills(agent_version_id='<agentVersionId>')
runtime.update_agent_version_skill(agent_version_id='<agentVersionId>', skill_id='<skillId>',
file=InputFile.from_path('./skills/order-lookup-v2.zip'))
runtime.delete_agent_version_skill(agent_version_id='<agentVersionId>', skill_id='<skillId>')import "agentbase-go-sdk/file"
rt.CreateAgentVersionSkill("<agentVersionId>",
file.NewInputFile("/path/to/order-lookup.zip", "order-lookup.zip"))
rt.ListAgentVersionSkills("<agentVersionId>")
rt.UpdateAgentVersionSkill("<agentVersionId>", "<skillId>",
file.NewInputFile("/path/to/order-lookup-v2.zip", "order-lookup.zip"))
rt.DeleteAgentVersionSkill("<agentVersionId>", "<skillId>")# multipart 上传 Skill 包(.zip / .tar.gz / .tgz)
curl -sS -X POST "$APPBASE_ENDPOINT/agent-runtime/agent-versions/$AGENT_VERSION_ID/skills" \
-H "X-Appwrite-Project: $AGENT_VERSION_ID" -H "X-Appwrite-Key: $AGENT_VERSION_API_KEY" \
-F 'file=@./skills/order-lookup.zip'
# 列表 GET .../skills;替换 PUT .../skills/{skillId};删除 DELETE .../skills/{skillId}Draft 预览(Preview Thread / Run / SSE)
发布前在 Draft 上验证:预览 Thread → 预览 Run → SSE 事件 → 预览 Client Tool 回传;preview 方法面与 Published 面同构,作用域是 Draft Version。Web 面无预览能力,本卡不设 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
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>' }); // 显式取消var thread = runtime.createPreviewThread("<agentVersionId>");
var run = runtime.createPreviewRun("<agentVersionId>", "<threadId>", "帮我查一下订单 1001 的物流");
runtime.streamPreviewRunEvents("<agentVersionId>", "<runId>"); // SSE,断线续连同一 Run
runtime.submitPreviewToolMessage("<agentVersionId>", "<runId>",
"<messageId>", "tool", "<toolCallId>", "{\"status\":\"shipped\"}", null);
runtime.cancelPreviewRun("<agentVersionId>", "<runId>"); // 显式取消thread = runtime.create_preview_thread(agent_version_id='<agentVersionId>')
run = runtime.create_preview_run(agent_version_id='<agentVersionId>',
thread_id=thread['thread_id'], user_message='帮我查一下订单 1001 的物流')
runtime.stream_preview_run_events(agent_version_id='<agentVersionId>', run_id=run['run_id']) # SSE 断线续连同一 Run
runtime.submit_preview_tool_message(agent_version_id='<agentVersionId>', run_id=run['run_id'],
id='<messageId>', role='tool', tool_call_id='<toolCallId>', content='{"status":"shipped"}')
runtime.cancel_preview_run(agent_version_id='<agentVersionId>', run_id='<runId>') # 显式取消thread, _ := rt.CreatePreviewThread("<agentVersionId>")
run, _ := rt.CreatePreviewRun("<agentVersionId>", "<threadId>", "帮我查一下订单 1001 的物流")
rt.StreamPreviewRunEvents("<agentVersionId>", "<runId>") // SSE,断线续连同一 Run
rt.SubmitPreviewToolMessage("<agentVersionId>", "<runId>",
"<messageId>", "tool", "<toolCallId>", "{\"status\":\"shipped\"}")
rt.CancelPreviewRun("<agentVersionId>", "<runId>") // 显式取消curl -sS -X POST "$APPBASE_ENDPOINT/agent-runtime/agent-versions/$AGENT_VERSION_ID/threads" \
-H "X-Appwrite-Project: $AGENT_VERSION_ID" -H "X-Appwrite-Key: $AGENT_VERSION_API_KEY"
curl -sS -X POST "$APPBASE_ENDPOINT/agent-runtime/agent-versions/$AGENT_VERSION_ID/runs" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $AGENT_VERSION_ID" -H "X-Appwrite-Key: $AGENT_VERSION_API_KEY" \
-d '{"thread_id":"<threadId>","user_message":"帮我查一下订单 1001 的物流"}'
# SSE:GET .../runs/{runId}/events;Tool 回传:POST .../runs/{runId}/tool-messages
# 取消:POST .../runs/{runId}/cancelPublished Thread 与 Run(含 SSE 续连)
使用者面(用户 Session/JWT 或仅含 agent-runtime.execute 的 API Key):Thread 返回服务端固定的 agent_version_id,Run 返回 202 JSON,事件流是后续的 SSE GET。本卡各语言面齐全。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
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 });import { Client, AgentRuntime } from 'agentbase-web-sdk';
const client = new Client()
.setEndpoint('https://<HOSTNAME>/v1')
.setProject('<agentVersionId>'); // Published Version 路由标识;用户 Session 认证
const runtime = new AgentRuntime(client);
const thread = await runtime.createThread({ agentId: '<agentId>' });
const run = await runtime.createRun({
agentId: '<agentId>',
agentVersionId: thread.agent_version_id,
threadId: thread.thread_id,
userMessage: '我的订单什么时候发货?',
});
const stream = await runtime.streamRunEvents({ runId: run.run_id, agentVersionId: thread.agent_version_id });var thread = runtime.createThread("<agentId>");
// thread 返回服务端固定的 agent_version_id,后续调用都要带上
var run = runtime.createRun("<agentId>", "<agentVersionId>", "<threadId>", "我的订单什么时候发货?");
runtime.streamRunEvents("<runId>", "<agentVersionId>"); // SSE 独立 GET,断线续连同一 Run
runtime.listRunMessages("<runId>", "<agentVersionId>", 50L, null); // 终态后读持久化消息thread = runtime.create_thread(agent_id='<agentId>')
# thread['agent_version_id'] 为服务端固定的 Published Version,后续调用都要带上
run = runtime.create_run(agent_id='<agentId>', agent_version_id=thread['agent_version_id'],
thread_id=thread['thread_id'], user_message='我的订单什么时候发货?')
runtime.stream_run_events(run_id=run['run_id'], agent_version_id=thread['agent_version_id']) # SSE 断线续连同一 Run
runtime.list_run_messages(run_id=run['run_id'], agent_version_id=thread['agent_version_id']) # 终态后读持久化消息thread, _ := rt.CreateThread("<agentId>")
// thread 返回服务端固定的 agent_version_id,后续调用都要带上
run, _ := rt.CreateRun("<agentId>", "<agentVersionId>", "<threadId>", "我的订单什么时候发货?")
rt.StreamRunEvents("<runId>", "<agentVersionId>") // SSE 独立 GET,断线续连同一 Run
rt.ListRunMessages("<runId>", "<agentVersionId>") // 终态后读持久化消息curl -sS -X POST "$APPBASE_ENDPOINT/agent-runtime/agents/$AGENT_ID/threads" \
-H "X-Appwrite-Project: $AGENT_VERSION_ID" -H "X-Appwrite-Key: $EXECUTE_API_KEY"
# Run 创建(202 JSON;支持 Idempotency-Key 头去重):
curl -sS -X POST "$APPBASE_ENDPOINT/agent-runtime/agents/$AGENT_ID/runs" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $AGENT_VERSION_ID" -H "X-Appwrite-Key: $EXECUTE_API_KEY" \
-H 'Idempotency-Key: order-query-20260918-01' \
-d '{"agent_version_id":"<agentVersionId>","thread_id":"<threadId>","user_message":"我的订单什么时候发货?"}'
# SSE(断线用 Last-Event-ID 续连同一 Run;游标过期返回 409 stream_cursor_expired):
curl -sS --get "$APPBASE_ENDPOINT/agent-runtime/runs/$RUN_ID/events" \
-H "X-Appwrite-Project: $AGENT_VERSION_ID" -H "X-Appwrite-Key: $EXECUTE_API_KEY" \
-H 'Last-Event-ID: <lastEventId>' \
--data-urlencode 'agent_version_id=<agentVersionId>'Client Tool 回传与 Run 控制
Run 进入 WAITING_CLIENT_TOOL 后,客户端执行 TOOL_CALL_* 事件携带的调用并回传同一 Run;取消必须显式调用,SSE 断开不等于取消。本卡各语言面齐全。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
// 回传 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>',
});// 与 Node 面同构:submitToolMessage / cancelRun / getRun / listModelInvocations / listContextCompactions
await runtime.submitToolMessage({
runId: '<runId>',
agentVersionId: '<agentVersionId>',
id: '<messageId>',
role: 'tool',
toolCallId: '<toolCallId>',
content: '{"status":"shipped"}',
});
await runtime.cancelRun({ runId: '<runId>', agentVersionId: '<agentVersionId>' });runtime.submitToolMessage("<runId>", "<agentVersionId>",
"<messageId>", "tool", "<toolCallId>", "{\"status\":\"shipped\"}", null); // 末位为 error
runtime.cancelRun("<runId>", "<agentVersionId>"); // 显式取消
runtime.getRun("<runId>", "<agentVersionId>");
runtime.listModelInvocations("<runId>", "<agentVersionId>", 50L, null);
runtime.listContextCompactions("<agentId>", "<threadId>", "<agentVersionId>", 50L, null);runtime.submit_tool_message(run_id='<runId>', agent_version_id='<agentVersionId>',
id='<messageId>', role='tool', tool_call_id='<toolCallId>',
content='{"status":"shipped"}') # error='<原因>' 可选
runtime.cancel_run(run_id='<runId>', agent_version_id='<agentVersionId>') # 显式取消
runtime.get_run(run_id='<runId>', agent_version_id='<agentVersionId>')
runtime.list_model_invocations(run_id='<runId>', agent_version_id='<agentVersionId>')
runtime.list_context_compactions(agent_id='<agentId>', thread_id='<threadId>',
agent_version_id='<agentVersionId>')rt.SubmitToolMessage("<runId>", "<agentVersionId>",
"<messageId>", "tool", "<toolCallId>", "{\"status\":\"shipped\"}",
rt.WithSubmitToolMessageError("<失败原因>")) // error 可选
rt.CancelRun("<runId>", "<agentVersionId>") // 显式取消
rt.GetRun("<runId>", "<agentVersionId>")
rt.ListModelInvocations("<runId>", "<agentVersionId>")
rt.ListContextCompactions("<agentId>", "<threadId>", "<agentVersionId>")# Tool 回传(等待中的 Run;agent_version_id 在请求体内)
curl -sS -X POST "$APPBASE_ENDPOINT/agent-runtime/runs/$RUN_ID/tool-messages" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $AGENT_VERSION_ID" -H "X-Appwrite-Key: $EXECUTE_API_KEY" \
-d '{"agent_version_id":"<agentVersionId>","id":"<messageId>","role":"tool","toolCallId":"<toolCallId>","content":"{\"status\":\"shipped\"}"}'
# 取消:POST /agent-runtime/runs/{runId}/cancel,体 {"agent_version_id":"..."}
# 事实读取:GET .../runs/{runId} | /messages | /model-invocations(query 带 agent_version_id)
# Thread 事实:GET .../agents/{agentId}/threads/{threadId}/messages | /context-compactionsEvaluation(黑盒 E2E)
对当前 Published Version 触发 Langfuse 兼容的 E2E 评测:每个 Dataset item 创建独立 Thread/Run,跑完整 Agent loop(Memory、RAG、Skill、Tool 都按真实链路执行),Trace 经 Observability 关联。本卡各语言面齐全。
- Node.js(Server)
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
// Published 身份 + agent-runtime.execute;Dataset webhook envelope 经回调交互
const evaluation = await runtime.evaluateAgent({ agentId: '<agentId>' });const evaluation = await runtime.evaluateAgent({ agentId: '<agentId>' });var evaluation = runtime.evaluateAgent("<agentId>");evaluation = runtime.evaluate_agent(agent_id='<agentId>')evaluation, err := rt.EvaluateAgent("<agentId>")curl -sS -X POST "$APPBASE_ENDPOINT/agent-runtime/agents/$AGENT_ID/evaluations" \
-H "X-Appwrite-Project: $AGENT_VERSION_ID" -H "X-Appwrite-Key: $EXECUTE_API_KEY"示例指引
- JavaScript(Node 初始化与 Agent Runtime 调用):examples/javascript.md 的「Agent Runtime」小节。
- 其他语言写法对照见各 SDK 轴页面:server-sdk/nodejs.md、server-sdk/java.md、server-sdk/python.md、server-sdk/go.md、client-sdk/web.md。
事实源
skills/ob-agentbase/references/agent-runtime.md(三种权限面、SSE 续连、幂等、Client Tool、Eval 口径)skills/ob-agentbase/references/release-2.7.0.md(Agent Runtime 为 2.7.0 能力增量;2.6.0 仅 Console 消费)- agentbase-sdks v2.8.0(tag
v2.8.0):specs/open-api3-latest-server.json(/agent-runtime/**29 个端点)与specs/open-api3-latest-console.json(组织级 Agent/Version 管理);packages/sdks/server-nodejs/src/services/agent-runtime.ts、client-web/src/services/agent-runtime.ts、server-python/agentbase/services/agent_runtime.py、server-go/agentruntime/、server-java/src/main/java/io/agentbase/services/AgentRuntime.java、console-java/console-python/console-go对应 service