Docs
Contents

Agent Model, Prompts, Context Compaction, and Lexicon Interception Configuration

The project workbench knowledge-base selection guidance has been checked against the 2.12.0 release code; other operations depend on the deployed environment.

In the agent workbench (Agent Runtime), the runtime configuration (Config) and project-level lexicon binding (Lexicon Bindings) together determine the agent's reasoning brain, role boundaries, per-task cost ceiling, and the compliance/security posture of the conversation entry point. By carefully orchestrating, within the project's 企业智能客服与知识中台 (enterprise-ai-hub-210), the main conversation model (e.g., qwen-plus), sampling parameters, system prompts, context window budget, automatic context compaction, and stopword pre-interception (stopIntercept), enterprises can maintain long-conversation coherence while manage token budgets and intercept inputs that match lexicon rules.


Feature Overview

In long-cycle, high-concurrency enterprise agent operations, configuration management typically faces three major engineering challenges: first, multiple people tuning parameters simultaneously in the Console can overwrite each other, or mistakenly believe that changing the configuration mid-run alters a task already in progress; second, multi-turn troubleshooting conversations can easily blow up the model's context window, causing subsequent turns to fail directly with a token-limit error; third, users' colloquial jargon (such as OB, 4024) lowers retrieval hit rates, while violating words or jailbreak instructions sent directly to the large model waste inference compute for nothing.

The Agent Runtime configuration center addresses these pain points with four core governance mechanisms:

  1. Project-level model selection and fine-grained sampling parameter control (/v1/agent-runtime/project/models & /config):

    • Automatically discovers models with chat capability that are enabled for the project in Model (LLM Gateway) (e.g., qwen-plus and qwen-turbo under dashscope-prod).

    • Supports explicitly setting model_parameters.temperature (temperature, controlling generation randomness) and model_parameters.top_p (nucleus sampling threshold), or passing an empty object {} / null to restore the model's default sampling strategy.

  2. Optimistic autosave and runtime configuration snapshot isolation:

    • The configuration panel on the right side of the Console supports real-time autosave; every read or update returns a unique read-only configuration summary config_hash; when concurrent modifications by multiple people on the same project cause a conflict, the server returns HTTP 409 STATE_CONFLICT, forcing the client to fetch the latest configuration, merge, and resubmit to prevent silent overwrites.

    • Configuration snapshot locking rule: each Run locks in the then-valid configuration at the instant it is accepted by the server (202 Accepted); any subsequent changes to the project configuration only take effect for newly created Run and never interfere with in-flight tasks.

  3. Context window budget, execution guardrails, and automatic context compaction:

    • context_window_tokens (total context window) and reserved_output_tokens (reserved output budget) strictly constrain the per-step model input capacity, while max_steps (maximum reasoning steps) and max_duration_ms (maximum runtime) prevent tool dead loops.

    • When the accumulated history of a single session (Thread) approaches the available input budget, the Runtime automatically triggers context compaction — distilling earlier conversation turns into a high-density structured summary while fully preserving the recent fresh conversation tail (Fresh Tail), and exposing the entire compaction process via the /context-compactions audit interface and SSE events.

  4. Project-level lexicon binding and zero-token pre-compliance interception (/v1/agent-runtime/project/lexicons):

    • Supports mounting up to 100 project-level lexicons (e.g., lex_enterprise_synonyms and lex_support_stopwords) by priority (priority: 1..100).

    • After enabling stopIntercept: true and setting a custom compliance reply stopReply, once user input matches a stop (stop/restricted) entry in the lexicon, the Runtime short-circuits at the conversation entry layer and returns stopReply, with zero large-model token consumption, completing the compliance block.


Core Concepts and Architecture

Full Field Specification and Production Recommendation Table for Runtime Configuration (Config)

When reading the project runtime configuration via GET /v1/agent-runtime/project/config or updating it via PATCH /v1/agent-runtime/project/config, the type, constraints, and production benchmark values of each field are as follows:

Field NameTypeRequired / Nullable RuleProduction Benchmark Value (enterprise-ai-hub-210)Semantic Description and Engineering Boundary Constraints
model_idstringRequired on first save"qwen-plus"Must be a model ID with chat capability from the list returned by GET /models. When not configured it is null, and no Run can be started.
model_parametersobject | nullRequired on first save{"temperature": 0.3, "top_p": 0.9}Only temperature (0–1) and top_p (0–1) are supported. Note: when PATCH, the entire object is replaced rather than merged key by key; passing {} or null clears the explicit sampling parameters.
system_promptstring | nullOptional (may be null)"你是 Agentbase 企业智能客服与技术支持专家..."Defines the agent's role, answering style, and citation conventions. Note: the system prompt cannot substitute for server-side permission control; if JSON-formatted answers are required, agree on it here and validate at the application layer.
context_window_tokensintegerRequired on first save (> 0)65536 (or 32768)The total model context window token count adopted by this configuration; must be less than or equal to the real maximum window supported by the selected physical model (e.g., qwen-plus).
reserved_output_tokensintegerRequired on first save4096 (or 8192)The output token budget reserved for a single model generation; must satisfy 0 < reserved_output_tokens < context_window_tokens.
max_stepsintegerRequired on first save (> 0)16 (common range 8–64)The maximum number of ReAct model reasoning steps allowed per Run (must not exceed the instance deployment limit; default limit 64), preventing infinite tool-call loops.
max_duration_msintegerRequired on first save (> 0)180000 (commonly 120000–600000)The maximum end-to-end execution time in milliseconds per Run (e.g., 180000 means 3 minutes; the deployment limit is usually 600000, i.e., 10 minutes); on timeout the task is terminated and marked RUN_DEADLINE_EXCEEDED.
knowledge_search_enabledbooleanRequired on first savetrueWhether to allow the agent to invoke the built-in knowledge_retrieve tool to search the project knowledge base.
knowledge_base_idsstring[] | nullRequired when knowledge retrieval is enabled["kb_enterprise_support"]The server API accepts at most 100 unique knowledge base IDs from the same project; the project workbench console allows up to 10 selections. When newly enabling knowledge_search_enabled: true, it must not be an empty array; when retrieval is disabled, the selected list may be retained for one-click restoration later.
memory_enabledbooleanRequired on first savetrue (mutually exclusive with powercontext_enabled)Whether to enable project long-term memory (Memory) retrieval and writing. Project Memory initialization (Shared V2 mode) must be completed first.
memory_embedding_model_idstring | nullOptional"text-embedding-v3"The Embedding model ID associated with Memory; it must match the model actually used for project Memory initialization.
memory_embedding_dimensionsinteger | nullOptional (> 0)1024The vector dimension associated with Memory (e.g., text-embedding-v3 corresponds to 1024 dimensions).
powercontext_enabledbooleanRequired on first savefalse (mutually exclusive with memory_enabled)Whether to enable the PowerContext persistent context service. Strictly mutually exclusive with memory_enabled; setting both to true in the same request will be rejected by the server (HTTP 400).
config_hashstringRead-only output field"cfg_9f8e7d6c5b4a3210"The server-computed hash of the current configuration snapshot. Used to identify configuration versions; never pass it back as an input field to PATCH /config.

Roles, Entry Points, and Relationships

Configuration and Lexicon Governance Interfaces and Permissions Quick Reference

Feature ModuleConsole Operation LocationREST API EndpointRequired Role / API Key ScopeWhether userId Is RequiredEffective Timing Notes
List available modelsRight column of the workbench → Model dropdownGET /v1/agent-runtime/project/modelsRoles: owner, admin, developer, editor
Scope: agent-runtime.project
Not required (project-shared)Newly added or enabled Chat models in Model (/llm-gateway) become visible immediately
Read / update run configurationRight column of the workbench → prompt, parameters, and capability toggles panelGET /v1/agent-runtime/project/config
PATCH /v1/agent-runtime/project/config
Roles: owner, admin, developer, editor
Scope: agent-runtime.project
Not required (project-shared)After a successful save, changes take effect immediately for newly created Runs; running Runs are not affected
View context compaction recordsMiddle column of the workbench → the "context compacted" node in the conversation timelineGET /v1/agent-runtime/project/threads/{threadId}/context-compactionsRoles: owner, admin, developer, editor, analyst
Scope: agent-runtime.project
Required (Query parameter ?userId=...)Written in real time when conversation history triggers automatic compaction; up to 1000 context events are returned
Bind project intervention lexiconsRight column of the workbench → Lexicon settings (Lexicons) areaGET /v1/agent-runtime/project/lexicons
PUT /v1/agent-runtime/project/lexicons
Roles: owner, admin, developer, editor
Scope: agent-runtime.project
Not required (project-shared)PUT After the binding relationships are replaced wholesale, rewrites and stopIntercept interception take effect immediately in the next conversation turn

Feature Details and Operation Guide

1. Select a DashScope chat model and adjust sampling and the system prompt

  1. Log in to the Console and go to /console/project-default-enterprise-ai-hub-210/agent-runtime. In the Model dropdown at the top of the configuration panel on the right, select dashscope-prod's qwen-plus (the main model for complex reasoning and tool calling) or qwen-turbo (a low-latency lightweight Q&A model).

    Important note: A model appearing in the model dropdown only means the project has registered that model catalog in the LLM Gateway; it does not mean the upstream provider's API Key balance, network connectivity, or quota is necessarily healthy. After switching to a new model, be sure to send a test message in the middle conversation area to verify actual availability.

  2. Expand Model Parameters:

    • Set temperature to 0.3 (in enterprise customer service and troubleshooting Q&A, a lower temperature significantly suppresses hallucinations caused by the model improvising, ensuring rigor in tool parameters and technical commands);

    • Set top_p to 0.9 or 1.0.

  3. Write structured instructions in the System Prompt text box, clarifying the role positioning, tool usage priorities, and boundary constraints:

    你是 Agentbase 企业智能客服与技术支持专家(服务于「企业智能客服与知识中台」项目)。
    请严格遵守以下工作准则:
    1. 回答关于 OceanBase 架构、向量索引排障(如 4013/4024 错误码)、AI 网关路由计费及客服 SOP 的问题时,必须优先调用知识库检索工具查阅《kb_enterprise_support》中的权威文档,并在回答中明确引用来源文档标题。
    2. 若检索结果与用户问题无关或证据不足,请如实说明“当前知识库暂无相关记录,建议提交人工工单”,严禁编造配置参数、SQL 视图名或价格数字。
    3. 涉及订单或工单状态查询时,请调用已绑定的 AI Gateway 业务工具获取实时状态。
  4. After making changes, there is no need to manually look for a submit button — the panel automatically issues a sparse PATCH /v1/agent-runtime/project/config request and updates the display in the top-right corner with All changes saved. To perform a server-side partial update of the prompt and temperature (keeping other fields unchanged), execute:

    (
      set +x
      set -o pipefail
      : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
    builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X PATCH "${APPBASE_ENDPOINT}/agent-runtime/project/config" \
      -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
      --header @- \
      -H "Content-Type: application/json" \
      -d '{
        "system_prompt": "你是 Agentbase 企业智能客服与技术支持专家,请严格基于知识库证据与工具返回结果回答问题,并在结尾标注参考来源。",
        "model_parameters": {
          "temperature": 0.2,
          "top_p": 0.9
        }
      }'
    )

2. Plan the context window budget and understand automatic Context Compaction

1. Why can't the entire context_window_tokens be left for user input?

In every ReAct model call step, the total input tokens sent to the large model are divided among the following five parts: $$\text{Total Input Tokens} = T_{\text{system_prompt}} + T_{\text{tool_schemas}} + T_{\text{memory_recall}} + T_{\text{history_or_summary}} + T_{\text{fresh_tail}}$$ And the following must be satisfied: $$\text{Total Input Tokens} + \text{reserved_output_tokens} \le \text{context_window_tokens}$$ Therefore:

2. How automatic Context Compaction works and how to audit it

When a user has gone through more than a dozen rounds of troubleshooting Q&A in the same Thread and invoked knowledge base retrieval multiple times, the accumulated history message tokens approach the input budget limit. At that point the Agent Runtime automatically triggers Context Compaction:

  1. Compaction process: The Runtime launches an internal model call (recorded in model-invocations as purpose: "CONTEXT_COMPACTION") that distills earlier conversation turns into a compact context Summary, while preserving the fresh tail of the most recent turns as-is (Fresh Tail, containing the current in-progress question and recent tool context). It then assembles subsequent model input from "Summary + Fresh Tail" to continue completing the current Run.

  2. Important distinctions:

    • Context compaction $\neq$ deleting conversation history: Compaction only changes how the context fed into subsequent model inference is assembled; calling GET /threads/{threadId}/messages can still fully read all original history messages starting from message_seq = 1.

    • Context compaction $\neq$ PowerContext compression: The Runtime's built-in context compaction only applies to the short-term session window of the current Thread, and is not equivalent to the PowerContext service's cross-session persistent context compression (/v1/projects/{projectId}/powercontext/compaction).

  3. Observing context compaction events via SSE and the REST API:

    • Real-time SSE notification: When subscribing to /runs/{runId}/events, the client receives an extended event with type: "CUSTOM" and name: "appbase.context.compaction", where value contains status (started / completed / failed), eventSeq, and on failure failureCode.

    • Query thread-level context compaction history (GET /v1/agent-runtime/project/threads/{threadId}/context-compactions):

      (
        set +x
        set -o pipefail
        : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
      builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/threads/thd_01j8x9k2m4n6p8q0r2s4t6u8v0/context-compactions?userId=user_zhangwei_001" \
        -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
        --header @-
      )

      Expected successful response (HTTP 200 OK):

      {
        "items": [
          {
            "run_id": "run_01j8x9k5a7b9c1d3e5f7g9h1j3",
            "event_seq": 14,
            "type": "CONTEXT_COMPACTION_STARTED",
            "payload": [],
            "created_at": "2026-10-22T09:28:10Z"
          },
          {
            "run_id": "run_01j8x9k5a7b9c1d3e5f7g9h1j3",
            "event_seq": 18,
            "type": "CONTEXT_COMPACTION_COMPLETED",
            "payload": [],
            "created_at": "2026-10-22T09:28:12Z"
          }
        ]
      }

      Note: For privacy and payload size control, this public API returns a timeline of compaction lifecycle events (including CONTEXT_COMPACTION_STARTED, CONTEXT_COMPACTION_COMPLETED, CONTEXT_COMPACTION_FAILED, and RUN_FINISHED / RUN_ERROR for auxiliary timeline alignment). On normal completion payload is an empty array []; on failure payload is an error object containing code: "CONTEXT_COMPACTION_FAILED". The full internal summary text is not echoed back directly.


3. Bind project-level intervention lexicons and enable stopword pre-compliance interception (/v1/agent-runtime/project/lexicons)

After creating the synonym dictionary lex_enterprise_synonyms and the stopword/sensitive interception dictionary lex_support_stopwords in the project enterprise-ai-hub-210's Knowledge Base → Lexicons (/knowledge-base/lexicons) (for lexicon entry creation, see project-level lexicons and coordinated governance of retrieval/knowledge graph/agents), you can mount them onto the agent workbench.

1. The dual role of agent lexicon binding

2. Lexicon binding parameter description table

Field nameTypeRequiredDefault valueDescription and constraints
enabledbooleanNofalseWhether to enable lexicon rewriting and stopword interception for the current project's agent workbench.
stopInterceptbooleanNotrueWhen user input matches a stop-type entry in an enabled lexicon, whether to immediately short-circuit and block the current Run.
stopReplystringNo""The fixed compliance message returned directly to the user as the agent's answer when stopIntercept blocking is triggered (maximum 4,096 characters).
bindingsobject[]Yes[]An ordered array of lexicon bindings (up to 100 items), each containing lexiconId (lexicon ID) and priority (priority as a positive integer, with 1 being the highest, executed in ascending order).

3. Binding and verifying lexicon interception via API (PUT / GET /v1/agent-runtime/project/lexicons)

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 1. Bind two lexicons to the project agent workbench and enable stopIntercept compliance interception (no userId required)
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X PUT "${APPBASE_ENDPOINT}/agent-runtime/project/lexicons" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "stopIntercept": true,
    "stopReply": "抱歉,您的提问包含受限词汇或违反企业安全合规规范的指令,请围绕产品技术架构、排障手册与客户服务业务进行咨询。",
    "bindings": [
      {
        "lexiconId": "lex_enterprise_synonyms",
        "priority": 1
      },
      {
        "lexiconId": "lex_support_stopwords",
        "priority": 2
      }
    ]
  }'
)

Expected successful response (HTTP 200 OK):

{
  "enabled": true,
  "stopIntercept": true,
  "stopReply": "抱歉,您的提问包含受限词汇或违反企业安全合规规范的指令,请围绕产品技术架构、排障手册与客户服务业务进行咨询。",
  "bindings": [
    {
      "lexiconId": "lex_enterprise_synonyms",
      "priority": 1
    },
    {
      "lexiconId": "lex_support_stopwords",
      "priority": 2
    }
  ]
}
(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 2. Read the effective lexicon binding configuration of the current workbench at any time
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -fsS -i -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/lexicons" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @-
)

FAQ and Troubleshooting

Q1: Why does the task fail with CONTEXT_BUDGET_EXCEEDED or CONTEXT_FRESH_TAIL_TOO_LARGE when running?

Cause and troubleshooting steps: Both error codes indicate that a single model step's input exceeded the currently configured available context window budget, and even triggering automatic context compaction cannot fit it into the model window:

  1. CONTEXT_FRESH_TAIL_TOO_LARGE: This means the most recent single user input text, the system prompt, a large batch of bound tool Schema definitions, or a single freshly returned oversized tool result (the Fresh Tail portion) already exceeds context_window_tokens - reserved_output_tokens, so the compactor cannot free up enough space by compressing early history.

  2. Remediation:

    • Check whether context_window_tokens is set too small (for example, the model supports 65536 but only 8192 is configured), and increase it to 32768 or 65536;

    • Check whether reserved_output_tokens reserves too much, and adjust it to a reasonable 2048~4096;

    • Compact an overly long system_prompt or an oversized log file pasted in a single user message, or start a new conversation with Thread.

Q2: I modified system_prompt or switched the model in the Console — why isn't the currently running conversation answering with the new prompt?

Cause and troubleshooting steps: This is the Agent Runtime's runtime configuration snapshot isolation design. To ensure consistency of model capabilities, window budget, and tool sets throughout a single multi-step ReAct inference, the Runtime locks the current Config at the instant POST /runs accepts the task. After you see "All changes saved" in the configuration panel, simply send the next new message (triggering a new Run) to use the updated configuration.

Q3: Why was my normal business question directly intercepted by the lexicon and returned stopReply?

Cause and troubleshooting steps: This means that in the bound lexicon (such as lex_support_stopwords), a common colloquial word (such as “请问”, “帮我查下”) was entered as a stop-type entry, while the agent lexicon binding also has stopIntercept: true enabled.

Q4: When calling PATCH /v1/agent-runtime/project/config I passed only {"model_parameters": {"temperature": 0.5}} — why did the previously set top_p revert to the default value?

Cause and troubleshooting steps: PATCH /config performs partial-preserve updates on top-level fields (such as system_prompt, max_steps, model_parameters), but for the nested model_parameters object it uses wholesale replacement (Replace) rather than per-key merging (Deep Merge). Therefore, when updating sampling parameters, always pass the complete {"temperature": 0.5, "top_p": 0.9}.