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	Location	Type	Required	Description
status	query	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	query	int	No	Skips the first offset records. The value must be a non-negative integer. The default value is 0.
limit	query	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	Location	Type	Required	Description
agentId	path	string	Yes	The agent ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/agent/${agentId}" \
  -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	Location	Type	Required	Description
agentId	path	string	Yes	The agent ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/agent/${agentId}/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	Location	Type	Required	Description
agentId	body	string	Yes	The ID of an agent in the ACTIVE state.
title	body	string	No	The session title.
llmConfigId	body	string	No	The ID of an available LLM configuration for the current user under the specified agent.
metadata	body	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	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/session/${sessionId}" \
  -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	Location	Type	Required	Description
sessionId	path	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	body	string	No	The session title.
llmConfigId	body	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	body	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/${sessionId}" \
  -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, attachment records of the session 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	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.

Request Example

curl -X DELETE "${BASE_URL}/agent-bus/v1/session/${sessionId}" \
  -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	Location	Type	Required	Description
agentId	query	string	Yes	The agent ID. You can also specify the ID in the request URL or through the x-agent-id request header.
offset	query	int	No	Skips the first offset records. The value must be a non-negative integer. The default value is 0.
limit	query	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	body	string	Yes	The session ID. It must belong to the currently logged-in user.
message	body	string	Conditionally required	User message text, which is automatically appended to the session history.
toolResults	body	ToolResult[]	Conditionally required	The list of tool execution results. These must correspond to the toolCalls returned by the LLM in the previous turn.
content	body	array	Conditionally required	An array of content parts, containing at least one valid content part. Exactly one of message or content must be provided; toolResults can be submitted independently or alongside either of them. When using content, text must be placed in a text block. Multimodal user messages are written to the session history, but are not included in long-term memory extraction by default.
stream	body	bool	No	Whether to return a streaming response. The default value is true.
contextEvent	body	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	body	bool	No	Whether to return the reasoning process. The default value is false.
tools	body	ToolDefinition[]	No	The list of application-layer tool definitions in OpenAI function calling format.
activeSkillNames	body	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	body	string	No	LLM configuration ID to use for this request. Temporarily overrides the default configuration of the session or agent.
model	body	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	body	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	body	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	body	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	body	string/string[]	No	Temporarily sets the stop sequences for this request. Generation stops when the output matches any sequence.
extensions	body	object	No	Parameters passed directly through to the model service provider.
assemblyConfig	body	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.

Content Part

Content parts include text blocks, image blocks, and attachment reference blocks.

Text Block

{
  "type": "text",
  "text": "Please analyze this image"
}

The "text" field must be a non-empty string.

Image Block

The [OI]-compatible format is recommended:

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,iVBORw0KGgo..."
  }
}

The following compatible formats are also supported:

{"type":"image","url":"data:image/png;base64,..."}

{"type":"image_url","imageUrl":"data:image/jpeg;base64,..."}

Only the following image URL format is supported: data:<mimeType>;base64,<data> Data URL.

HTTP/HTTPS image URLs and local file paths cannot be sent directly as the "url". The caller must either convert the image content to a Base64 Data URL, or upload it as a session attachment first and then reference it using the "attachmentId".

Attachment Reference Block

{
  "type": "attachment",
  "attachmentId": "doc_xxx"
}

The attachment reference must belong to the current session, and the upload must be completed with an "attachmentId" returned by the server.

Example of a content

{
  "sessionId": "sess_xxx",
  "llmConfigId": "llm_vision_xxx",
  "stream": false,
  "content": [
    {
      "type": "text",
      "text": "Please describe the content of the image and recognize the text in it."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "data:image/png;base64,iVBORw0KGgo..."
      }
    }
  ]
}

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.

The server obtains the agent and user based on the sessionId in the request and checks the token budget before calling the LLM Provider. If the budget is insufficient, the server returns an error before calling the Provider:

{
  "error": {
    "code": "BUS_LLM_QUOTA_EXCEEDED",
    "message": "LLM_TOKEN_BUDGET_EXCEEDED: agent token budget exceeded: agentId=agent_xxx, projectedTokens=4096, remainingTokens=1024"
  }
}

When the budget is insufficient, the LLM Provider is not called, so no LLM usage is incurred.
If both the budgets for the agent and the LLM configuration are configured, the server checks the budget for the agent first, followed by the budget configured for the current llmConfigId.

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	Location	Type	Required	Description
agentId	path	string	Yes	The agent ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/skill/${agentId}/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	Location	Type	Required	Description
skillId	path	string	Yes	The skill ID.
agentId	path	string	Yes	The agent ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/skill/${skillId}/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	Location	Type	Required	Description
skillId	path	string	Yes	The skill ID.
agentId	query	string	Yes	The agent ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/skill/${skillId}/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	Location	Type	Required	Description
skillId	path	string	Yes	The skill ID.
agentId	query	string	Yes	The agent ID.
filePath	query	string	Yes	The path of the skill package file relative to the root directory.
lineStart	query	int	No	The 1-based starting line for text files. The default value is 0, which means the full file is read.
lineLimit	query	int	No	The number of lines to read. The default value is 120, and the maximum value is 300.
raw	body	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/${skillId}/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	Location	Type	Required	Description
skillId	path	string	Yes	The skill ID.
agentId	body	string	Yes	The agent ID.
query	body	string	Conditionally required	Search for a single string, 1 to 1,024 bytes. Exactly one of query, all, and any must be provided.
all	body	string[]	Conditionally required	Matches only when all specified strings are found. Up to 5 strings, each 1 to 1,024 bytes.
any	body	string[]	Conditionally required	Matches when any one of the specified strings is found. Up to 5 strings, each 1 to 1,024 bytes.
scope	body	string	No	Match scope. Valid values: "file" (entire file) and "line" (single line). The default value is "file".
caseSensitive	body	bool	No	Whether matching is case-sensitive. The default value is false.
filePaths	body	string[]	No	The list of relative paths in the skill package that limit the search scope.
extensions	body	string[]	No	Limits the search to files with the specified extensions, such as [".md",".json"].
contextLines	body	int	No	Number of context lines before and after each matching line. The default value is 3, and the maximum value is 10.
maxResults	body	int	No	Safety threshold for the total number of hits. The default value is 1000, and the maximum value is 5000.
maxPerFile	body	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	Location	Type	Required	Description
skillId	path	string	Yes	The skill ID.
agentId	body	string	Yes	The agent ID.
filePaths	body	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/${skillId}/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. Knowledge Base Access

5.1 List Knowledge Bases

Lists the active knowledge bases associated with the specified agent.

Request Method and URL

POST /agent-bus/v1/knowledge/available

Request Parameters


Parameter	Location	Type	Required	Description
sessionId	body	string	Conditionally required	The session ID. If agentId is not specified, sessionId must be specified.
agentId	body	string	Conditionally required	The agent ID. If sessionId is not specified, agentId must be specified.

Note:

If both sessionId and agentId are specified, the agent associated with sessionId must be the same as the agent corresponding to agentId.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/knowledge/available" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: knowledge_available" \
  -d "{
    \"agentId\": \"${agentId}\",
    \"sessionId\": \"${sessionId}\"
    }"

Response Example

Each element in the items array represents a knowledge base and contains the following three fields:

knowledgeBaseId: The knowledge base ID, used in subsequent retrieve and read APIs
name: The knowledge base name
description: The knowledge base description

{
 "items": [
   {
     "knowledgeBaseId": "kb_c0566aa1-e175-5ba6-ef4f-ff93ae4cbb0d",
     "name": "Manual",
     "description": "test"
   }
 ]
}

5.2 Retrieve from a Knowledge Base

Retrieves information from a knowledge base based on the specified content. Each request can retrieve data from only one knowledge base. To retrieve from multiple knowledge bases, first call the available API, then call the retrieve API multiple times and organize the results yourself.

Request Method and URL

POST /agent-bus/v1/knowledge/retrieve

Request Parameters


Parameter	Location	Type	Required	Description
sessionId	body	string	Conditionally required	The session ID. If agentId is not specified, sessionId must be specified.
agentId	body	string	Conditionally required	The agent ID. If sessionId is not specified, agentId must be specified.
knowledgeBaseId	body	string	Yes	The knowledge base ID. The knowledge base must be active and associated with the target agent.
query	body	string	Yes	The content to retrieve. After leading and trailing whitespace is removed, it must be a non-empty string. The original UTF-8-encoded content must not exceed 16 KiB.

Note:

If both sessionId and agentId are specified, the agent associated with sessionId must be the same as the agent corresponding to agentId.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/knowledge/retrieve" \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer ${TOKEN}" \
 -H "x-request-id: knowledge_retrieve" \
 -d "{
     \"agentId\": \"${agentId}\",
     \"knowledgeBaseId\": \"${knowledgeBaseId}\",
     \"query\": \"test\"
 }"

Response Example

Each element in the items array contains information about a chunk in the knowledge base that matches the query content. For the field description, see ChunkInfo. An empty items array indicates that no relevant content was found in the knowledge base.

{
 "retrievalId": "ret_ea36ee47-073e-caa0-4847-d64b5536f6d6",
 "resultStatus": "OK",
 "items": [
   {
     "chunkId": "chk_249b86f3bbea9c810625581497941915",
     "content": "# Test attachment upload",
     "source": {
         "documentId": "doc_5eeaa1fb2afd07d21110cbfa45c141cf",
         "fileName": "README.md",
         "pageNo": null
       }
   },
   {
     "chunkId": "chk_e033d9d3a223caa93c668e8a32ee86e7",
     "content": "This is a markdown file for test",
      "source": {
         "documentId": "doc_5eeaa1fb2afd07d21110cbfa45c141cf",
         "fileName": "README.md",
         "pageNo": null
     }
   }
 ]
}

5.3 Read a Chunk and Its Adjacent Content

Reads information about the chunk specified by chunkId and its adjacent chunks.

Note:

Only the currently active index of the knowledge base is queried, and the target document must still have an ACTIVE status. After the index is updated, the old chunkId may become invalid. To query the content again, call retrieve to obtain the latest results. We do not recommend caching chunkId as a long-term reference.

Request Method and URL

POST /agent-bus/v1/knowledge/read

Request Parameters


Parameter	Location	Type	Required	Description
sessionId	body	string	Conditionally required	The session ID. If agentId is not specified, sessionId must be specified.
agentId	body	string	Conditionally required	The agent ID. If sessionId is not specified, agentId must be specified.
knowledgeBaseId	body	string	Yes	The knowledge base ID. The knowledge base must be active and associated with the target agent.
chunkId	body	string	Yes	The chunk ID. Obtained through the `retrieve` API.
before	body	int	No	Returns information about the n chunks preceding the specified chunk. The valid range is [0, 5], and the default value is 0.
after	body	int	No	Returns information about the n chunks following the specified chunk. The valid range is [0, 5], and the default value is 0.

Note:

If both sessionId and agentId are specified, the agent associated with sessionId must be the same as the agent corresponding to agentId.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/knowledge/read" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: knowledge_read" \
  -d "{
    \"agentId\": \"${agentId}\",
    \"knowledgeBaseId\": \"${knowledgeBaseId}\",
    \"chunkId\": \"${chunkId}\",
    \"before\": 1,
    \"after\": 1
  }"

Response Example

item contains information about the specified chunk. The elements in the before and after arrays contain information about the chunks immediately preceding and following the specified chunk. These elements have the same structure as item. For the field description, see ChunkInfo.

{
 "item": {
     "chunkId": "chk_249b86f3bbea9c810625581497941915",
     "content": "# Test attachment upload",
     "source": {
       "documentId": "doc_5eeaa1fb2afd07d21110cbfa45c141cf",
       "fileName": "README.md",
       "pageNo": null
   }
 },
 "before": [],
 "after": [
   {
     "chunkId": "chk_e033d9d3a223caa93c668e8a32ee86e7",
     "content": "This is a markdown file for test",
     "source": {
       "documentId": "doc_5eeaa1fb2afd07d21110cbfa45c141cf",
       "fileName": "README.md",
       "pageNo": null
   }
  }
 ]
}

6. Session Attachment Management

You can upload attachments in the following formats to a session:


Category	Extension or MIME type
image	png, jpg, jpeg, webp, gif, or image/*
pdf	pdf or application/pdf
document	docx or a DOCX MIME type
presentation	pptx or a PPTX MIME type
spreadsheet	xlsx
text	txt, text, log, md, csv, tsv, xml, text/*, or application/xml

6.1 Initialize an Attachment Upload

Declares the metadata for the attachment to be uploaded. Then, you can upload the attachment through the chunk upload API.

Request Method and URL

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

Request Parameters


Parameter	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.
filename	body	string	Yes	The name of the attachment to upload. The server determines the attachment type from the filename and MIME type.
mimeType	body	string	Yes	The MIME type of the attachment, in `type/subtype` format. For example, specify "image/png" for a PNG image.
byteSize	body	integer	Yes	The total size of the attachment in bytes. The value must be greater than 0 and must not exceed the server's per-attachment size limit.
sha256	body	string	Yes	SHA-256 hash of the complete attachment, represented as a 64-character hexadecimal string.
extra	body	string	No	Additional information.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_upload_init" \
  -d "{
    \"filename\": \"architecture.png\",
    \"mimeType\": \"image/png\",
    \"byteSize\": 417996,
    \"sha256\": \"${file_sha256}\",
    \"extra\": \"image of DolphinDB architecture\"
  }"

Response Example

For the response field description, see SessionAttachmentInfo.

{
   "attachmentId": "img_e80e3523ea5ad6bae8f6b2c0985daeb0",
   "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
   "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
   "userId": "admin",
   "filename": "architecture.png",
   "mimeType": "image/png",
   "kind": "image",
   "byteSize": 417996,
   "sha256": "72d9842aaef8ee95b52dd60eba7896b439c10d2c7174675bd9b0977d2f80f53c",
   "uploadStatus": "UPLOADING",
   "parseStatus": "NOT_APPLICABLE",
   "indexStatus": "NOT_APPLICABLE",
   "parseError": null,
   "indexError": null,
   "schemaVersion": 2,
   "extra": "image of DolphinDB architecture",
   "createTime": "2026.09.03 11:23:43.301",
   "updateTime": "2026.09.03 11:23:43.301",
   "partSize": 4194304,
   "partCount": 1,
   "uploadedPartCount": 0
}

6.2 Upload Attachment Parts

Uploads the attachment parts in sequence.

Request Method and URL

PUT /agent-bus/v1/session/{sessionId}/attachments/{attachmentId}/parts/{partNo}

Request Parameters


Parameter	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.
attachmentId	path	string	Yes	The attachment ID.
partNo	path	integer	Yes	The part number, starting from 0.
X-Part-SHA256	header	string	Yes	SHA-256 checksum of the current part, used to verify the integrity of the part data.
/	body	binary	Yes	Binary data of the current part, with the content type `application/octet-stream`.

Request Example

curl -X PUT "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments/${attachmentId}/parts/0" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Content-Type: application/octet-stream" \
    -H "X-Part-SHA256: ${PART_SHA256}" \
    --data-binary "@${PART}"

Response Example

For the response field description, see SessionAttachmentInfo.

{
  "attachmentId": "img_e80e3523ea5ad6bae8f6b2c0985daeb0",
  "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
  "userId": "admin",
  "filename": "architecture.png",
  "mimeType": "image/png",
  "kind": "image",
  "byteSize": 417996,
  "sha256": "72d9842aaef8ee95b52dd60eba7896b439c10d2c7174675bd9b0977d2f80f53c",
  "uploadStatus": "UPLOADING",
  "parseStatus": "NOT_APPLICABLE",
  "indexStatus": "NOT_APPLICABLE",
  "parseError": null,
  "indexError": null,
  "schemaVersion": 2,
  "extra": "image of DolphinDB architecture",
  "createTime": "2026.09.03 11:23:43.301",
  "updateTime": "2026.09.03 11:23:43.301",
  "partSize": 4194304,
  "partCount": 1,
  "uploadedPartCount": 1
}

6.3 Complete the Attachment Upload

Completes the attachment upload by validating the number and size of parts and the SHA-256 hash of the complete attachment, then parsing and indexing it.

Note:

Attachment parsing and indexing depend on the DocParser and ModelInference plugins, respectively. The DolphinDB node that processes the attachment must load the corresponding plugins. Otherwise, parseStatus is set to PARSE_FAILED or indexStatus is set to INDEX_FAILED, respectively.

Request Method and URL

POST /agent-bus/v1/session/{sessionId}/attachments/{attachmentId}/complete

Request Parameters


Parameter	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.
attachmentId	path	string	Yes	The attachment ID.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments/${attachmentId}/complete" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_upload_complete"

Response Example

For the response field description, see SessionAttachmentInfo.

If an image is uploaded successfully, uploadStatus=COMMITTED is returned, and both the parsing and indexing statuses are NOT_APPLICABLE.
Document parsing succeeded: the response contains parseStatus=PARSED and indexStatus=INDEXING.
Document parsing failed: the response contains parseStatus=PARSE_FAILED and parseError. The original asset is retained, and you can call this API again to retry.
Index creation succeeded: the response contains indexStatus=READY.
Index creation failed: the response contains indexStatus=INDEX_FAILED. You can call the index endpoint to retry.

{
  "attachmentId": "img_e80e3523ea5ad6bae8f6b2c0985daeb0",
  "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
  "userId": "admin",
  "filename": "architecture.png",
  "mimeType": "image/png",
  "kind": "image",
  "byteSize": 417996,
  "sha256": "72d9842aaef8ee95b52dd60eba7896b439c10d2c7174675bd9b0977d2f80f53c",
  "uploadStatus": "COMMITTED",
  "parseStatus": "NOT_APPLICABLE",
  "indexStatus": "NOT_APPLICABLE",
  "parseError": null,
  "indexError": null,
  "schemaVersion": 2,
  "extra": "image of DolphinDB architecture",
  "createTime": "2026.09.03 11:23:43.301",
  "updateTime": "2026.09.03 14:22:34.651"
}

6.4 Rebuild the Index

If attachment parsing succeeds (parseStatus=PARSED) but index creation fails, you can call this API to retry.

Request Method and URL

POST /agent-bus/v1/session/{sessionId}/attachments/{attachmentId}/index

Request Parameters


Parameter	Location	Type	Required	Description
attachmentId	path	string	Yes	The attachment ID.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments/${attachmentId}/index" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_index"

Response Example

For the response field description, see SessionAttachmentInfo.

{
  "attachmentId": "doc_20c06b45a8f42998ddab4846343a25c8",
  "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
  "userId": "admin",
  "filename": "README.md",
  "mimeType": "text/markdown",
  "kind": "text",
  "byteSize": 91,
  "sha256": "d49c9511f1e7314af7f2488005c05eedc99a0716558fc19aa226cae05e1254d6",
  "uploadStatus": "COMMITTED",
  "parseStatus": "PARSED",
  "indexStatus": "READY",
  "parseError": null,
  "indexError": null,
  "schemaVersion": 2,
  "extra": "README file for the project",
  "createTime": "2026.09.03 14:34:55.178",
  "updateTime": "2026.09.03 14:46:48.644"
}

6.5 List Session Attachments

Lists the attachments in the specified session.

Request Method and URL

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

Request Parameters


Parameter	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.

Request Example

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

Response Example

Each element in the items array contains information about one attachment. For the field description, see SessionAttachmentInfo.

{
  "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
  "items": [
     {
        "attachmentId": "img_e80e3523ea5ad6bae8f6b2c0985daeb0",
        "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
        "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
        "userId": "admin",
        "filename": "architecture.png",
        "mimeType": "image/png",
        "kind": "image",
        "byteSize": 417996,
        "sha256": "72d9842aaef8ee95b52dd60eba7896b439c10d2c7174675bd9b0977d2f80f53c",
        "uploadStatus": "COMMITTED",
        "parseStatus": "NOT_APPLICABLE",
        "indexStatus": "NOT_APPLICABLE",
        "parseError": null,
        "indexError": null,
        "schemaVersion": 2,
        "extra": "image of DolphinDB architecture",
        "createTime": "2026.09.03 11:23:43.301",
        "updateTime": "2026.09.03 14:22:34.651"
            }
  ],
  "offset": 0,
  "limit": 100,
  "size": 1
}

6.6 Get Attachment Information

Gets information about the specified attachment.

Request Method and URL

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

Request Parameters


Parameter	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.
attachmentId	path	string	Yes	The attachment ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments/{attachmentId}" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_info"

Response Example

For the response field description, see SessionAttachmentInfo.

{
  "attachmentId": "doc_20c06b45a8f42998ddab4846343a25c8",
  "sessionId": "5884131e-3a03-078d-df44-8315b4e9a277",
  "agentId": "agent_builtin_3f9e3c9d-1b10-4d12-9d4a-0d47a9dfb001",
  "userId": "admin",
  "filename": "README.md",
  "mimeType": "text/markdown",
  "kind": "text",
  "byteSize": 91,
  "sha256": "d49c9511f1e7314af7f2488005c05eedc99a0716558fc19aa226cae05e1254d6",
  "uploadStatus": "COMMITTED",
  "parseStatus": "PARSED",
  "indexStatus": "READY",
  "parseError": null,
  "indexError": null,
  "schemaVersion": 2,
  "extra": "README file for the project",
  "createTime": "2026.09.03 14:34:55.178",
  "updateTime": "2026.09.03 14:46:48.644"
}

6.7 Download the Original Attachment File

Directly returns the original file content as uploaded, without a JSON envelope or Base64 encoding. The attachment must be in the COMMITTED state. Its parsing and indexing statuses do not affect downloading.

Request Method and URL

GET /agent-bus/v1/session/{sessionId}/attachments/{attachmentId}/content

Request Parameters


Parameter	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.
attachmentId	path	string	Yes	The attachment ID.

Request Example

OUTPUT='./downloaded-file'
curl -i GET "$BASE_URL/agent-bus/v1/session/${sessionId}/attachments/${attachmentId}/content" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_download" \
  --output "${OUTPUT}"

Response Example

HTTP/1.1 200 OK
Content-Length: 91
X-Content-SHA256: d49c9511f1e7314af7f2488005c05eedc99a0716558fc19aa226cae05e1254d6
X-Agent-Bus-Streaming: false
Content-Type: text/markdown
Access-Control-Expose-Headers: Content-Disposition, X-Content-SHA256
Content-Disposition: attachment; filename="README.md"; filename*=UTF-8''README.md
Access-Control-Allow-Origin: *
Connection: close

# Test attachment upload

This is a markdown file for test

6.8 Retrieve Attachments

Retrieves chunks from attachments based on the query.

Note:

Only non-image attachments with uploadStatus=COMMITTED, parseStatus=PARSED, and indexStatus=READY can be searched. An explicitly provided attachment ID must belong to the specified session. The API returns NOT_FOUND for nonexistent attachments and a parameter error or conflict for images or attachments that are not ready.

Request Method and URL

POST /agent-bus/v1/session/{sessionId}/attachments/retrieve

Request Parameters


Field	Location	Type	Required	Description
query	body	string	Yes	The query content, encoded in UTF-8 and limited to 16 KiB.
topK	body	integer	No	The number of chunks to return, from 1 to 20. The default value is 8.
attachmentIds	body	string[]	No	Specifies the attachments to retrieve. If empty or omitted, all searchable attachments in the current session are searched. The default is empty.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/session/${sessionId}/attachments/retrieve" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_retrieve" \
  -d "{
    \"query\": \"测试\",
    \"topK\": 5,
    \"attachmentIds\": [\"${attachmentId}\"]
  }"

Response Example

{
 "retrievalId": "ret_bcc831d2-1861-e5b9-e244-ee69cf714298",
 "resultStatus": "OK",
 "items": [
     {
     "chunkId": "chk_909c5cf36fe6736745fd69fce0a8dc36",
     "content": "# Test attachment upload",
     "source": {
     "attachmentId": "doc_20c06b45a8f42998ddab4846343a25c8",
     "fileName": "README.md",
     "pageNo": null
     }
 },
     {
     "chunkId": "chk_c87b675323193785f1fe7855c47b86de",
     "content": "This is a markdown file for test",
     "source": {
     "attachmentId": "doc_20c06b45a8f42998ddab4846343a25c8",
     "fileName": "README.md",
     "pageNo": null
     }
  }
 ]
}

6.9 Delete an Attachment

Deletes the specified attachment.

Request Method and URL

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

Request Parameters


Parameter	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.
attachmentId	path	string	Yes	The attachment ID.

Request Example

curl -X DELETE "$BASE_URL/agent-bus/v1/session/${sessionId}/attachments/${attachmentId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: attachment_delete"

Response Example

deleted=true indicates that the logical deletion has taken effect and the background cleanup task has been submitted. It does not indicate that the parsing blocks, index, and asset chunks have been physically deleted.

{
   "attachmentId": "img_b17760a09aeba5eb7ae6a56f04e8e7a3",
   "deleted": true
}

7. 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.

7.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	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/workspace/${sessionId}/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
}

7.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	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.
name	query	string	Yes	File name. Paths are not supported.
startLine	query	int	No	Start line, 1-based. Defaults to line 1.
endLine	query	int	No	End line, inclusive. Defaults to the end of the file.

Request Example

curl -X GET "${BASE_URL}/agent-bus/v1/workspace/${sessionId}/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.

7.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	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.
name	body	string	Yes	File name. Paths are not supported.
content	body	string	Yes	UTF-8 text content.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/workspace/${sessionId}/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"
}

7.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	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.
name	body	string	Yes	File name. Paths are not supported.

Request Example

curl -X DELETE "${BASE_URL}/agent-bus/v1/workspace/${sessionId}/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
}

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

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

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/workspace/${sessionId}/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.

8. 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	Location	Type	Required	Description
agentId	body	string	Conditionally required	The agent ID.
method	body	string	Yes	Only "GET" and "POST" are supported. Matching is case-insensitive.
url	body	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	body	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	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	body	int	No	Request timeout in milliseconds. The default value is 10000, and the maximum value is 30000.
maxBodyBytes	body	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
}

9. 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	Location	Type	Required	Description
sessionId	body	string	Yes	The session ID. It must belong to the currently logged-in user. DolphinX resolves the agent from the session.
toolName/name	body	string	Yes	The name of the MCP composite tool to execute. This usually comes from `toolCalls[].function.name` in the previous turn.
arguments	body	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.

10. 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	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.
instructions	body	string	No	Additional summary instructions to append to the summary prompt.
llmConfigId	body	string	No	The ID of the LLM configuration to prefer for this summary.
force	body	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	body	object	No	User-defined metadata in JSON format. DolphinX only passes it through.

Request Example

curl -X POST "${BASE_URL}/agent-bus/v1/session/${sessionId}/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"
  }
}

11. 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	Location	Type	Required	Description
sessionId	body	string	Yes	The session ID. The session must be within the readable scope of the currently logged-in user.
message	body	string	Conditionally required	User message text. You must provide exactly one of message and toolResults.
toolResults	body	ToolResult[]	Conditionally required	The list of tool execution results. These must correspond to the toolCalls returned by the LLM in the previous turn.
content	body	array	Conditionally required	An array of content parts, containing at least one valid content part. Exactly one of message or content must be provided; toolResults can be submitted independently or alongside either of them. When using content, text must be placed in a text block. Multimodal user messages are written to the session history, but are not included in long-term memory extraction by default.
tools	body	ToolDefinition[]	No	The list of tool definitions. If assemblyConfig is present, put this in `assemblyConfig.tools` instead.
activeSkillNames	body	string[]	No	The names of the skills proactively loaded for this request. If assemblyConfig is present, put this in `assemblyConfig.activeSkillNames` instead.
llmConfigId	body	string	No	The ID of the LLM configuration used to resolve the context window and token budget.
assemblyConfig	body	object	No	Manual assembly configuration. The structure is the same as the manual assembly mode in Chat Completions.
maxTokens/max_tokens/max_completion_tokens	body	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.

12. Low-Level APIs

12.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	Location	Type	Required	Description
agentId	body	string	Conditionally required	The agent ID.
sessionId	body	string	No	The session ID.
messages	body	LLMMessage[]	Yes	The complete message list constructed by the application layer and sent directly to the LLM.
tools	body	ToolDefinition[]	No	The list of tool definitions in the OpenAI function calling format.
model	body	string	No	Temporarily sets the model name for this request.
stream	body	bool	No	Whether to return a streaming response. The default value is true.
includeReasoning	body	bool	No	Whether to return the reasoning process. The default value is false.
llmConfigId	body	string	No	The LLM configuration ID.
requestId	body	string	No	The request trace ID. If omitted, it is generated automatically.
temperature	body	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	body	int	No	Temporarily overrides the output token limit for this request. The three fields are equivalent. We recommend passing only one.
topP/top_p	body	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	body	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	body	bool	No	Valid only when sessionId is specified. When set to true, appends the model response to that session.
extensions	body	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
  }
}

The server obtains the agent and user based on the agentId or sessionId in the request and checks the token budget before calling the LLM Provider. If the budget is insufficient, the server returns an error before calling the Provider:

{
  "error": {
    "code": "BUS_LLM_QUOTA_EXCEEDED",
    "message": "LLM_TOKEN_BUDGET_EXCEEDED: model token budget exceeded: agentId=agent_xxx, model=gpt-4.1, projectedTokens=4096, remainingTokens=1024"
  }
}

When the budget is insufficient, the LLM Provider is not called, so no LLM usage is incurred.

12.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	Location	Type	Required	Description
sessionId	path	string	Yes	The session ID.
startSeq	query	long	No	The starting message sequence number. The default value is 1.
endSeq	query	long	No	The ending message sequence number. By default, no ending sequence number is specified.
limit	query	int	No	The maximum number of messages to return; you must specify it together with the from parameter. By default, there is no limit on the number of messages.
from	query	string	No	Specifies where to retrieve messages from; you must specify it together with with the limit parameter. Valid values are as follows: front: retrieves messages from the beginning of the range onward tail: retrieves messages from the end of the range backward

Request Example

Example 1: Retrieve messages with sequence numbers from 1 to 100

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

Example 2: Retrieve the latest 50 messages

curl -X GET "${BASE_URL}/agent-bus/v1/session/${sessionId}/messages?limit=50&from=tail" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-request-id: req_session_messages"

Example 3: Starting with message 100, retrieve the previous 50 messages

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

Example 4: Starting with message 150, retrieve the next 50 messages

curl -X GET "${BASE_URL}/agent-bus/v1/session/${sessionId}/messages?startSeq=150&limit=50&from=front" \
  -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
}