Docs
Contents

Agent Runtime (Project-level Agent Workbench)

Overview and use cases

Agent Runtime (agent workbench) is a project-level managed agent runtime engine provided by Agentbase (/v1/agent-runtime/project/*). The business backend does not need to maintain the complex "Prompt assembly → model inference → tool calling → context compression → streaming push" ReAct loop at the application layer: simply configure a conversational model (e.g. qwen-plus), a system prompt, and the desired capability toggles (enterprise knowledge base retrieval Knowledge Search, long-term Memory or managed context PowerContext, project Lexicons, AI Gateway tools and Skill packs) in the current project, and then use the unified Project API Key to create continuous sessions (Threads) for different business end users (userId), submit tasks asynchronously (Runs), subscribe to AG-UI streaming events (SSE) with reconnection support, and in client tool scenarios pause, await the callback, and continue the same Run.

Typical use cases:

Prerequisites

Configuration item / dependencySpecification requirements and SIT demo coordinates
API Endpointhttps://appbuild-sit.oceanbase.com/v1 (project-level agent workbench path prefix: /v1/agent-runtime/project)
Owning organization and projectOrganization: Agentbase 企业智能中台 (69c6d1aa00062e6bb60); project: 企业智能客服与知识中台 (Project ID: enterprise-ai-hub-210, Shared V2 storage mode)
Auth header and minimal scopeX-Appwrite-Project: enterprise-ai-hub-210 + X-Appwrite-Key: <APPBASE_API_KEY>; the API Key must include the agent-runtime.project scope (covering the full set of 27 endpoints for configuration management and session execution)
SDK version baselineNode.js: agentbase-node-sdk@2.10.0; Python: agentbase-python-sdk==2.10.0; Java: io.agentbase:agentbase-server-java:2.10.0; Go: agentbase-go-sdk (v2.10.0)
Multi-user isolation parameter userId1–128 ASCII letters, digits, or underscores (^[A-Za-z0-9_]{1,128}$), case-insensitive (the server normalizes everything to lowercase); system is a reserved word.14 project-shared configuration endpoints do not pass userId; 13 user-level Thread/Run endpoints require userId (POST in the JSON Body, GET / DELETE in the URL Query)
Associated project resources (as needed)Chat models: qwen-plus / qwen-turbo (Provider: dashscope-prod); embedding model: text-embedding-v3 (1024 dimensions); knowledge base: kb_enterprise_support; lexicons: lex_enterprise_synonyms, lex_support_stopwords; AI Gateway: gw_7194685489feb1e169548619 (must be a Shared V2 project and the Gateway status must be ACTIVE)

Usage workflow

  1. Initialize the project workbench and save the run configuration: query the /v1/agent-runtime/project status → perform idempotent initialization POST /v1/agent-runtime/project → query available models GET .../models → configure PATCH .../config, system prompt, context budget, and the Memory / Knowledge Search toggles via qwen-plus.

  2. Bind project lexicons and the AI Gateway: mount the enterprise synonym and stopword lexicons via PUT .../lexicons (configure stopIntercept: true and compliance interception scripts stopReply); bind an active AI Gateway via PUT .../gateway.

  3. Upload and manage Skill packages: upload .zip / .tar.gz / .tgz Skill packages containing SKILL.md to /v1/agent-runtime/project/skills via multipart/form-data, allowing agents to read standard operating procedures on demand.

  4. Create sessions for business users and submit Runs idempotently: call POST .../threads with the business user's userId (e.g., user_zhangwei_001) to create a session → call POST .../runs with Idempotency-Key to submit the question (returns 202 Accepted and run_id).

  5. Subscribe to the resumable SSE event stream and read the final message: call GET .../runs/{runId}/events?userId=... to consume AG-UI events such as TEXT_MESSAGE_CONTENT and TOOL_CALL_* in real time and record the latest frame id; if the network disconnects, resume the same Run by passing Last-Event-ID; after receiving RUN_FINISHED, call GET .../runs/{runId}/messages to read the persisted answer and knowledge references.

  6. Handle Client Tool returns, explicit cancellation, and usage auditing: when the Run enters WAITING_CLIENT_TOOL, execute the locally approved tool and restore the same Run by returning the result via POST .../runs/{runId}/tool-messages; call POST .../runs/{runId}/cancel explicitly when a task needs to be terminated; audit Token consumption and context compaction records via GET .../model-invocations and GET .../context-compactions.

Key parameters and returns

Endpoint / phaseKey input parameters and locationsCore return fields and handling points
Update configuration PATCH /project/configBody (no userId): system_prompt, model_id, model_parameters (temperature/top_p), context_window_tokens, reserved_output_tokens, max_steps, max_duration_ms, memory_enabled, powercontext_enabled (mutually exclusive with Memory), knowledge_search_enabled, knowledge_base_ids (at most 100 IDs), memory_embedding_model_id, memory_embedding_dimensions.Returns the full Config object and the read-only config_hash. When a Run is accepted, the configuration snapshot for that run is frozen; modifying the configuration does not affect in-flight Runs.
Bind lexicons PUT /project/lexiconsBody (no userId): bindings: [{ lexiconId, priority }] (at most 100 entries), enabled: boolean, stopIntercept: boolean, stopReply: string (max 4096 characters).Returns the effective LexiconBindings. When stopIntercept is enabled, user input matching a stop entry will short-circuit and terminate the Run, directly returning stopReply.
Upload Skill POST /project/skillsmultipart/form-data (no userId): binary file field file (.zip / .tar.gz / .tgz, <= 10 MiB, root directory contains SKILL.md).201 Created, returning skill_id, name, description, front_matter, content_hash. The list endpoint additionally returns skill_count and skill_limit.
Create session POST /project/threadsBody: { "userId": "user_zhangwei_001" }.201 Created, returning thread_id, title (initial null), status: "ACTIVE". All subsequent operations on this Thread must use the same userId.
Create Run POST /project/runsHeader: Idempotency-Key (1–128 bytes); Body: { "userId", "thread_id", "user_message" }.First acceptance returns 202 Accepted (run_id, status: "QUEUED", created_at); replaying with the same idempotency key and same request body returns 200 OK and idempotent_replay: true.
SSE event stream GET /project/runs/{runId}/eventsQuery: userId; Header: Accept: text/event-stream, and on reconnection pass Last-Event-ID.Each frame contains the outer id, event, and data (JSON, containing type, messageId/toolCallId, delta, etc.). The outer id is used for Last-Event-ID resumption and must not be confused with the message sequence number message_seq.
Return tool result POST /project/runs/{runId}/tool-messagesBody: { "userId", "id", "role": "tool", "toolCallId", "content", "error" } (error optional), where content must be a JSON-serialized string (e.g., "{\"status\":\"shipped\"}").202 Accepted, returning Run (status returns to QUEUED to continue executing the same Run; a second Run is not created).
Message pagination GET .../messagesQuery: userId, after (default 0, pass the message_seq of the last item on the previous page), limit (default 100, 1–1000).Returns a Message[] array (message_id, message_seq, message_type, payload, tool_call_id, trace_id).

Errors and boundaries

SDK Category Differences

SDK category and language coverageIntegration approach for the project-level agent workbench (/v1/agent-runtime/project/*)
Node.js Server SDK (server-sdk/nodejs.md)Initialize the agentbase-node-sdk@2.10.0's Client (set the Endpoint, Project ID enterprise-ai-hub-210, and an API Key containing agent-runtime.project); reuse the project authentication header and call all 27 endpoints and the resumable SSE stream of /v1/agent-runtime/project/* via native fetch / Web Streams.
Java / Python / Go Server SDK (server-sdk/java.md, server-sdk/python.md, server-sdk/go.md)Same as Node.js: hold the Project API Key on a controlled server, and connect to the project-level agent workbench with a standard HTTP/SSE client carrying X-Appwrite-Project, X-Appwrite-Key, and the business userId.
Web Client SDK (client-sdk/web.md)The browser frontend must not hold the Project API Key and does not directly call /v1/agent-runtime/project/*; the frontend submits questions through endpoints wrapped by the business backend and consumes the SSE event stream forwarded by the backend.
Console SDK (console-sdk/nodejs.md)Used to create projects and issue Project API Keys containing the agent-runtime.project Scope.

Examples by language

Each card has switchable language tabs (synchronized across the full page); the cards correspond one-to-one with the entries in the "Usage workflow".

1. Initialize the project workbench and save the run configuration

Initialize the project agent workbench (POST /v1/agent-runtime/project), query available models (GET .../models), and configure qwen-plus, the system prompt, the context window budget, and enable Memory and enterprise knowledge base retrieval (kb_enterprise_support) via PATCH .../config. The project configuration endpoint does not require passing userId.

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

const ENDPOINT = process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1';
const PROJECT_ID = process.env.APPBASE_PROJECT_ID ?? 'enterprise-ai-hub-210';
const API_KEY = process.env.APPBASE_API_KEY!; // Requires the agent-runtime.project scope

// The Server SDK Client manages project coordinates uniformly while constructing project-level Runtime request headers
const client = new Client()
    .setEndpoint(ENDPOINT)
    .setProject(PROJECT_ID)
    .setKey(API_KEY);

const headers = {
    'X-Appwrite-Project': PROJECT_ID,
    'X-Appwrite-Key': API_KEY,
    'Content-Type': 'application/json',
};

// 1. Idempotently initialize the project Agent Runtime (repeated calls do not clear existing data)
await fetch(`${ENDPOINT}/agent-runtime/project`, {
    method: 'POST',
    headers,
    body: JSON.stringify({}),
});

// 2. List models available to the current project (confirm qwen-plus has chat capability)
const modelsRes = await fetch(`${ENDPOINT}/agent-runtime/project/models`, { headers });
const { models } = await modelsRes.json();

// 3. Sparsely update the project agent workbench configuration
const configRes = await fetch(`${ENDPOINT}/agent-runtime/project/config`, {
    method: 'PATCH',
    headers,
    body: JSON.stringify({
        system_prompt: '你是企业智能客服与知识中台助手,请优先检索企业知识库回答问题,保留引用来源。',
        model_id: 'qwen-plus',
        model_parameters: { temperature: 0.3, top_p: 0.9 },
        context_window_tokens: 32768,
        reserved_output_tokens: 2048,
        max_steps: 12,
        max_duration_ms: 120000,
        memory_enabled: true,
        powercontext_enabled: false,
        knowledge_search_enabled: true,
        knowledge_base_ids: ['kb_enterprise_support'],
        memory_embedding_model_id: 'text-embedding-v3',
        memory_embedding_dimensions: 1024,
    }),
});
const config = await configRes.json();
console.log('Saved config_hash:', config.config_hash, 'models count:', models.length);

2. Bind project lexicons and the AI Gateway

Bind the synonym lexicon (lex_enterprise_synonyms) and stopword lexicon (lex_support_stopwords) via PUT /v1/agent-runtime/project/lexicons, and enable stopword blocking (stopIntercept: true); bind an active AI Gateway via PUT /v1/agent-runtime/project/gateway (gw_7194685489feb1e169548619).

// 1. Bind the project lexicon and enable stopword short-circuit interception
await fetch(`${ENDPOINT}/agent-runtime/project/lexicons`, {
    method: 'PUT',
    headers,
    body: JSON.stringify({
        enabled: true,
        stopIntercept: true,
        stopReply: '您好,您咨询的内容涉及企业受限或违规词条,当前请求已被拦截,请联系人工客服处理。',
        bindings: [
            { lexiconId: 'lex_enterprise_synonyms', priority: 1 },
            { lexiconId: 'lex_support_stopwords', priority: 2 },
        ],
    }),
});

// 2. Bind an AI Gateway in ACTIVE status within the same project
await fetch(`${ENDPOINT}/agent-runtime/project/gateway`, {
    method: 'PUT',
    headers,
    body: JSON.stringify({
        gateway_id: 'gw_7194685489feb1e169548619',
    }),
});

3. Upload and manage Skill packages

Upload .zip / .tar.gz / .tgz Skill packages containing SKILL.md to /v1/agent-runtime/project/skills via multipart/form-data, with support for list queries, full replacement, and deletion.

import { readFile } from 'node:fs/promises';

const zipBytes = await readFile('./skills/enterprise-order-sop.zip');
const form = new FormData();
form.append('file', new Blob([zipBytes], { type: 'application/zip' }), 'enterprise-order-sop.zip');

// 1. Upload the Skill package (note: do not set Content-Type manually; FormData generates the multipart boundary automatically)
const uploadRes = await fetch(`${ENDPOINT}/agent-runtime/project/skills`, {
    method: 'POST',
    headers: {
        'X-Appwrite-Project': PROJECT_ID,
        'X-Appwrite-Key': API_KEY,
    },
    body: form,
});
const skill = await uploadRes.json();

// 2. List the project's uploaded Skill packages and quotas (skill_count / skill_limit)
const listRes = await fetch(`${ENDPOINT}/agent-runtime/project/skills`, {
    headers: { 'X-Appwrite-Project': PROJECT_ID, 'X-Appwrite-Key': API_KEY },
});
const skillList = await listRes.json();
console.log('Uploaded skill:', skill.skill_id, 'Quota:', skillList.skill_count, '/', skillList.skill_limit);

4. Create sessions for business users and submit Runs idempotently

Create a session for business user user_zhangwei_001 (POST /v1/agent-runtime/project/threads, with userId in the JSON Body), and asynchronously submit a Run with Idempotency-Key in that session (POST /v1/agent-runtime/project/runs, returning 202 Accepted).

const userId = 'user_zhangwei_001';

// 1. Create a session for the business user (POST request: userId goes in the JSON Body)
const threadRes = await fetch(`${ENDPOINT}/agent-runtime/project/threads`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ userId }),
});
const thread = await threadRes.json(); // { thread_id, title, status: 'ACTIVE' }

// 2. Asynchronously submit a Run with an Idempotency-Key (returns 202 Accepted and run_id)
const runRes = await fetch(`${ENDPOINT}/agent-runtime/project/runs`, {
    method: 'POST',
    headers: {
        ...headers,
        'Idempotency-Key': 'req_zhangwei_20261022_001',
    },
    body: JSON.stringify({
        userId,
        thread_id: thread.thread_id,
        user_message: '请帮我查询订单 ORD-20261022-889 的发货状态,并说明跨月退货如何处理增值税专用发票。',
    }),
});
const run = await runRes.json(); // { run_id, status: 'QUEUED', created_at }
console.log('Created thread:', thread.thread_id, 'Run queued:', run.run_id);

5. Subscribe to the resumable SSE event stream and read the final message

Send a GET to /v1/agent-runtime/project/runs/{runId}/events?userId=... (GET request with userId in the Query), parse AG-UI events in real time and save the latest outer frame id; on disconnection, resume the same Run by passing Last-Event-ID; after receiving the terminal event, read the persisted messages via GET .../messages.

async function consumeRunEvents(runId: string, userId: string, lastEventId?: string) {
    const eventHeaders: Record<string, string> = {
        'X-Appwrite-Project': PROJECT_ID,
        'X-Appwrite-Key': API_KEY,
        Accept: 'text/event-stream',
    };
    if (lastEventId) {
        eventHeaders['Last-Event-ID'] = lastEventId; // On reconnect after disconnect, resume from the breakpoint
    }

    const res = await fetch(
        `${ENDPOINT}/agent-runtime/project/runs/${encodeURIComponent(runId)}/events?userId=${encodeURIComponent(userId)}`,
        { headers: eventHeaders }
    );
    if (res.status === 409) {
        // Cursor expired (stream_cursor_expired): first read the persisted Run state and messages; do not create a duplicate Run
        console.warn('SSE cursor expired, falling back to persisted messages');
        return;
    }

    const reader = res.body!.pipeThrough(new TextDecoderStream()).getReader();
    let buffer = '';
    let currentId = lastEventId;

    while (true) {
        const { value, done } = await reader.read();
        if (done) break;
        buffer += value;
        const frames = buffer.split('\n\n');
        buffer = frames.pop() ?? '';
        for (const frame of frames) {
            for (const line of frame.split('\n')) {
                if (line.startsWith('id: ')) currentId = line.slice(4).trim();
                if (line.startsWith('data: ')) {
                    const event = JSON.parse(line.slice(6));
                    if (event.type === 'TEXT_MESSAGE_CONTENT') {
                        process.stdout.write(event.delta);
                    }
                }
            }
        }
    }

    // After final state, read persisted messages using the message_seq cursor
    const msgRes = await fetch(
        `${ENDPOINT}/agent-runtime/project/runs/${encodeURIComponent(runId)}/messages?userId=${encodeURIComponent(userId)}&after=0&limit=100`,
        { headers: { 'X-Appwrite-Project': PROJECT_ID, 'X-Appwrite-Key': API_KEY } }
    );
    return { lastEventId: currentId, messages: await msgRes.json() };
}

6. Handle Client Tool returns, explicit cancellation, and usage auditing

When the Run enters WAITING_CLIENT_TOOL, call POST /v1/agent-runtime/project/runs/{runId}/tool-messages to return the tool result and restore the same Run; call POST .../cancel when a task needs to be terminated; and read per-step Token consumption and context compaction events via GET .../model-invocations and GET .../context-compactions.

// 1. Return the client tool execution result (content must be a JSON-serialized string; an error field can be passed on failure)
await fetch(`${ENDPOINT}/agent-runtime/project/runs/${encodeURIComponent(run.run_id)}/tool-messages`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
        userId,
        id: 'tmsg_01ja9x9c4d5e6f7g8h9j0k1l2m',
        role: 'tool',
        toolCallId: 'call_order_lookup_001',
        content: JSON.stringify({ order_id: 'ORD-20261022-889', status: 'shipped', carrier: 'SF-Express' }),
    }),
});

// 2. Explicitly cancel a running Run (disconnecting the SSE stream does not cancel the Run)
await fetch(`${ENDPOINT}/agent-runtime/project/runs/${encodeURIComponent(run.run_id)}/cancel`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ userId }),
});

// 3. Query the model call Token consumption and latency records for a single Run (GET request: userId in the Query)
const invocationsRes = await fetch(
    `${ENDPOINT}/agent-runtime/project/runs/${encodeURIComponent(run.run_id)}/model-invocations?userId=${encodeURIComponent(userId)}`,
    { headers: { 'X-Appwrite-Project': PROJECT_ID, 'X-Appwrite-Key': API_KEY } }
);
const invocations = await invocationsRes.json();

// 4. Query a session's automatic context compaction records
const compactionsRes = await fetch(
    `${ENDPOINT}/agent-runtime/project/threads/${encodeURIComponent(thread.thread_id)}/context-compactions?userId=${encodeURIComponent(userId)}`,
    { headers: { 'X-Appwrite-Project': PROJECT_ID, 'X-Appwrite-Key': API_KEY } }
);
const compactions = await compactionsRes.json();
console.log('Model steps:', invocations.items.length, 'Compactions:', compactions.items.length);

Example Guide