响应数据结构

本文介绍 DolphinX API 响应中反复出现的数据结构，方便开发者根据这些结构处理业务数据。

1. AgentInfo

字段 类型 说明
agentId string 全局唯一的 Agent ID，由 DolphinX 在注册 Agent 时生成。
agentName string Agent 名称。
description string Agent 描述信息。
status int Agent 状态值。

  • 0：REGISTERED

  • 1：ACTIVE

  • 2：SUSPENDED

  • 3：DELETED
statusName string Agent 状态名称。

  • "REGISTERED"：已注册，不可创建会话

  • "ACTIVE"：已激活，可正常使用

  • "SUSPENDED"：已挂起

  • "DELETED"：已删除
myPermission string 当前用户对该 Agent 的有效权限。字段值为 AGENT_INVOKE 或 AGENT_ADMIN。仅 agent/accessible 接口支持返回该字段。

2. SelectableLlmInfo

字段 类型 说明
llmConfigId string LLM 配置 ID，可传给 session/create、chat/completions、session/{sessionId}/summary 等接口。
name string 配置名称。
model string 模型名称。
capability string 配置能力类型，当前主要使用 chat。
contextWindow int/null 模型上下文窗口大小（token 数）；为空时使用平台默认上下文预算。
source string 配置来源。字段值为 "agent"、"user" 或 "both"。
isAgentDefault bool 是否为指定 Agent 的默认模型。
participatesInFallback bool 是否与指定 Agent 绑定，并可作为备用 LLM 配置。
fallbackPriority int/null 备用切换顺序；仅 participatesInFallback=true 时有值。

3. SessionInfo

字段 类型 说明
sessionId string 全局唯一的会话 ID，创建时自动生成。
agentId string 会话所属 Agent 的 ID，可在创建会话时指定，创建后不可变更。
llmConfigId string 会话使用的 LLM 配置的 ID。
title string 会话标题，可通过 /session/{sessionId} 接口修改。
metadata object JSON 格式的自定义元数据，可通过 /session/{sessionId} 接口修改。
createTime timestamp 会话创建时间。
updateTime timestamp 最近会话消息时间。无消息时等于 createTime。

4. MessageInfo

字段 类型 说明
messageId string 唯一的消息 ID，发送消息时自动生成。
sessionId string 消息所属会话的 ID。
agentId string 消息所属 Agent 的 ID。
sequenceNum long 会话内单调递增序列号，从 1 开始，用于消息排序和范围查询。
role string 消息角色。

  • "system"：系统指令

  • "user"：用户输入

  • "assistant"：LLM 回复

  • "tool"：工具执行结果
contentType string 内容类型，决定上下文组装时的解析方式。

  • "text"：纯文本，直接作为 message.content。

  • "tool_call"：工具调用，content 为 JSON 格式的 toolCalls 数组，组装时解析为 OpenAI tool_calls 结构。

  • "tool_result"：工具结果，组装时使用 role=tool 并附带 toolCallId。

  • "summary"：会话摘要，由 DolphinX 内部写入，在 summary-first 模式下作为 latest summary 注入；其 metadata 中记录 summaryUpToSeqNum 和 trigger。
content string 消息内容。格式取决于 contentType：text 和 tool_result 为纯文本，tool_call 为 JSON（{"toolCalls":[...]} 或 [{...}]）。
toolCallId string 工具调用关联 ID，用于将工具执行结果关联到 LLM 调用的对应工具（同一个 toolCallId）。
metadata object JSON 格式的自定义元数据。
createTime timestamp 消息创建时间。

5. SkillInfo

字段 类型 说明
skillId string 唯一的技能 ID，注册时自动生成。
name string 技能名称，启用状态下全局唯一。可传入 activeSkillNames 用于主动加载技能。
description string 技能描述，在技能目录中展示，帮助 LLM 判断是否需要该技能。
license string 许可证信息。
compatibility string 兼容性说明（如最低 DolphinX 版本要求）。
argumentHint string 参数提示信息，在技能目录中展示，提示 LLM 如何调用该技能。
disableModelInvocation bool 是否禁止 LLM 自动调用。为 true 时该技能不会出现在 LLM 可发现的技能目录中，但仍可显式调用。
userInvocable bool 是否允许用户直接调用该技能。
hasInstruction bool 技能包中是否包含详细指令（SKILL.md frontmatter 之后的正文内容）。
displayName string 技能显示名称。
category string 技能分类标签，用于按分类筛选。
version string 技能版本号（如 1.0.0）。
metadata object 自定义元数据。

6. NetworkFetchResponse

字段 类型 说明
url string 规范化后的请求 URL。
method string 实际发起的 HTTP 方法：GET 或 POST。
statusCode int 目标站点返回的 HTTP 状态码。3xx 重定向不会被 DolphinX 自动跟随。
statusText string 目标站点返回的 HTTP 状态描述。
headers object 目标站点返回的响应头。
contentType string 从响应头解析出的 Content-Type，不存在时为空字符串。
contentEncoding string 从响应头解析出的 Content-Encoding，不存在时为空字符串。
body string 文本类响应体。二进制、未知类型或非 identity 编码响应为空字符串。
truncated bool 响应体是否因 maxBodyBytes 上限被截断。
bodyOmitted bool 是否因为内容类型或编码不适合放入 JSON 响应而省略 body。
bodyUtf8Sanitized bool 文本 body 是否经过 UTF-8 安全处理；常见于截断刚好切断多字节字符或上游返回非法 UTF-8。
latencyMs long 本次网络请求耗时，单位毫秒。

7. McpToolCallResult

字段 类型 说明
ok bool 工具执行是否成功。MCP Server 返回工具级错误时为 false。
isError bool MCP tools/call 结果中的工具级错误标记。
truncated bool MCP Server 原始响应是否被读取上限截断。
content any MCP tools/call 返回的内容，通常为 MCP content 数据。
error string DolphinX 侧或 MCP 调用失败原因，仅失败时返回。

8. LLMResponse

字段 类型 说明
requestId string 唯一的请求 ID，用于追踪和日志关联。
sessionId string 请求所属会话的 ID（如有）。
model string 实际使用的 LLM 模型名称（由 LLM 提供商返回）。
llmConfigId string 实际使用的 LLM 配置的 ID。
content string LLM 回复的文本内容。
reasoning string LLM 提供商返回的可展示 reasoning 文本；仅指定 includeReasoning=true 且提供商返回可展示的 reasoning 时非空，否则为空字符串。
toolCalls ToolCall[] LLM 发起的工具调用列表。非空时 finishReason 通常为 tool_calls/tool_use，应用层应执行工具并将结果追加为 tool_result 消息。
finishReason string 结束原因，值取决于 LLM 提供商。

  • OpenAI 系："stop"（正常结束）、"tool_calls"（需要调用工具）、"length"（达到 max_tokens 限制）、"content_filter"（内容过滤）。

  • Anthropic 系："end_turn"、"tool_use"、"max_tokens" 、"stop_sequence"。
usage object 本次请求的 token 用量统计。
usage.promptTokens int 输入 token 数（发送给 LLM 的完整上下文消耗的 token）。
usage.completionTokens int 输出 token 数（LLM 生成的回复消耗的 token）。
usage.totalTokens int 总 token 数。
latencyMs long 本次 LLM 请求的端到端延迟（毫秒）。
metadata object 额外元数据。chat/complete 响应中会包含模型选择辅助字段：requestedLlmConfigId（原始目标 LLM 配置 ID）、fallbackApplied（是否从首选配置切换到备用配置）；实际使用的 LLM 配置 ID 见顶层 llmConfigId。当 fallbackApplied=true 时还包含 fallbackFromLlmConfigId（原配置 ID）、fallbackReason（原配置调用失败原因）、fallbackStatusCode（原配置调用失败状态码）

9. ToolCall

字段 类型 说明
id string 唯一的工具调用 ID（如 call_abc123），应用层执行工具后需将结果以相同 toolCallId 追加为 tool_result 消息，LLM 据此关联调用与结果。
type string 固定为 "function"。
function.name string 要调用的函数/工具名称。
function.arguments string 调用参数，JSON 格式字符串。
index int 流式响应中的调用索引（可选），用于将分块的 tool_call delta 拼接为完整调用。

10. SummaryResult

字段 类型 说明
sessionId string 所属会话 ID。
generated bool 是否实际生成了摘要。为 false 时表示本次没有可压缩的 raw 历史或无需生成，可查看 reason 了解原因。
reason string 未生成摘要的原因说明（generated=true 时为空）。
trigger string 触发方式：

  • "manual"：用户手动调用摘要 API。

  • "auto"：/chat/completions 主链路前置自动摘要。
summaryUpToSeqNum long 本次生成的 latest summary 覆盖边界。表示该 summary 已覆盖所有 sequenceNum <= summaryUpToSeqNum 的历史消息。
其余 MessageInfo 字段 - 生成的摘要消息本身的详情（messageId、sequenceNum、role="system"、contentType="summary"、content="摘要内容..." 等）。