Docs
Contents

Agent Runtime (Project-level Agent Workbench)

Before integration, verify that the endpoint, project, and credentials belong to the same intended environment.

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 / dependencyRequirements and examples (replace with values from the target environment)
API EndpointThe target environment API endpoint (including /v1); project-level 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 (for project configuration management and session execution)
SDK version baselineNode.js: agentbase-node-sdk@2.12.0; Python: agentbase-python-sdk==2.12.0; Java: io.agentbase:agentbase-server-java:2.12.0; Go: the agentbase-go-sdk ZIP from Release 2.12.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.Project-shared configuration endpoints do not pass userId; 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.12.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 the project configuration and session endpoints covered here and the resumable SSE stream 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

This page retains the integration concepts and language guidance. The previous multilingual HTTP examples had credential redirect, failure handling, and Run cancellation sequencing issues and have been removed pending language-by-language validation. Use the linked product procedures and REST examples below, subject to the target environment's capabilities.

Keep project API keys on a controlled server. When implementing an HTTP client, disable automatic redirects for requests carrying keys; confirm HTTP 2xx and the response before starting the next operation. Do not put keys in a browser, command arguments, or logs.

1. Initialize the project workbench and save the run configuration

Read the workbench status, initialize it if needed, verify available project models, and update configuration. See the workbench overview and project configuration.

2. Bind project lexicons and the AI Gateway

Lexicons and the gateway are separately configurable; choose the capabilities you need rather than executing both automatically. See knowledge and lexicons and tools and skills.

3. Upload and manage Skill packages

Check the project permissions and archive contents before uploading; confirm the uploaded skill and quota in the response and list. See tools and skills.

4. Create sessions for business users and submit Runs idempotently

Create a thread and confirm success, take its returned thread_id, and submit the Run separately. Use a new Idempotency-Key for each new Run; reuse it only when retrying the same request. See threads and runs.

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

Persist each received event id and reconnect to the same Run with Last-Event-ID as needed. A closed stream does not mean the Run is complete. On HTTP 409, first query the existing Run state and persisted messages; do not create a replacement Run. See events and Run status.

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

When a Run waits for a client tool, return the result for the current Run and toolCallId. Cancellation is a separate operation used only when you intend to stop the Run. Reading model invocations is also a separate read-only operation. See tool returns and Run cancellation.

Example Guide