Response Data Structures

This article describes the data structures that appear repeatedly in DolphinX API responses, helping developers process business data based on these structures.

1. AgentInfo

Field Type Description
agentId string The globally unique agent ID, generated by DolphinX when the agent is registered.
agentName string The agent name.
description string The agent description.
status int The value of the agent status.
  • 0: REGISTERED
  • 1: ACTIVE
  • 2: SUSPENDED
  • 3: DELETED
statusName string The name of the agent status.
  • "REGISTERED": Registered; sessions cannot be created.
  • "ACTIVE": Active and ready for use.
  • "SUSPENDED": Suspended.
  • "DELETED": Deleted.
myPermission string The current user's effective permission on this agent. The field value is AGENT_INVOKE or AGENT_ADMIN. Only the agent/accessible API supports returning this field.

2. SelectableLlmInfo

Field Type Description
llmConfigId string The LLM configuration ID, which can be passed to APIs such as session/create,chat/completions, and session/{sessionId}/summary.
name string The configuration name.
model string The model name.
capability string The configuration capability type. Currently, "chat" is primarily used.
contextWindow int/null The size of the model context window, in tokens. If empty, the default context budget is used.
source string The configuration source. The field value is "agent", "user", or "both".
isAgentDefault bool Whether this is the default model for the specified agent.
participatesInFallback bool Whether this configuration is bound to the specified agent and can be used as a fallback LLM configuration.
fallbackPriority int/null The fallback order. This field has a value only when participatesInFallback=true.

3. SessionInfo

Field Type Description
sessionId string The globally unique session ID, generated automatically at creation.
agentId string The ID of the agent that to which the session belongs. You can specify it when creating the session, and it cannot be changed after creation.
llmConfigId string The ID of the LLM configuration used by the session.
title string The session title, which can be updated through the /session/{sessionId} API.
metadata object User-defined metadata in JSON format, which can be updated through the /session/{sessionId} API.
createTime timestamp The time when the session was created.
updateTime timestamp The time of the most recent session message. If there are no messages, this value is the same as createTime.

4. MessageInfo

Field Type Description
messageId string The unique message ID, generated automatically when a message is sent.
sessionId string The ID of the session to which the message belongs.
agentId string The ID of the agent to which the message belongs.
sequenceNum long A monotonically increasing sequence number within the session, starting from 1. It is used for message ordering and range queries.
role string The message role.
  • "system": System instructions.
  • "user": User input.
  • "assistant": LLM response.
  • "tool": Tool execution result.
contentType string The content type, which determines how the content is parsed when the context is assembled.
  • "text": Plain text, used directly as message.content.
  • "tool_call": A tool call. content is a JSON-formatted toolCalls array, which is parsed into the OpenAI tool_calls structure during assembly.
  • "tool_result": A tool result. During assembly, it uses role=tool and includes toolCallId.
  • "summary": A session summary written internally by DolphinX. In summary-first mode, it is injected as the latest summary. Its metadata records summaryUpToSeqNum and trigger.
content string The message content. The format depends on contentType: text and tool_result are plain text, while tool_call is JSON ({"toolCalls":[...]} or [{...}]).
toolCallId string The tool call association ID, used to associate a tool execution result with the corresponding tool in the LLM call (the same toolCallId).
metadata object User-defined metadata in JSON format.
createTime timestamp The time when the message was created.

5. SkillInfo

Field Type Description
skillId string The unique skill ID, generated automatically at registration.
name string The skill name, which is globally unique when enabled. Can be passed to activeSkillNames to actively load the skill.
description string The skill description, shown in the skill catalog to help the LLM determine whether the skill is needed.
license string The license information.
compatibility string Compatibility notes, such as the minimum required DolphinX version.
argumentHint string Argument hints, shown in the skill catalog to instruct the LLM on how to call the skill.
disableModelInvocation bool Whether automatic LLM invocation is disabled. A value of true indicates that the skill does not appear in the skill catalog discoverable by the LLM, but it can still be called explicitly.
userInvocable bool Whether users are allowed to call the skill directly.
hasInstruction bool Whether the skill package includes detailed instructions, which are the body content after the SKILL.md frontmatter.
displayName string The skill display name.
category string The skill category label, used to filter by category.
version string The skill version number, such as 1.0.0.
metadata object User-defined metadata.

6. NetworkFetchResponse

Field Type Description
url string The normalized request URL.
method string The HTTP method actually used for the request: GET or POST.
statusCode int The HTTP status code returned by the target site. DolphinX does not automatically follow 3xx redirects.
statusText string The HTTP status text returned by the target site.
headers object The response headers returned by the target site.
contentType string The Content-Type parsed from the response headers, or an empty string if it is not present.
contentEncoding string The Content-Encoding parsed from the response headers, or an empty string if it is not present.
body string The text response body. An empty string for binary, unknown-type, or non-identity-encoded responses.
truncated bool Whether the response body was truncated because it exceeded the maxBodyBytes limit.
bodyOmitted bool Whether the body was omitted because its content type or encoding is not suitable for inclusion in a JSON response.
bodyUtf8Sanitized bool Whether the text body was sanitized for UTF-8 safety; this commonly occurs when truncation cuts through a multibyte character or the upstream server returns invalid UTF-8.
latencyMs long The duration of this network request, in milliseconds.

7. McpToolCallResult

Field Type Description
ok bool Whether the tool execution succeeded. A value of false indicates that the MCP server returns a tool-level error.
isError bool The tool-level error flag in the MCP tools/call result.
truncated bool Whether the raw MCP server response was truncated by the read limit.
content any The content returned by MCP tools/call, typically MCP content data.
error string The reason the DolphinX-side operation or MCP call fails. Returned only on failure.

8. LLMResponse

Field Type Description
requestId string The unique request ID, used for tracing and log correlation.
sessionId string The ID of the session associated with the request, if any.
model string The name of the LLM model actually used, as returned by the LLM provider.
llmConfigId string The ID of the LLM configuration actually used.
content string The text content of the LLM response.
reasoning string Displayable reasoning text returned by the LLM provider. This field is non-empty only when includeReasoning=true is specified and the provider returns displayable reasoning; otherwise, it is an empty string.
toolCalls ToolCall[] The list of tool calls initiated by the LLM. When this field is non-empty, finishReason is usually tool_calls/tool_use, and the application layer should execute the tools and append the results as tool_result messages.
finishReason string The finish reason. Values depend on the LLM provider.
  • OpenAI-style values: "stop" (completed normally), "tool_calls" (tool calls required), "length" (reached the max_tokens limit), and "content_filter" (content filtered).
  • Anthropic-style values: "end_turn", "tool_use", "max_tokens", and "stop_sequence".
usage object Token usage statistics for this request.
usage.promptTokens int The number of input tokens: the tokens consumed by the full context sent to the LLM.
usage.completionTokens int The number of output tokens: the tokens consumed by the response generated by the LLM.
usage.totalTokens int The total number of tokens.
latencyMs long The end-to-end latency of this LLM request, in milliseconds.
metadata object Additional metadata. The chat/complete response includes auxiliary model-selection fields: requestedLlmConfigId (the original target LLM configuration ID) and fallbackApplied (whether the preferred configuration was switched to a fallback configuration). The LLM configuration ID actually used is provided in the top-level llmConfigId field. When fallbackApplied=true, the response also includes fallbackFromLlmConfigId (the original configuration ID), fallbackReason (the reason the original configuration call failed), and fallbackStatusCode (the failure status code from the original configuration call).

9. ToolCall

Field Type Description
id string The unique tool call ID, such as “call_abc123”. After the application layer executes the tool, it must append the result as a tool_result message with the same toolCallId so that the LLM can associate the call with its result.
type string Always returns "function".
function.name string The name of the function or tool to call.
function.arguments string The call arguments as a JSON-formatted string.
index int The call index in a streaming response. Optional; used to assemble chunked tool_call deltas into a complete call.

10. SummaryResult

Field Type Description
sessionId string The session ID.
generated bool Whether a summary was actually generated. A value of false indicates that there was no compressible raw history for this request or that no summary needed to be generated. See reason for details.
reason string The reason no summary was generated. Empty when generated=true.
trigger string Trigger method:"manual":
  • "manual": The user manually called the summary API.
  • "auto": Automatic summary performed before the main /chat/completions flow.
summaryUpToSeqNum long The coverage boundary of the latest summary generated by this request. Indicates that the summary covers all historical messages with sequenceNum <= summaryUpToSeqNum.
Other MessageInfo fields - Details of the generated summary message itself, such as messageId, sequenceNum, role="system", contentType="summary", and content="Summary content...".