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:
Multi-tenant enterprise customer service and knowledge assistants: the backend holds a single Project API Key and, by passing the business system's own
userId(e.g.user_zhangwei_001,user_lina_002), isolates the session history and long-term memory of different end users while sharing the project-level knowledge base (kb_enterprise_support) and compliance lexicons (lex_enterprise_synonyms,lex_support_stopwords).Business tools and frontend interaction coordination: by binding an AI Gateway under the same project (
gw_7194685489feb1e169548619), the agent automatically calls controlled MCP / HTTP server-side tools during inference, or triggersCLIENTtools to be executed on the application side with results returned.High-reliability long tasks and mobile weak-network recovery: Run creation (
202 Accepted) and the SSE event stream (GET .../events) are decoupled; a brief client network interruption does not cancel the background Run. Reconnect withLast-Event-IDwhen needed; if the cursor expires, first query the existing Run state and persisted messages.
Prerequisites
| Configuration item / dependency | Requirements and examples (replace with values from the target environment) |
|---|---|
| API Endpoint | The target environment API endpoint (including /v1); project-level path prefix: /v1/agent-runtime/project |
| Owning organization and project | Organization: Agentbase 企业智能中台 (69c6d1aa00062e6bb60); project: 企业智能客服与知识中台 (Project ID: enterprise-ai-hub-210, Shared V2 storage mode) |
| Auth header and minimal scope | X-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 baseline | Node.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 userId | 1–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
Initialize the project workbench and save the run configuration: query the
/v1/agent-runtime/projectstatus → perform idempotent initializationPOST /v1/agent-runtime/project→ query available modelsGET .../models→ configurePATCH .../config, system prompt, context budget, and the Memory / Knowledge Search toggles viaqwen-plus.Bind project lexicons and the AI Gateway: mount the enterprise synonym and stopword lexicons via
PUT .../lexicons(configurestopIntercept: trueand compliance interception scriptsstopReply); bind an active AI Gateway viaPUT .../gateway.Upload and manage Skill packages: upload
.zip/.tar.gz/.tgzSkill packages containingSKILL.mdto/v1/agent-runtime/project/skillsviamultipart/form-data, allowing agents to read standard operating procedures on demand.Create sessions for business users and submit Runs idempotently: call
POST .../threadswith the business user'suserId(e.g.,user_zhangwei_001) to create a session → callPOST .../runswithIdempotency-Keyto submit the question (returns202 Acceptedandrun_id).Subscribe to the resumable SSE event stream and read the final message: call
GET .../runs/{runId}/events?userId=...to consume AG-UI events such asTEXT_MESSAGE_CONTENTandTOOL_CALL_*in real time and record the latest frameid; if the network disconnects, resume the same Run by passingLast-Event-ID; after receivingRUN_FINISHED, callGET .../runs/{runId}/messagesto read the persisted answer and knowledge references.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 viaPOST .../runs/{runId}/tool-messages; callPOST .../runs/{runId}/cancelexplicitly when a task needs to be terminated; audit Token consumption and context compaction records viaGET .../model-invocationsandGET .../context-compactions.
Key parameters and returns
| Endpoint / phase | Key input parameters and locations | Core return fields and handling points |
|---|---|---|
Update configuration PATCH /project/config | Body (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/lexicons | Body (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/skills | multipart/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/threads | Body: { "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/runs | Header: 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}/events | Query: 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-messages | Body: { "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 .../messages | Query: 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
Iron rules for user isolation and parameter placement:
userIdcan only be generated by mapping a real login session in a controlled backend; it is strictly forbidden to hand the Project API Key to the frontend and let the frontend fill inuserIditself.POSTEndpointsuserIdplace it in the JSON Body;GET/DELETEendpoints place it in the URL Query viauserId; omitting it, passing it twice, including a hyphen-, or using the reserved wordsystemall return400 general_argument_invalid. Cross-user access to anotheruserId's Thread/Run uniformly returns404 NOT_FOUND.Single-session concurrency exclusivity (
409 THREAD_BUSY): only one unfinished Run (includingWAITING_CLIENT_TOOLstatus) may exist at any moment for the samethread_id. To start a new conversation, you must first complete the current client tool return, or explicitly callPOST .../canceland wait for the status to converge toCANCELLED.SSE disconnection is not cancellation; when the cursor expires, read persisted facts first: closing the SSE connection does not stop the background Run. When the cache still has entries but
Last-Event-IDis too far behind, the endpoint may return409 stream_cursor_expired(containingearliest_event_idandlatest_event_id). The default retention is 30 minutes, measured from the Run deadline for ordinary events and from publication time for terminal events; the entry limit can evict older events sooner. If the entire cache is absent, terminal Runs or Runs waiting for a client tool may receive fallback events instead of 409 — in that case, first callGET .../runs/{runId}andGET .../messagesto restore the persisted state and messages; do not blindly create a new Run.Memory and PowerContext are mutually exclusive: in the same project configuration,
memory_enabledandpowercontext_enabledcannot both betrue; before enabling either capability, the corresponding project service must be initialized first, whileknowledge_search_enabledcan be freely combined with either one.Idempotency protection for external tool side effects: when a Run returns
TOOL_RESULT_UNKNOWNor a network timeout triggers a reconnect, the Runtime does not roll back write operations on external business systems; the client must deduplicate bytoolCallId, and business operations with side effects must first query the actual business state before deciding whether to retry.
SDK Category Differences
| SDK category and language coverage | Integration 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.