API List

Using HTTP calls as an example, this article describes the request methods, API endpoints, request parameters, request examples, and response examples for the DolphinX API. For the field mappings between HTTP and WebSocket, see WebSocket Protocol.

Note:

Before running the curl examples, obtain BASE_URL and TOKEN:

BASE_URL='http://<host>:<port>' # Address of the server where DolphinX is deployed
TOKEN='<dolphindb-token>' # DolphinDB login token, obtained through the /api/login API

Response examples in this article include only the content of the data field. When calling an API, you receive the complete envelope and must retrieve the business data from the data field. For details, see General Conventions.

1. Agent and LLM Discovery

1.1 Get Accessible Agents

Gets the agents accessible to the current user.

Request Method and URL

GET /agent-bus/v1/agent/accessible

Request Parameters


Parameter	Type	Required	Description
status	int	No	The value of the agent status. 0 (default): REGISTERED 1: ACTIVE 2: SUSPENDED 3: DELETED Note: When `status=1` is set, or when this parameter is omitted, ACTIVE agents are returned. When it is set to 0, 2, or 3, an empty list is returned.
offset	int	No	Skips the first offset records. The value must be a non-negative integer. The default value is 0.
limit	int	No	The maximum number of records to return. The value must be a non-negative integer. If set to 0, an empty list is returned. The default value is 100.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/agent/accessible?offset=0&limit=100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_agent_accessible"

Response Example

Each element in the items array contains information about an agent. For field descriptions, see AgentInfo. size indicates the length of the items array, which is the number of accessible agents.

{
  "items": [
    {
      "agentId": "agent_builtin_xxx",
      "agentName": "DolphinDB Coding Agent",
      "description": "Built-in programming assistant for DolphinDB development, debugging, script generation, and data analysis.",
      "status": 1,
      "statusName": "ACTIVE",
      "systemPrompt": "You are the DolphinDB Coding Agent, responsible for assisting users with DolphinDB-related code development, debugging, script generation, data analysis, and troubleshooting.

Execute tasks directly whenever possible, and focus on delivering usable results rather than just providing suggestions. Responses should be concise, reliable, and easy to verify. When information is insufficient, ask only the necessary questions and do not fabricate table schemas, APIs, or execution results.",
      "llmConfigId": "llm_f5796495-21ce-8990-4e40-xxx",
      "contextConfig": {
        "includeSkillCatalog": true,
        "includeMemory": true
      },
      "memoryConfig": {
        "embeddingEnabled": false
      },
      "config": {
        "builtin": true,
        "builtinVersion": "2026.06.02",
        "agentKind": "coding"
      },
      "version": 3,
      "schemaVersion": 1,
      "extra": "",
      "createTime": "2026.06.29 14:20:30.596",
      "updateTime": "2026.06.29 14:22:09.107",
      "myPermission": "AGENT_ADMIN"
    }
  ],
  "offset": 0,
  "limit": 100,
  "size": 1
}

1.2 Get a Specified Agent

Gets a specified agent by agent ID.

Request Method and URL

GET /agent-bus/v1/agent/{agentId}

Request Parameters


Parameter	Type	Required	Description
agentId	string	Yes	The agent ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/agent/agent_xxx" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_agent_get"

Response Example

Returns information about the specified agent. For field descriptions, see AgentInfo.

{
  "agentId": "agent_builtin_xxx",
  "agentName": "DolphinDB Coding Agent",
  "description": "Built-in programming assistant for DolphinDB development, debugging, script generation, and data analysis.",
  "status": 1,
  "statusName": "ACTIVE",
  "systemPrompt": "You are the DolphinDB Coding Agent, responsible for assisting users with DolphinDB-related code development, debugging, script generation, data analysis, and troubleshooting.

Execute tasks directly whenever possible, and focus on delivering usable results rather than just providing suggestions. Responses should be concise, reliable, and easy to verify. When information is insufficient, ask only the necessary questions and do not fabricate table schemas, APIs, or execution results.",
  "llmConfigId": "llm_f5796495-21ce-8990-4e40-xxx",
  "contextConfig": {
    "includeSkillCatalog": true,
    "includeMemory": true
  },
  "memoryConfig": {
    "embeddingEnabled": false
  },
  "config": {
    "builtin": true,
    "builtinVersion": "2026.06.02",
    "agentKind": "coding"
  },
  "version": 3,
  "schemaVersion": 1,
  "extra": "",
  "createTime": "2026.06.29 14:20:30.596",
  "updateTime": "2026.06.29 14:22:09.107"
}

1.3 Get Available LLMs

Gets the LLMs available for the specified agent by agent ID.

Request Method and URL

GET /agent-bus/v1/agent/{agentId}/llm/selectable

Request Parameters


Parameter	Type	Required	Description
agentId	string	Yes	The agent ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/agent/agent_xxx/llm/selectable" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_agent_llm_selectable"

Response Example

Each element in the items array contains information about an LLM. For field descriptions, see SelectableLlmInfo. size indicates the length of the items array, which is the number of available LLMs.

{
  "defaultLlmConfigId": "llm_f5796495-21ce-8990-xxx",
  "items": [
    {
      "llmConfigId": "llm_f5796495-21ce-8990-xxx",
      "name": "gpt",
      "providerId": "provider_d69bdb29-70e7-f9ab-cc42-xxx",
      "provider": {
        "providerId": "provider_d69bdb29-70e7-f9ab-cc42-xxx",
        "name": "gpt",
        "adapterType": "openai-compatible",
        "baseUrl": "https://xxx",
        "apiKey": "***************************************************",
        "enabled": true,
        "schemaVersion": 1,
        "extra": "",
        "createTime": "2026.06.29 14:21:42.339",
        "updateTime": "2026.06.29 14:21:42.339"
      },
      "model": "gpt-5.5",
      "capability": "chat",
      "embeddingDimension": 0,
      "embeddingMetric": "",
      "embeddingNormalize": false,
      "requestPath": "/v1/chat/completions",
      "defaultParams": {},
      "contextWindow": null,
      "maxConcurrency": null,
      "rateLimitRPM": null,
      "timeoutMs": null,
      "retryConfig": {},
      "enabled": true,
      "schemaVersion": 1,
      "customData": "{"tool_call":true}",
      "extra": "",
      "createTime": "2026.06.29 14:22:01.843",
      "updateTime": "2026.06.29 14:22:01.843",
      "source": "agent",
      "isAgentDefault": true,
      "fallbackPriority": 0,
      "participatesInFallback": true
    }
  ],
  "size": 1
}

2. Session Management

2.1 Create a Session

Creates a session with the specified agent.

Request Method and URL

POST /agent-bus/v1/session/create

Request Parameters


Parameter	Type	Required	Description
agentId	string	Yes	The ID of an agent in the ACTIVE state.
title	string	No	The session title.
llmConfigId	string	No	The ID of an available LLM configuration for the current user under the specified agent.
metadata	object	No	User-defined metadata in JSON format. DolphinX does not process this data.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/session/create" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_create" \
  -d '{"agentId":"agent_xxx","title":"session for test"}'

Response Example

For response field descriptions, see SessionInfo.

{
    "sessionId": "8280cfd0-92c6-6bae-1844-xxx",
    "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-xxx",
    "userId": "admin",
    "llmConfigId": "",
    "title": "session for test",
    "metadata": {},
    "schemaVersion": 1,
    "extra": "",
    "createTime": "2026.06.30 10:54:22.665",
    "updateTime": "2026.06.30 10:54:22.665"
  }

2.2 Get a Session

Gets a specified session by session ID.

Request Method and URL

GET /agent-bus/v1/session/{sessionId}

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/session/8280cfd0-92c6-6bae-1844-xxx" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_get"

Response Example

For response field descriptions, see SessionInfo.

{
  "sessionId": "8280cfd0-92c6-6bae-1844-xxx",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-xxx",
  "userId": "admin",
  "llmConfigId": "",
  "title": "session for test",
  "metadata": {},
  "schemaVersion": 1,
  "extra": "",
  "createTime": "2026.06.30 10:54:22.665",
  "updateTime": "2026.06.30 10:54:22.665"
}

2.3 Update a Session

Updates information for a specified session. Only the session owner has permission to update the session.

Request Method and URL

PUT /agent-bus/v1/session/{sessionId}

Request Parameters


Parameter	Type	Required	Description
sessionId	string	This parameter is optional if the session ID is provided in the request URL.	The session ID. If the ID is specified in both the request URL and the request body, the values must match.
title	string	No	The session title.
llmConfigId	string	No	The ID of an available LLM configuration for the current user under the agent associated with the specified session. If this value is empty, the existing LLM configuration is cleared.
metadata	object	No	User-defined metadata in JSON format. This field can only be replaced as a whole.

Request Example

curl -X PUT "${BASE_URL}/agent-bus/v1/session/8280cfd0-92c6-6bae-1844-xxx" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_update" \
  -d '{"title":"updated session title","metadata":{"source":"curl-demo"}}'

Response Example

For response field descriptions, see SessionInfo.

{
  "sessionId": "8280cfd0-92c6-6bae-1844-xxx",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-xxx",
  "userId": "admin",
  "llmConfigId": "",
  "title": "updated session title",
  "metadata": {"source": "curl-demo"},
  "schemaVersion": 1,
  "extra": "",
  "createTime": "2026.06.30 10:54:22.665",
  "updateTime": "2026.06.30 10:54:22.665"
}

2.4 Delete a Session

Deletes a specified session.

Only the session owner has permission to delete the session.
After deletion, the corresponding session messages and workspace are permanently deleted.
For a nonexistent sessionId, the API returns deleted=true.
After deletion starts, no new messages can be sent in the session.
After a session is deleted, calls to the corresponding GET /session/{sessionId} and GET /session/{sessionId}/messages APIs return BUS_SESSION_NOT_FOUND.

Request Method and URL

DELETE /agent-bus/v1/session/{sessionId}

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID.

Request Example

curl -X DELETE "${BASE_URL}/agent-bus/v1/session/8280cfd0-92c6-6bae-1844-xxx" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_delete"

Response Example

{
  "sessionId": "8280cfd0-92c6-6bae-1844-xxx",
  "deleted": true
}

2.5 List Sessions

Lists sessions created by the current user. This API does not support querying sessions across users.

Request Method and URL

GET /agent-bus/v1/session/list

Request Parameters


Parameter	Type	Required	Description
agentId	string	Yes	The agent ID. You can also specify the ID in the request URL or through the x-agent-id request header.
offset	int	No	Skips the first offset records. The value must be a non-negative integer. The default value is 0.
limit	int	No	The maximum number of records to return. The value must be a non-negative integer. If set to 0, an empty list is returned. The default value is 100.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/session/list?agentId=agent_xxx&offset=0&limit=100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_list"

Response Example

Each element in the items array contains information about one session. For field descriptions, see SessionInfo. size indicates the length of the items array, which is the number of sessions.

{
  "items": [
    {"sessionId": "100d1675-0a36-70a0-cf48-xxx",
    "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-xxx",
    "userId": "admin",
    "llmConfigId": "",
    "title": "session for test",
    "metadata": {},
    "schemaVersion": 1,
    "extra": "",
    "createTime": "2026.06.30 10:44:55.744",
    "updateTime": "2026.06.30 10:44:55.744"
    }],
    "offset": 0,
    "limit": 100,
    "size": 1
}

3. Chat Completion

Advances the specified session by one turn. You can submit a new user message or the execution results of tool calls. DolphinX automatically handles permission validation, session writes, context assembly, model selection, LLM calls, response persistence, and token usage recording.

The API supports both streaming and non-streaming responses. Streaming is used by default. Automatic assembly and manual assembly use the same request URL. Switch between them based on whether the request body contains the assemblyConfig parameter:

If assemblyConfig is omitted, automatic assembly is used. This is suitable for standard conversations.
If assemblyConfig is included, manual assembly is used. This is suitable when the caller needs to control context blocks, tool definitions, or temporary instructions.

Request Method and URL

POST /agent-bus/v1/chat/completions

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID. It must belong to the currently logged-in user.
message	string	Conditionally required	User message text, which is automatically appended to the session history. You must provide exactly one of message and toolResults.
toolResults	ToolResult[]	Conditionally required	The list of tool execution results. These must correspond to the toolCalls returned by the LLM in the previous turn. You must provide exactly one of message and toolResults.
stream	bool	No	Whether to return a streaming response. The default value is true.
contextEvent	bool	No	Whether to include context-processing events in the streaming response. The default value is false. Only applies to HTTP SSE and WebSocket requests with `stream=true`. Note: When enabled, processes such as automatic summarization and context compression are returned as EVENT events, allowing the frontend to display states such as “Compressing context.” These events are not part of the LLM response content.
includeReasoning	bool	No	Whether to return the reasoning process. The default value is false.
tools	ToolDefinition[]	No	The list of application-layer tool definitions in OpenAI function calling format.
activeSkillNames	string[]	No	The list of skill names to actively load for this request. Used only to explicitly inject detailed instructions for these skills. It does not indicate skills autonomously selected by the model, nor does it maintain a progressive loading state. The caller decides whether to continue loading them in subsequent requests.
llmConfigId	string	No	LLM configuration ID to use for this request. Temporarily overrides the default configuration of the session or agent.
model	string	No	Temporarily overrides the model name for this request. In general, select the model through llmConfigId. Use this parameter only when you need to temporarily specify a compatible model name under the same LLM configuration. This parameter does not change llmConfigId, permission validation, the context window, or the fallback LLM configuration switching policy.
temperature	double	No	Temporarily overrides the sampling temperature for this request. The value must be in the range [0, 2]. Lower values produce more stable output, while higher values produce more varied output.
maxTokens/max_tokens/max_completion_tokens	int	No	Temporarily overrides the output token limit for this request. This also affects the output budget reserved during context assembly. The three parameters are equivalent. We recommend passing only one.
topP/top_p	double	No	Temporarily overrides the nucleus sampling parameter. The value must be in the range (0, 1]. Smaller values produce more focused output. The two parameters are equivalent. We recommend passing only one of them.
stop	string/string[]	No	Temporarily sets the stop sequences for this request. Generation stops when the output matches any sequence.
extensions	object	No	Parameters passed directly through to the model service provider.
assemblyConfig	object	No	Manual assembly configuration, where the application layer controls how the context is constructed. Set this parameter only when manual assembly is required. For the internal structure of assemblyConfig, see the table below.

assemblyConfig structure:


Parameter	Type	Required	Description
systemPrompt	string	No	User-defined system prompt that overrides the agent's default system prompt.
contextBlocks	ContextBlock[]	No	The list of user-defined context blocks, inserted into the assembly pipeline according to position. For details, see the ContextBlock structure and manual assembly flow below.
tools	ToolDefinition[]	No	The list of application-layer tool definitions in OpenAI function calling format.
activeSkillNames	string[]	No	The list of skill names to actively load for this request. Used only to explicitly inject detailed instructions for these skills. It does not indicate skills autonomously selected by the model, nor does it maintain a progressive loading state. The caller decides whether to continue loading them in subsequent requests.
excludeSkillNames	string[]	No	The list of skill names to exclude.
noSkillCatalog	bool	No	Whether to skip automatic skill catalog injection. The default value is false.

ToolResult structure:


Parameter	Type	Required	Description
toolCallId/tool_call_id	string	Yes	The tool call ID. Must match `toolCalls[].id` returned by the LLM in the previous turn.
content	string	No	Text content of the tool execution result.

ContextBlock structure:


Parameter	Type	Required	Description
name	string	Yes	The block identifier, used only for validation and debugging. It is not injected into the prompt.
content	string	Yes	Text content to inject.
position	string	No	The text insertion position. Valid values are after_system, before_history (default), and before_current_turn.

Automatic Assembly

DolphinX performs the following steps in the background. The caller only needs to submit the current message or toolResults.

Validates the session permissions and resolves the LLM configuration to use for this request.
Loads the agent configuration, system prompt, skill catalog, detailed instructions for explicitly loaded skills, and related memories.
Runs automatic summarization when needed.
After the context window check passes, it writes the current turn input to the session and calls the LLM.
Writes the model output and token usage to the session, then returns the response for this request.

Manual Assembly

Blocks with after_system are appended to the end of the preceding system prompt. If this assembly does not include a system prompt, after_system is converted to the first role=system message.
before_history is wrapped as an application reference context and inserted after the latest summary and before the raw history.
before_current_turn is wrapped as application runtime context and folded into the current turn message.
Use after_system for global rules, before_history for reference material for the current turn, and before_current_turn for runtime state or dynamic snapshots that should stay close to the current turn.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/chat/completions" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_chat_completions" \
  -d '{"sessionId":"sess_001","message":"hello, please introduce DolphinX.","stream":false}'

Response Example

Automatic assembly and manual assembly use the same response data structure. When stream=false, this structure is returned as the data field in the HTTP JSON envelope. When stream=true, the complete result is returned in STREAM_END.data.

reasoning indicates the displayable reasoning process returned by the LLM provider. It is intended for display only and is not guaranteed to be complete or equivalent to the model’s internal reasoning. DolphinX extracts and returns it only when includeReasoning=true; it does not need to be persisted.

{
  "requestId": "req_xxx",
  "sessionId": "sess_001",
  "model": "gpt-4",
  "llmConfigId": "llm_actual",
  "content": "This is a reply from LLM...",
  "reasoning": "The reasoning process returned by the LLM provider for display. Empty if reasoning is disabled or not provided.",
  "toolCalls": [
    {
      "id": "call_xxx",
      "type": "function",
      "function": {
        "name": "search_database",
        "arguments": "{"query":"SELECT ..."}"
      }
    }
  ],
  "finishReason": "stop",
  "usage": {
    "promptTokens": 1200,
    "completionTokens": 300,
    "totalTokens": 1500
  },
  "latencyMs": 2500,
  "metadata": {
    "llmConfigId": "llm_actual",
    "requestedLlmConfigId": "llm_requested",
    "fallbackApplied": false
  }
}

In streaming responses, STREAM_CHUNK.data.content contains incremental body content, and toolCallDeltas contains incremental tool calls. These deltas may be incomplete and are intended only for real-time display. Use STREAM_END.data.toolCalls as the source of truth for executing tools, persisting data, or making business decisions.
STREAM_REASONING.data.reasoning appears only when includeReasoning=true and the LLM provider returns a displayable reasoning process.
metadata records the LLM configuration actually used for this request. fallbackApplied=true indicates that DolphinX switched to a fallback LLM configuration after the preferred LLM configuration failed. In this case, the response also returns fallbackFromLlmConfigId (the original configuration ID), fallbackReason (the failure reason), and fallbackStatusCode (the failure status code).
The context.compaction event is returned only when contextEvent=true and the current request actually triggers context compaction. It may appear before STREAM_START. Standard HTTP JSON responses ignore contextEvent.

4. Skill Management

4.1 Get an Agent’s Skill Catalog

Retrieves summaries of skills under the specified agent that are visible to the current user and discoverable by the LLM. When you call /chat/completions, DolphinX injects the skill catalog into the context by default, so callers typically do not need to call this API manually. This API is primarily used for previewing, debugging, or user-defined context assembly. In manual assembly mode, you can set assemblyConfig.noSkillCatalog=true to disable automatic injection.

Request Method and URL

GET /agent-bus/v1/skill/{agentId}/catalog

Request Parameters


Parameter	Type	Required	Description
agentId	string	Yes	The agent ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/skill/agent_xxx/catalog" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_catalog"

Response Example

For response field descriptions, see SkillInfo.

{
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-xxx",
  "userId": "admin",
  "catalog": 
    [
      {
        "skillId": "sk_6d9fbb7a-9597-7a97-ed4b-a5cccea178a1",
        "name": "ddb-ml",
        "description": "A built-in skill for DolphinDB Web's machine learning data workflow. Supports metadata discovery, data preview, filtering, aggregation, joins, field role inference, data cleaning, feature engineering, and classification, regression, and clustering tasks. Does not cover investigative reports, time-series reports, or database administration.",
        "argumentHint": ""
      },
        ...
    ],"size": 4
}

4.2 Get the Main Instruction in a Skill

Gets the main instruction content for the specified skill.

Request Method and URL

GET /agent-bus/v1/skill/{skillId}/instruction

Request Parameters


Parameter	Type	Required	Description
skillId	string	Yes	The skill ID.
agentId	string	Yes	The agent ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/skill/skill_xxx/instruction?agentId=agent_xxx" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_instruction"

Response Example

{
  "skillId": "skill_xxx",
  "name": "search-database",
  "description": "Search distributed tables",
  "instruction": "Full skill instruction in Markdown format..."
}

4.3 List Skill Package Files

Lists files in the skill package. The response includes only file metadata and does not return file content.

Request Method and URL

GET /agent-bus/v1/skill/{skillId}/files/list

Request Parameters


Parameter	Type	Required	Description
skillId	string	Yes	The skill ID.
agentId	string	Yes	The agent ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/skill/skill_xxx/files/list?agentId=agent_xxx" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_files_list"

Response Example

{
  "skillId": "skill_xxx",
  "items": [
    {
      "skillId": "skill_xxx",
      "filePath": "references/model-selection-guide.md",
      "size": 2048,
      "isText": true,
      "lineCount": 80
    }
  ],
  "size": 1
}

Response Field Description

filePath: The path of the skill package file relative to the root directory.
isText: Indicates whether the server treats the file as a text file. When a non-text file is read, the complete raw content is returned as Base64-encoded data.

4.4 Get a Single Skill Package File

Gets the content of a specified file in the skill package.

Request Method and URL

GET /agent-bus/v1/skill/{skillId}/files/get

Request Parameters


Parameter	Type	Required	Description
skillId	string	Yes	The skill ID.
agentId	string	Yes	The agent ID.
filePath	string	Yes	The path of the skill package file relative to the root directory.
lineStart	int	No	The 1-based starting line for text files. The default value is 0, which means the full file is read.
lineLimit	int	No	The number of lines to read. The default value is 120, and the maximum value is 300.
raw	bool	No	Compatibility parameter. The content in the response is always the original Base64-encoded file content.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/skill/skill_xxx/files/get?agentId=agent_xxx&filePath=references/model-selection-guide.md&lineStart=1&lineLimit=120" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_files_get"

Response Example

{
  "skillId": "skill_xxx",
  "filePath": "references/model-selection-guide.md",
  "isText": true,
  "lineCount": 42,
  "raw": false,
  "lineStart": 1,
  "lineEnd": 42,
  "encoding": "base64",
  "content": "<base64 content>",
  "size": 1024
}

For text files, when lineStart and lineLimit are specified, only the corresponding line range is returned.
Non-text files do not support line-based reads and always return the complete original content.
For large files, use segmented reads to control the response size.

4.5 Search Skill Package Text Files

Search for content by string in skill package text files. This API is designed for tools to read content on demand without loading entire files into the context.

Request Method and URL

POST /agent-bus/v1/skill/{skillId}/files/search

Request Parameters


Parameter	Type	Required	Description
skillId	string	Yes	The skill ID.
agentId	string	Yes	The agent ID.
query	string	Conditionally required	Search for a single string, 1 to 1,024 bytes. Exactly one of query, all, and any must be provided.
all	string[]	Conditionally required	Matches only when all specified strings are found. Up to 5 strings, each 1 to 1,024 bytes.
any	string[]	Conditionally required	Matches when any one of the specified strings is found. Up to 5 strings, each 1 to 1,024 bytes.
scope	string	No	Match scope. Valid values: "file" (entire file) and "line" (single line). The default value is "file".
caseSensitive	bool	No	Whether matching is case-sensitive. The default value is false.
filePaths	string[]	No	The list of relative paths in the skill package that limit the search scope.
extensions	string[]	No	Limits the search to files with the specified extensions, such as [".md",".json"].
contextLines	int	No	Number of context lines before and after each matching line. The default value is 3, and the maximum value is 10.
maxResults	int	No	Safety threshold for the total number of hits. The default value is 1000, and the maximum value is 5000.
maxPerFile	int	No	Safety threshold for the number of hits in a single file. The default value is 200, and the maximum value is 1000.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/skill/skill_xxx/files/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_files_search" \
  -d '{"agentId":"agent_xxx","query":"DolphinDB","scope":"line","contextLines":2,"maxResults":20}'

Response Example

{
  "skillId": "skill_xxx",
  "terms": ["RSI"],
  "mode": "query",
  "scope": "file",
  "resultCount": 1,
  "skippedCount": 0,
  "matches": [
    {
      "skillId": "skill_xxx",
      "filePath": "refs/indicators/rsi.json",
      "size": 668,
      "isText": true,
      "lineCount": 24,
      "line": 3,
      "column": 12,
      "term": "RSI",
      "text": ""name": "RSI"",
      "before": ["{"],
      "after": [" "period": 14"]
    }
  ],
  "skipped": []
}

Searches for content by string in skill package text files. It is designed for tools to read content on demand without loading entire files into the context.
Only text files are searched. Non-text files and text files that exceed the searchable size limit appear in the skipped field, with the reason field set to non_text or too_large.
Search terms are matched as literal substrings. Tokenization, regex, and scoring are not supported. Case sensitivity is controlled by caseSensitive.
scope=file evaluates matches against the entire file. For example, all=["foo","bar"] only requires both strings to appear in the same file. The response still returns the lines that actually matched. scope=line evaluates matches against a single line. For example, all=["foo","bar"] requires both strings to appear on the same line.
Results are returned in a stable order based on skill package file order and line number. They are not sorted by relevance.
If the number of hits exceeds maxResults or maxPerFile, an error is returned, and no partial results are returned. Callers should use a more specific pattern for the search.

4.6 Batch Retrieve Skill Package Files

Gets the content of specified files in a skill package in batches.

Request Method and URL

POST /agent-bus/v1/skill/{skillId}/files/batchGet

Request Parameters


Parameter	Type	Required	Description
skillId	string	Yes	The skill ID.
agentId	string	Yes	The agent ID.
filePaths	string/string[]	Yes	File paths relative to the skill package root directory. A single string is treated as one file; an empty array returns an empty list.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/skill/skill_xxx/files/batchGet" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_skill_files_batch_get" \
  -d '{"agentId":"agent_xxx","filePaths":["SKILL.md","reference.md"]}'

Response Example

{
  "skillId": "skill_xxx",
  "items": [
    {
      "skillId": "skill_xxx",
      "filePath": "SKILL.md",
      "encoding": "base64",
      "content": "<base64 content>",
      "size": 2048
    }
  ],
  "size": 1
}

5. Workspace Management

A workspace is a session-level, temporary text-file area for agents. It stores intermediate code, scripts, and partial modification results, so the model does not need to output complete file contents during a conversation repeatedly.

General Constraints

A workspace is identified by sessionId, and the current user must be the creator of that session.
Files are stored flat within a single session's workspace; subdirectories are not supported. name must be a regular file name. It cannot contain /, \, or .., and it cannot start with periods (.).
read/search/write/replace apply only to UTF-8 text files.
By default, a single workspace is limited to 100 files, 5 MiB in total size, and 512 KiB per file. The total size limit is controlled by the deployment parameter maxAgentWorkspaceBytes. Reads and searches are subject to server-side limits.

Workspace File Hash

A hash value in the workspace is a field returned by DolphinX when a workspace file is read. The agent must include this hash value when modifying the file to ensure that the target file is the same as the one previously read, which prevents stale reads.

Format:

xxh64:<16-bit hex>:<size>

When calling workspace.replace to modify a file, the request body must include the hash obtained from the most recent workspace.read, workspace.search, workspace.write, or workspace.replace call for the same file.
Before executing workspace.replace, the server rereads the current file and computes its hash. If the hash in the request does not match the current file hash, the request is rejected with REPLACE_REJECTED and error.reason="stale_file". The client should read or search again before generating a replacement request.

APIs that provide and use hashes:


API	Returns Hash	Description
workspace.read	Yes, in the hash response field	Indicates the full-content digest of the file that was read and can be used directly as a subsequent `workspace.replace.hash`.
workspace.search	Yes, in each `matches[].hash`	Indicates the full-content digest of the corresponding `matches[].name` file and can be used as `workspace.replace.hash` when modifying that file.
workspace.write	Yes, in the hash response field	Indicates the full-file digest after the write and can be used as a subsequent `workspace.replace.hash`.
workspace.replace	The request must include a hash; a successful response returns a new hash.	The hash in the request is used for stale-read detection. Use the new hash in the response for subsequent modifications to the same file.

5.1 List Workspace Files

Lists regular files in the root directory of the current session's workspace.

Request Method and URL

GET /agent-bus/v1/workspace/{sessionId}/files

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/workspace/sess_001/files" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_list"

Response Example

{
  "items": [
    {
      "name": "main.dos",
      "type": "file",
      "size": 2048,
      "updateTime": "2026-05-21T10:00:00.000"
    }
  ],
  "size": 1
}

5.2 Read a Workspace File

Reads the content of the specified workspace file.

Request Method and URL

GET /agent-bus/v1/workspace/{sessionId}/file

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID.
name	string	Yes	File name. Paths are not supported.
startLine	int	No	Start line, 1-based. Defaults to line 1.
endLine	int	No	End line, inclusive. Defaults to the end of the file.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/workspace/sess_001/file?name=main.dos&startLine=1&endLine=120" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_read"

Response Example

{
  "name": "main.dos",
  "content": "def main(){
 return 1
}
",
  "size": 1024,
  "lineCount": 42,
  "startLine": 1,
  "endLine": 3,
  "hash": "xxh64:4f9a2c18b7e301d2:1024"
}

size is the complete file size in bytes, and lineCount is the total number of lines in the file.
See the hash description at the beginning of this section.
When constructing workspace.replace.replacements[].old, copy the original fragment exactly from the content returned by this API. For multi-line replacements or changes that are sensitive to line breaks, use workspace.read first to retrieve sufficient context.

5.3 Write Workspace Files

Creates a file or overwrites an entire file. For small changes, use workspace.replace.

Request Method and URL

POST /agent-bus/v1/workspace/{sessionId}/file

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID.
name	string	Yes	File name. Paths are not supported.
content	string	Yes	UTF-8 text content.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/workspace/sess_001/file" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_write" \
  -d '{"name":"main.dos","content":"def main(){
  return 1
}
"}'

Response Example

{
  "name": "main.dos",
  "created": true,
  "changed": true,
  "size": 31,
  "hash": "xxh64:4f9a2c18b7e301d2:31"
}

5.4 Delete Workspace Files

Deletes a specified file from the current session’s workspace. Directory deletion, recursive deletion, batch deletion, wildcard deletion, and clearing the workspace are not supported.

Request Method and URL

DELETE /agent-bus/v1/workspace/{sessionId}/file

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID.
name	string	Yes	File name. Paths are not supported.

Request Example

curl -X DELETE "${BASE_URL}/agent-bus/v1/workspace/sess_001/file" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_delete" \
  -d '{"name":"main.dos"}'

Response Example

{
  "name": "main.dos",
  "deleted": true,
  "size": 2048
}

5.5 Search Workspace Files

Searches for content by string in workspace text files. This API is suitable for on-demand reads by tools.

Request Method and URL

POST /agent-bus/v1/workspace/{sessionId}/search

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID.
query	string	Conditionally required	Search for a single string, 1 to 1,024 bytes. Exactly one of query, all, and any must be provided.
all	string[]	Conditionally required	Matches only when all specified strings are found. Up to 5 strings, each 1 to 1,024 bytes.
any	string[]	Conditionally required	Matches when any one of the specified strings is found. Up to 5 strings, each 1 to 1,024 bytes.
scope	string	No	Match scope. Valid values: "file" (entire file) and "line" (single line). The default value is "file".
caseSensitive	bool	No	Whether matching is case-sensitive. The default value is false.
names	string[]	No	The list of file names to restrict the search to.
extensions	string[]	No	Limits the search to files with the specified extensions, such as [".dos",".md"].
contextLines	int	No	Number of context lines before and after each matching line. The default value is 0, and the maximum is 10.
maxResults	int	No	Safety threshold for the total number of hits. The default value is 1000, and the maximum value is 5000.
maxPerFile	int	No	Safety threshold for the number of hits in a single file. The default value is 200, and the maximum value is 1000.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/workspace/sess_001/search" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_search" \
  -d '{"query":"submitOrder","scope":"line","contextLines":1,"maxResults":20}'

Response Example

{
  "terms": ["submitOrder", "RSI"],
  "mode": "all",
  "scope": "file",
  "resultCount": 1,
  "skippedCount": 0,
  "matches": [
    {
      "name": "main.dos",
      "hash": "xxh64:4f9a2c18b7e301d2:1024",
      "line": 37,
      "column": 12,
      "term": "submitOrder",
      "text": "submitOrder(account, symbol, qty)",
      "before": ["if(rsi < 30){"],
      "after": ["}"]
    }
  ],
  "skipped": []
}

Searches for content by string in workspace text files, so tools can read it on demand.
Searches only UTF-8 text files. Files that exceed the per-file size limit or are not UTF-8 appear in the skipped field, with the reason field set to too_large or invalid_utf8.
Search terms are matched as literal substrings. Tokenization, regex, and scoring are not supported. Case sensitivity is controlled by caseSensitive.
scope=file evaluates matches against the entire file. For example, all=["foo","bar"] only requires both strings to appear in the same file. The response still returns the lines that actually matched.
scope=line evaluates matches against a single line. For example, all=["foo","bar"] requires both strings to appear on the same line.
If the number of hits exceeds maxResults or maxPerFile, an error is returned, and no partial results are returned. Callers should use a more specific pattern for the search.
See the hash description at the beginning of this section.
workspace.search is designed to locate files and line numbers. The text, before, and after fields returned by the search provide line-based context. When you need to construct a multiline or newline-sensitive old fragment, call workspace.read again to read the content around the target lines.

5.6 Partially Modify Workspace Files

Performs a partial replacement in a workspace file by using an exact old fragment. The request must include the file hash for stale-read detection.

Request Method and URL

POST /agent-bus/v1/workspace/{sessionId}/replace

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID.
name	string	Yes	Name of the existing file to modify. Paths are not supported.
hash	string	Yes	File hash, in a format such as `xxh64:<16-digit hex>:<size>`.
replacements	object[]	Yes	Ordered replacement list. Cannot be empty.
replacements[].old	string	Yes	Exact old fragment. Cannot be empty.
replacements[].new	string	Yes	New fragment. It can be an empty string; an empty string deletes the old fragment.
replacements[].replaceAll	bool	No	Whether to replace all matches. The default value is false.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/workspace/sess_001/replace" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_workspace_replace" \
  -d '{"name":"main.dos","hash":"xxh64:<hash>:<size>","replacements":[{"old":"return 1","new":"return 2"}]}'

Response Example

{
  "name": "main.dos",
  "changed": true,
  "lineCount": 3,
  "replacementCount": 2,
  "occurrenceCount": 5,
  "hash": "xxh64:7c1d0b2a9910ef43:1048"
}

Multiple replacement entries are applied in array order. If multiple replacement entries are provided, the second entry runs against the content produced after the first replacement. Therefore, if the first entry creates new text, the second entry may also match that new text.
When replaceAll=false, old must occur exactly once. The request is rejected if it occurs zero times or multiple times.
When replaceAll=true, old must occur at least once, and the server replaces all non-overlapping matches.
If any replacement entry fails, the entire request fails, and the original file remains unchanged.

6. Initiate External Network Requests

Accesses external HTTP(S) resources through DolphinX. DolphinX handles security validation, rate limiting, request initiation, and returning summaries of raw HTTP responses; application-layer logic such as page parsing, search ranking, and redirect handling is handled by the application.

Request Method and URL

POST /agent-bus/v1/network/fetch

Request Parameters


Parameter	Type	Required	Description
agentId	string	Conditionally required	The agent ID.
method	string	Yes	Only "GET" and "POST" are supported. Matching is case-insensitive.
url	string	Yes	A complete http:// or https:// URL. Currently, access is allowed only to dolphindb.cn, dolphindb.com, and their subdomains, matched on domain boundaries. Only default ports are allowed: HTTP 80 and HTTPS 443. 3xx redirects are not followed. The URL must not contain spaces, control characters, fragments, userinfo, or an IP literal host.
headers	object	No	Request headers to pass through to the target site. Values must be scalar strings. Request headers are filtered for security. Host, Content-Length, Transfer-Encoding, Connection, authentication/Cookie/proxy-related headers, Accept-Encoding, and hop-by-hop headers are not allowed. DolphinX always uses Accept-Encoding: identity.
body	string	No	POST request body. GET requests cannot include a body.A body is returned only for text-based, uncompressed responses. For binary responses, unknown types, or responses with non-identity encoding, `bodyOmitted=true` is set.Text bodies are returned in UTF-8. If sanitization is required, `bodyUtf8Sanitized=true` is set.
timeoutMs	int	No	Request timeout in milliseconds. The default value is 10000, and the maximum value is 30000.
maxBodyBytes	long	No	Maximum number of response body bytes to read. The default value is 2097152, and the maximum value is 33554432.When the body is truncated, `truncated=true` is set. Binary resources such as PDFs return only the status code, response headers, and content type; they do not return a body.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/network/fetch" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_network_fetch" \
  -d '{"agentId":"agent_xxx","method":"GET","url":"https://docs.dolphindb.cn/zh/","timeoutMs":10000,"maxBodyBytes":1048576}'

Response Example

For response field descriptions, see NetworkFetchResponse.

{
  "url": "https://docs.dolphindb.cn/zh/tutorials/in_memory_table.html",
  "method": "GET",
  "statusCode": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "text/html; charset=utf-8"
  },
  "contentType": "text/html; charset=utf-8",
  "contentEncoding": "",
  "body": "<!doctype html>...",
  "truncated": false,
  "bodyOmitted": false,
  "bodyUtf8Sanitized": false,
  "latencyMs": 321
}

7. Call MCP Tools

Executes the MCP tool call returned by /chat/completions.

Request Method and URL

POST /agent-bus/v1/mcp/tools/call

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID. It must belong to the currently logged-in user. DolphinX resolves the agent from the session.
toolName/name	string	Yes	The name of the MCP composite tool to execute. This usually comes from `toolCalls[].function.name` in the previous turn.
arguments	object	No	The tool parameters, which are a JSON object. If omitted, an empty object is used.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/mcp/tools/call" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_mcp_tools_call" \
  -d '{"sessionId":"sess_001","toolName":"mcp_server_tool_name","arguments":{"query":"DolphinDB"}}'

Response Example

For response field descriptions, see McpToolCallResult.

{
  "ok": true,
  "isError": false,
  "truncated": false,
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ]
}

This API is responsible only for executing tools on bound MCP servers. It cannot be used to configure MCP servers or bindings. Configuration capabilities are maintained by the DolphinX management system and are not exposed as external APIs.
toolName is a composite tool name generated by DolphinX to prevent tool name conflicts across different MCP servers. Applications typically use the toolCalls[].function.name returned by the LLM directly and do not need to parse this name.
When an MCP server returns a tool-level error, the API may still return a business result with ok=false or isError=true. The caller should return the response content to the model as the tool result so the model can continue processing.

8. Session Summary Generation

DolphinX automatically compresses context when the chat.completions context becomes too long. This API is intended only for scenarios that require manual compression.

Request Method and URL

POST /agent-bus/v1/session/{sessionId}/summary

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID.
instructions	string	No	Additional summary instructions to append to the summary prompt.
llmConfigId	string	No	The ID of the LLM configuration to prefer for this summary.
force	bool	No	Whether to force generation. The default value is false. When set to true, all raw history after the latest summary is included in this summary.
metadata	object	No	User-defined metadata in JSON format. DolphinX only passes it through.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/session/sess_001/summary" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_summary" \
  -d '{"force":false,"instructions":"Retain the database paths, table names, and key conclusions throughout the current conversation."}'

Response Example

For response field descriptions, see SummaryResult.

{
  "sessionId": "sess_001",
  "generated": true,
  "reason": "",
  "trigger": "manual",
  "summaryUpToSeqNum": 50,
  "messageId": "msg_xxx",
  "sequenceNum": 51,
  "role": "system",
  "contentType": "summary",
  "content": "summary content...",
  "metadata": {
    "summaryUpToSeqNum": 50,
    "trigger": "manual"
  }
}

9. Context Preview

Previews the assembled context without calling the LLM. Use this to inspect token budget allocation and verify that skills and memory are injected correctly.

Request Method and URL

POST /agent-bus/v1/context/preview

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID. The session must be within the readable scope of the currently logged-in user.
message	string	Conditionally required	User message text. You must provide exactly one of message and toolResults.
toolResults	ToolResult[]	Conditionally required	The list of tool execution results. These must correspond to the toolCalls returned by the LLM in the previous turn.
tools	ToolDefinition[]	No	The list of tool definitions. If assemblyConfig is present, put this in `assemblyConfig.tools` instead.
activeSkillNames	string[]	No	The names of the skills proactively loaded for this request. If assemblyConfig is present, put this in `assemblyConfig.activeSkillNames` instead.
llmConfigId	string	No	The ID of the LLM configuration used to resolve the context window and token budget.
assemblyConfig	object	No	Manual assembly configuration. The structure is the same as the manual assembly mode in Chat Completions.
maxTokens/max_tokens/max_completion_tokens	int	No	Reserved budget for output tokens. The three fields are equivalent; provide only one of them.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/context/preview" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_context_preview" \
  -d '{"sessionId":"sess_001","message":"Preview the context that will be assembled for this request.","maxTokens":1024}'

Response Example

{
  "agentId": "agent_001",
  "sessionId": "sess_001",
  "assemblyMode": "auto",
  "messages": [
    {
      "role": "system",
      "content": "..."
    },
    {
      "role": "user",
      "content": "current question"
    }
  ],
  "tools": [],
  "estimatedTokens": 4200,
  "detail": {
    "assemblyMode": "auto",
    "historyMode": "summary-first",
    "memoriesIncluded": 2,
    "messagesIncluded": 8,
    "skillsInCatalog": 3,
    "activeInstructions": 1,
    "toolsIncluded": 2,
    "summaryIncluded": true,
    "summaryUpToSeqNum": 40,
    "historyFromSeq": 41,
    "historyToSeq": 48
  },
  "tokenBreakdown": {
    "systemPrompt": 200,
    "skillCatalog": 300,
    "skillInstructions": 600,
    "memoryContext": 300,
    "summaryMessage": 120,
    "historyMessages": 2200,
    "externalContext": 0,
    "userMessage": 50,
    "toolDefinitions": 430
  }
}

detail Field Description


Field	Type	Description
assemblyMode	string	"auto" or "manual".
memoriesIncluded	int	The number of memories actually injected into the context.
messagesIncluded	int	The number of historical messages actually included.
skillsInCatalog	int	The number of skills included in the skill catalog.
activeInstructions	int	The number of detailed skill instructions loaded.
toolsIncluded	int	The number of tool definitions.
historyMode	string	The history assembly mode. Fixed to "summary-first".
summaryIncluded	bool	Whether the latest summary was injected for this request.
summaryUpToSeqNum	long	The sequence-number boundary covered by the latest summary used for this request. This is 0 when no summary is used.
historyFromSeq	long	The starting sequence number of the raw tail.
historyToSeq	long	The ending sequence number of the raw tail.

tokenBreakdown Field Description


Field	Type	Description
systemPrompt	int	The estimated token count for the system prompt.
skillCatalog	int	The estimated token count for the skill catalog.
skillInstructions	int	The estimated token count for detailed skill instructions.
memoryContext	int	The estimated token count for memory content.
summaryMessage	int	The estimated token count for the latest summary.
historyMessages	int	The estimated token count for message history.
externalContext	int	The estimated token count for external context, such as contextBlocks.
userMessage	int	The estimated token count for the current user message. This is 0 if only toolResults is provided in this turn.
toolDefinitions	int	The estimated token count for tool definitions.

10. Low-Level APIs

10.1 LLM Complete (Call the LLM Directly)

Bypasses context assembly and sends messages directly to the LLM. Use this when your application interacts with the LLM directly.

Request Method and URL

POST /agent-bus/v1/llm/complete

Request Parameters


Parameter	Type	Required	Description
agentId	string	Conditionally required	The agent ID.
sessionId	string	No	The session ID.
messages	LLMMessage[]	Yes	The complete message list constructed by the application layer and sent directly to the LLM.
tools	ToolDefinition[]	No	The list of tool definitions in the OpenAI function calling format.
model	string	No	Temporarily sets the model name for this request.
stream	bool	No	Whether to return a streaming response. The default value is true.
includeReasoning	bool	No	Whether to return the reasoning process. The default value is false.
llmConfigId	string	No	The LLM configuration ID.
requestId	string	No	The request trace ID. If omitted, it is generated automatically.
temperature	double	No	Temporarily overrides the sampling temperature for this request. Valid range: [0,2]. Lower values produce more stable output, while higher values produce more varied output.
maxTokens/max_tokens/max_completion_tokens	int	No	Temporarily overrides the output token limit for this request. The three fields are equivalent. We recommend passing only one.
topP/top_p	double	No	Temporarily overrides the nucleus sampling parameter. Valid range: (0,1]. Smaller values produce more focused output. The two parameters are equivalent. We recommend passing only one of them.
stop	string/string[]	No	Temporarily sets the stop sequences for this request. Generation stops when the generated content encounters any stop sequence. You can pass a string or an array of strings.
persistMessage	bool	No	Valid only when sessionId is specified. When set to true, appends the model response to that session.
extensions	object	No	Parameters passed directly through to the model service provider.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/llm/complete" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_llm_complete" \
  -d '{"agentId":"agent_xxx","messages":[{"role":"user","content":"hello, introduce DolphinX in one sentence"}],"stream":false}'

Response Example

The response structure is the same as the Chat Completions response.

{
  "requestId": "req_xxx",
  "sessionId": "sess_001",
  "model": "gpt-4",
  "llmConfigId": "llm_actual",
  "content": "This is a reply from LLM...",
  "reasoning": "",
  "toolCalls": [],
  "finishReason": "stop",
  "usage": {
    "promptTokens": 1200,
    "completionTokens": 300,
    "totalTokens": 1500
  },
  "latencyMs": 2500,
  "metadata": {
    "llmConfigId": "llm_actual",
    "requestedLlmConfigId": "llm_requested",
    "fallbackApplied": false
  }
}

10.2 Get Message List

Gets the message list for the specified session.

Request Method and URL

GET /agent-bus/v1/session/{sessionId}/messages

Request Parameters


Parameter	Type	Required	Description
sessionId	string	Yes	The session ID.
startSeq	long	No	The starting sequence number. The default value is 1.
endSeq	long	No	The ending sequence number. The default value is MAX.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/session/sess_001/messages?startSeq=1&endSeq=100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_messages"

Response Example

For response field descriptions, see MessageInfo.

{
  "sessionId": "sess_001",
  "items": [
    {
      "messageId": "msg_xxx",
      "sessionId": "sess_001",
      "agentId": "agent_xxx",
      "sequenceNum": 1,
      "role": "user",
      "contentType": "text",
      "content": "hello",
      "metadata": {},
      "createTime": "2026.06.30 10:54:22.665"
    }
  ],
  "size": 1
}