Finx
点金文档中心
查看 Markdown
POST/api/agent/finx/createMcpService

创建MCP服务

为指定智能体创建一个 MCP 类型的 Finx 服务。服务创建后，其工具由远端 MCP Server 动态提供，无需再调用 createTool。

保存时会做连通性测试：后端会用传入的 mcpConfig 真实连接 MCP Server 执行一次 listTools，连不通就直接报错、服务不会被创建；需要看参数校验、连接测试、描述生成、持久化各阶段进度时，可用流式版本 /createMcpService/stream。

与凭证管理的分工：平台统一凭证直接写在 mcpConfig.auth 里；若要求每个用户用自己的凭证，则在 auth 里只声明字段名、值留空并置 requireUserProvided=true，用户后续通过 getAuthSchema + saveAuthCredential 各自提交。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

请求体（JSON）7 个字段

agentIdintegerrequired

智能体ID，服务创建后归属该智能体

serviceNamestringrequired

服务标识名，创建后作为 finx 命令中调用该服务的名字。必须以英文字母或下划线开头，只能包含字母、数字、下划线和连字符，长度不超过 64；在同一智能体内以及与平台全局服务之间都不能重名，重名会直接报错

displayNamestringnullable

服务中文名（前端展示用，可为空，为空时展示服务标识名），长度不超过64

logoUrlstringnullable

服务Logo URL（前端展示用，可为空），长度不超过512

descriptionstringnullable

服务描述，长度不超过 512。智能体依赖这段描述判断什么场景该调用该服务，请写清能力范围、覆盖的数据品类与适用问题场景，描述越准确调用时机越准

mcpConfigobjectrequired

MCP服务配置（JSON对象）

  • serverUrl：MCP Server 的接入地址（必填），如 https://mcp.example.com/sse
  • transportType：传输协议，可选值 SSE、STREAMABLE_HTTP，不传时默认 SSE
  • requestTimeoutSeconds：单次请求超时时间（秒），不传时默认 30
  • description：配置备注（选填，仅作记录，不影响调用）
  • auth：鉴权配置，字段说明见下方
  • testVariables：连通性测试用的临时变量值（选填），仅当配置中使用了 ${...} 占位符时才需要

保存时的行为

  • 后端会用本配置真实连接 MCP Server 执行一次 listTools，连不通会直接返回错误原因、服务不会被创建
  • 若 auth.requireUserProvided=true，创建期没有可用凭证，会跳过连通性测试，此时必须显式填写 description（autoGenerateDescription 会被忽略）

运行时变量占位符（进阶用法）

  • serverUrl、auth.credential、auth.customHeaders 的值、auth.queryParams 的值支持 ${ctx.xxx}（发起运行时由调用方传入）与 ${sys.xxx}（系统注入，如 ${sys.agentId}）
  • 使用了占位符时，请在 testVariables 中给出本次连通性测试用的值，key 需带命名空间前缀，如 {"ctx.union_id":"u-123"}；该值只用于保存时的测试，运行时取真实上下文值

完整示例

  • 无鉴权：{"serverUrl":"https://mcp.example.com/sse","transportType":"SSE","requestTimeoutSeconds":30}
  • 平台统一 Bearer 凭证：{"serverUrl":"https://mcp.example.com/mcp","transportType":"STREAMABLE_HTTP","requestTimeoutSeconds":30,"auth":{"type":"BEARER","credential":"my-token"}}
  • 用户各自提供凭证：{"serverUrl":"https://mcp.example.com/sse","transportType":"SSE","auth":{"type":"CUSTOM","customHeaders":{"X-App-Secret":""},"requireUserProvided":true}}

auth（鉴权配置，选填。不传或 type=NONE 表示该服务无需鉴权）

  • type：鉴权类型。请求侧键名是 type；响应侧（getServiceDetail、getAuthSchema）回显时叫 authType，两者不要混用。可选值：
    • NONE：无需认证
    • API_KEY：API 密钥放在请求头
    • BEARER：Bearer 令牌
    • BASIC：HTTP Basic 认证
    • CUSTOM：一个或多个自定义请求头
    • CUSTOM_HTTP_TOKEN：先调用一个 HTTP 接口动态换取令牌
    • OAUTH：OAuth 2.1 按用户授权（平台预置数据源专用，见下文）
  • headerName：API_KEY 使用的请求头名，不传时默认 X-API-Key
  • tokenPrefix：BEARER 使用的令牌前缀，不传时默认 Bearer（BASIC 固定使用 Basic，此字段对它无效）
  • credential：主凭证值，API_KEY / BEARER / BASIC 使用。BEARER 只填令牌本身、不要带 Bearer 前缀；BASIC 填 base64(用户名:密码) 的结果
  • customHeaders：自定义请求头键值对，CUSTOM 使用，运行时按原样作为请求头发送
  • queryParams：URL 查询参数键值对，可与任意 type 叠加，运行时拼接到请求 URL 上（如 ?apiKey=xxx）
  • requireUserProvided：凭证由谁提供，不传时默认 false
    • false（平台统一凭证）：在 auth 里直接写真实凭证值，该服务的所有用户共用这一份凭证
    • true（用户各自提供）：auth 只作为模板，仅声明字段名、凭证值留空串；每个用户后续通过 saveAuthCredential 提交自己的凭证
  • tokenFetchConfig：动态换取令牌的配置，仅 type=CUSTOM_HTTP_TOKEN 时需要，子字段：
    • method：换取令牌的请求方法，不传时默认 POST
    • url：换取令牌的接口地址（必填）
    • headers：换取令牌时携带的请求头，客户端凭证放在这里（如 {"Authorization":"Basic xxx"}）
    • body：换取令牌的请求体字符串（如 grant_type=client_credentials）
    • tokenField：从响应 JSON 中取令牌的字段名，不传时默认 access_token
    • expiresInField：从响应 JSON 中取有效期（秒）的字段名，不传时默认 expires_in
    • targetHeaderName：把令牌注入业务请求时使用的请求头名，不传时默认 Authorization
    • targetTokenPrefix：注入令牌时使用的前缀，不传时默认 Bearer
    • refreshBufferSeconds：在令牌到期前多少秒主动刷新，不传时默认 60

各 type 的 auth 写法示例

  • NONE：{"type":"NONE"}
  • API_KEY（默认请求头 X-API-Key）：{"type":"API_KEY","credential":"sk-abcdef123456"}
  • API_KEY（自定义请求头名）：{"type":"API_KEY","headerName":"X-Custom-Key","credential":"sk-abcdef123456"}
  • BEARER：{"type":"BEARER","credential":"eyJhbGciOiJIUzI1NiJ9.payload.sig"}
  • BASIC：{"type":"BASIC","credential":"dXNlcjpwYXNz"}（dXNlcjpwYXNz 即 base64 编码后的 user:pass）
  • CUSTOM（多个自定义头）：{"type":"CUSTOM","customHeaders":{"X-App-Id":"123","X-App-Secret":"abc"}}
  • CUSTOM_HTTP_TOKEN：{"type":"CUSTOM_HTTP_TOKEN","tokenFetchConfig":{"method":"POST","url":"https://auth.example.com/oauth2/token","headers":{"Authorization":"Basic dXNlcjpwYXNz","Content-Type":"application/x-www-form-urlencoded"},"body":"grant_type=client_credentials","tokenField":"access_token","expiresInField":"expires_in","targetHeaderName":"Authorization","targetTokenPrefix":"Bearer","refreshBufferSeconds":60}}
  • 用户各自提供凭证（只声明字段名、值留空）：{"type":"CUSTOM","customHeaders":{"X-App-Secret":""},"requireUserProvided":true}
  • 鉴权信息放 URL 参数（与 BEARER 叠加）：{"type":"BEARER","credential":"my-token","queryParams":{"appId":"123"}}
  • OAUTH：仅用于平台预置的「按用户授权」数据源，需平台侧先完成 OAuth 客户端注册，通过本接口自助创建服务时暂不支持自行配置，如有此类需求请联系平台

凭证安全

  • credential、customHeaders 与 queryParams 的值落库前会加密存储；getServiceDetail 只回显含 *** 的脱敏值，不会返回明文
  • 编辑服务时把脱敏值原样回传即表示「保留原值」，星号不会被写入库；要真正修改就传新的明文值
autoGenerateDescriptionbooleannullable

是否自动生成服务描述，不传时默认 false。开启后系统会连接 MCP Server 获取工具列表，再调用大模型生成概括性描述并覆盖 description。注意：当 mcpConfig.auth.requireUserProvided=true（用户各自提供凭证）时，创建期无凭证可连接，本开关会被忽略，此时必须自行填写 description

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

dataintegernullable

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/updateMcpService

编辑MCP服务

编辑指定 MCP 类型 Finx 服务的配置（名称、展示名、Logo、描述、mcpConfig）。

更新语义：mcpConfig 中除 auth 以外的字段全量覆盖原配置；auth 与库中原配置按合并语义处理（未修改的凭证由后端用库中真实值回填，详见 mcpConfig 参数说明）。允许修改 serviceName 并会做唯一性校验（排除自身）。

保存时会做连通性测试：后端会对合并后的真实配置执行一次 listTools，失败直接报错、修改不生效。

建议做法：先调用 getServiceDetail 拿到当前完整配置（凭证为脱敏值），在其上修改后整体回传；未修改的凭证字段保留脱敏值原样回传即可，星号不会被写入库。用户各自的凭证仍由 saveAuthCredential 独立管理。

请求参数

请求体（JSON）7 个字段

agentIdintegerrequired

智能体ID，需与该服务归属的智能体一致，否则报错

idintegerrequired

服务ID，由 listServices / getServiceDetail 返回；必须是 MCP 类型服务的 ID，类型不匹配会报错

serviceNamestringrequired

服务标识名，创建后作为 finx 命令中调用该服务的名字。必须以英文字母或下划线开头，只能包含字母、数字、下划线和连字符，长度不超过 64；在同一智能体内以及与平台全局服务之间都不能重名，重名会直接报错。允许修改，会做唯一性校验（排除自身）

displayNamestringnullable

服务中文名（前端展示用，可为空，为空时展示服务标识名），长度不超过64

logoUrlstringnullable

服务Logo URL（前端展示用，可为空），长度不超过512

descriptionstringnullable

服务描述，长度不超过 512。智能体依赖这段描述判断什么场景该调用该服务，请写清能力范围、覆盖的数据品类与适用问题场景，描述越准确调用时机越准

mcpConfigobjectrequired

除 auth 外的字段整体覆盖原配置，auth 按下方合并语义处理。建议先调用 getServiceDetail 拿到当前完整配置，在其上修改后回传，避免字段丢失。

MCP服务配置（JSON对象）

  • serverUrl：MCP Server 的接入地址（必填），如 https://mcp.example.com/sse
  • transportType：传输协议，可选值 SSE、STREAMABLE_HTTP，不传时默认 SSE
  • requestTimeoutSeconds：单次请求超时时间（秒），不传时默认 30
  • description：配置备注（选填，仅作记录，不影响调用）
  • auth：鉴权配置，字段说明见下方
  • testVariables：连通性测试用的临时变量值（选填），仅当配置中使用了 ${...} 占位符时才需要

保存时的行为

  • 后端会用本配置真实连接 MCP Server 执行一次 listTools，连不通会直接返回错误原因、服务不会被创建
  • 若 auth.requireUserProvided=true，创建期没有可用凭证，会跳过连通性测试，此时必须显式填写 description（autoGenerateDescription 会被忽略）

运行时变量占位符（进阶用法）

  • serverUrl、auth.credential、auth.customHeaders 的值、auth.queryParams 的值支持 ${ctx.xxx}（发起运行时由调用方传入）与 ${sys.xxx}（系统注入，如 ${sys.agentId}）
  • 使用了占位符时，请在 testVariables 中给出本次连通性测试用的值，key 需带命名空间前缀，如 {"ctx.union_id":"u-123"}；该值只用于保存时的测试，运行时取真实上下文值

完整示例

  • 无鉴权：{"serverUrl":"https://mcp.example.com/sse","transportType":"SSE","requestTimeoutSeconds":30}
  • 平台统一 Bearer 凭证：{"serverUrl":"https://mcp.example.com/mcp","transportType":"STREAMABLE_HTTP","requestTimeoutSeconds":30,"auth":{"type":"BEARER","credential":"my-token"}}
  • 用户各自提供凭证：{"serverUrl":"https://mcp.example.com/sse","transportType":"SSE","auth":{"type":"CUSTOM","customHeaders":{"X-App-Secret":""},"requireUserProvided":true}}

auth（鉴权配置，选填。不传或 type=NONE 表示该服务无需鉴权）

  • type：鉴权类型。请求侧键名是 type；响应侧（getServiceDetail、getAuthSchema）回显时叫 authType，两者不要混用。可选值：
    • NONE：无需认证
    • API_KEY：API 密钥放在请求头
    • BEARER：Bearer 令牌
    • BASIC：HTTP Basic 认证
    • CUSTOM：一个或多个自定义请求头
    • CUSTOM_HTTP_TOKEN：先调用一个 HTTP 接口动态换取令牌
    • OAUTH：OAuth 2.1 按用户授权（平台预置数据源专用，见下文）
  • headerName：API_KEY 使用的请求头名，不传时默认 X-API-Key
  • tokenPrefix：BEARER 使用的令牌前缀，不传时默认 Bearer（BASIC 固定使用 Basic，此字段对它无效）
  • credential：主凭证值，API_KEY / BEARER / BASIC 使用。BEARER 只填令牌本身、不要带 Bearer 前缀；BASIC 填 base64(用户名:密码) 的结果
  • customHeaders：自定义请求头键值对，CUSTOM 使用，运行时按原样作为请求头发送
  • queryParams：URL 查询参数键值对，可与任意 type 叠加，运行时拼接到请求 URL 上（如 ?apiKey=xxx）
  • requireUserProvided：凭证由谁提供，不传时默认 false
    • false（平台统一凭证）：在 auth 里直接写真实凭证值，该服务的所有用户共用这一份凭证
    • true（用户各自提供）：auth 只作为模板，仅声明字段名、凭证值留空串；每个用户后续通过 saveAuthCredential 提交自己的凭证
  • tokenFetchConfig：动态换取令牌的配置，仅 type=CUSTOM_HTTP_TOKEN 时需要，子字段：
    • method：换取令牌的请求方法，不传时默认 POST
    • url：换取令牌的接口地址（必填）
    • headers：换取令牌时携带的请求头，客户端凭证放在这里（如 {"Authorization":"Basic xxx"}）
    • body：换取令牌的请求体字符串（如 grant_type=client_credentials）
    • tokenField：从响应 JSON 中取令牌的字段名，不传时默认 access_token
    • expiresInField：从响应 JSON 中取有效期（秒）的字段名，不传时默认 expires_in
    • targetHeaderName：把令牌注入业务请求时使用的请求头名，不传时默认 Authorization
    • targetTokenPrefix：注入令牌时使用的前缀，不传时默认 Bearer
    • refreshBufferSeconds：在令牌到期前多少秒主动刷新，不传时默认 60

各 type 的 auth 写法示例

  • NONE：{"type":"NONE"}
  • API_KEY（默认请求头 X-API-Key）：{"type":"API_KEY","credential":"sk-abcdef123456"}
  • API_KEY（自定义请求头名）：{"type":"API_KEY","headerName":"X-Custom-Key","credential":"sk-abcdef123456"}
  • BEARER：{"type":"BEARER","credential":"eyJhbGciOiJIUzI1NiJ9.payload.sig"}
  • BASIC：{"type":"BASIC","credential":"dXNlcjpwYXNz"}（dXNlcjpwYXNz 即 base64 编码后的 user:pass）
  • CUSTOM（多个自定义头）：{"type":"CUSTOM","customHeaders":{"X-App-Id":"123","X-App-Secret":"abc"}}
  • CUSTOM_HTTP_TOKEN：{"type":"CUSTOM_HTTP_TOKEN","tokenFetchConfig":{"method":"POST","url":"https://auth.example.com/oauth2/token","headers":{"Authorization":"Basic dXNlcjpwYXNz","Content-Type":"application/x-www-form-urlencoded"},"body":"grant_type=client_credentials","tokenField":"access_token","expiresInField":"expires_in","targetHeaderName":"Authorization","targetTokenPrefix":"Bearer","refreshBufferSeconds":60}}
  • 用户各自提供凭证（只声明字段名、值留空）：{"type":"CUSTOM","customHeaders":{"X-App-Secret":""},"requireUserProvided":true}
  • 鉴权信息放 URL 参数（与 BEARER 叠加）：{"type":"BEARER","credential":"my-token","queryParams":{"appId":"123"}}
  • OAUTH：仅用于平台预置的「按用户授权」数据源，需平台侧先完成 OAuth 客户端注册，通过本接口自助创建服务时暂不支持自行配置，如有此类需求请联系平台

凭证安全

  • credential、customHeaders 与 queryParams 的值落库前会加密存储；getServiceDetail 只回显含 *** 的脱敏值，不会返回明文
  • 编辑服务时把脱敏值原样回传即表示「保留原值」，星号不会被写入库；要真正修改就传新的明文值

编辑时 auth 的合并语义（本接口特有）

  • 整个 auth 不传：完整保留原鉴权配置
  • auth.type=NONE：明确清除鉴权配置
  • credential：不传或传脱敏值（含 ***）= 保留原值；传新的明文 = 替换；传空字符串 = 明确清空
  • customHeaders / queryParams：请求中出现的 key 集合即最终保留的集合，原有 key 未出现即被删除；某个 key 的值不传或传脱敏值 = 保留该 key 原值，传空字符串 = 清空
  • customHeaderKeys / queryParamKeys（字符串数组，选填）：用于「只修改其中一个 key」的场景声明最终 key 集合。key 在数组内但不在 customHeaders / queryParams 中 = 保留原值；key 不在数组内 = 删除。之所以需要这两个字段，是因为多数客户端的 JSON 序列化会丢弃 null 值，无法用 {"key":null} 表达「保留原值」。不传数组时按上一条语义处理
  • headerName / tokenPrefix / requireUserProvided / tokenFetchConfig：不传时保留原值
  • 示例（只改 X-App-Secret，保留 X-App-Id 原值，并删除原有的其他自定义头）：{"type":"CUSTOM","customHeaders":{"X-App-Secret":"new-secret"},"customHeaderKeys":["X-App-Id","X-App-Secret"]}

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

dataobjectnullable

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/importMcpService

通过JSON导入MCP服务

支持标准MCP JSON格式导入服务（type支持sse、streamable-http），每次仅支持导入一个服务，mcpServers下只能有一个entry。注意：mcpServers字段必须是JSON对象而非字符串，且不要重复嵌套mcpServers层级，直接传标准MCP JSON中 mcpServers 键对应的值即可。完整请求体示例：{"agentId":123,"mcpServers":{"context7-mcp":{"type":"sse","url":"https://mcp.example.com/sse"}}}。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

请求体（JSON）3 个字段

agentIdintegerrequired

智能体ID，服务导入后归属该智能体

mcpServersobjectrequired

MCP服务配置（JSON对象，非字符串）。key为服务名称，value为该服务的配置对象，且只能包含一个服务。

常见错误提示：

  • 该字段必须传JSON对象，不要将其序列化为字符串后传入
  • 不要再包裹一层 mcpServers，请直接传标准MCP JSON中 mcpServers 键对应的值

服务配置项：

  • url：MCP服务器地址（必填）
  • type：传输协议类型（选填），可选值：sse、streamable-http；不传时默认按 streamable-http 尝试，且因协议不匹配连接失败时会自动换另一种协议重试；显式传入时不做自动重试
  • headers：自定义请求头（JSON对象，选填）

导入时的行为

  • 后端会先连接该 MCP Server 拉取工具列表，连不通直接报错、服务不会被创建
  • key 不符合服务标识名规则（字母/下划线开头，仅含字母、数字、下划线、连字符）时，系统会自动生成合规的服务标识名与中文展示名
  • 服务描述由系统根据工具列表自动生成

headers 会被自动识别为鉴权配置

  • 不传或为空对象：识别为无需鉴权（NONE）
  • Authorization: Bearer <令牌>：识别为 BEARER，令牌自动去掉 Bearer 前缀后存为凭证
  • Authorization: Basic <凭证>：识别为 BASIC
  • 其他任意请求头：识别为 CUSTOM，所有 header 原样存为自定义请求头
  • 导入后如需调整鉴权方式（例如改为「用户各自提供凭证」），请再调用 updateMcpService 编辑
autoGenerateDescriptionbooleannullable

保留字段，不传时默认 false。导入场景下服务描述始终由系统根据工具列表自动生成，本开关不影响结果

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

dataintegernullable

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/createHttpService

创建HTTP服务

为指定智能体创建一个 HTTP 类型的 Finx 服务，用于把现有 REST 接口接入为智能体可调用的工具。

接入步骤：先用本接口创建服务（配置 baseUrl 与服务级鉴权），再用 createTool 为每个接口创建一个工具（工具默认继承服务级鉴权）；仅当服务本身就是一个可调用接口时，才需要在 httpConfig.serviceEndpoint 里直接配置端点。

注意：本接口不会做连通性测试（与 MCP 服务不同），保存成功不代表地址与凭证可用，建议随后用 execute 接口实际调用一次验证。

与凭证管理的分工：平台统一凭证直接写在 httpConfig.auth 里；若要求每个用户用自己的凭证，则在 auth 里只声明字段名、值留空并置 requireUserProvided=true，用户后续通过 getAuthSchema + saveAuthCredential 各自提交。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

请求体（JSON）7 个字段

agentIdintegerrequired

智能体ID，服务创建后归属该智能体

serviceNamestringrequired

服务标识名，创建后作为 finx 命令中调用该服务的名字。必须以英文字母或下划线开头，只能包含字母、数字、下划线和连字符，长度不超过 64；在同一智能体内以及与平台全局服务之间都不能重名，重名会直接报错

displayNamestringnullable

服务中文名（前端展示用，可为空，为空时展示服务标识名），长度不超过64

logoUrlstringnullable

服务Logo URL（前端展示用，可为空），长度不超过512

descriptionstringnullable

服务描述，长度不超过 512。智能体依赖这段描述判断什么场景该调用该服务，请写清能力范围、覆盖的数据品类与适用问题场景，描述越准确调用时机越准

parameterSchemastringnullable

参数Schema（JSON字符串，不是JSON对象）

  • 内容为标准 JSON Schema，需作为字符串传递（注意转义内部的双引号）；保存时会做合法性校验，不合法直接报错
  • 作用：告诉智能体调用该接口时要传哪些参数。每个属性的 description 直接影响模型选参的准确度，务必写清楚含义与取值示例
  • HTTP 类型的工具 / serviceEndpoint 建议填写；MCP 类型不需要（工具入参由 MCP Server 动态提供）
  • Schema 内容示例：{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"自然语言查询，如：宁德时代最新研报"},"limit":{"type":"integer","description":"返回条数，默认10"}}}
  • 本字段描述的是 httpConfig.serviceEndpoint 的入参，仅在配置了 serviceEndpoint 时有意义；服务下各工具的入参在 createTool 时单独定义
httpConfigobjectrequired

HTTP服务配置（JSON对象）

  • baseUrl：服务基础地址（必填），与工具的 path 拼接成最终请求地址，如 https://api.example.com + /api/data/query
  • auth：服务级鉴权配置，字段说明见下方；该服务下的工具默认继承服务级鉴权（工具端点的 inheritAuth 默认 true）
  • serviceEndpoint：服务自身可直接调用的端点（选填）。只有「服务本身就是一个可调用接口」时才填；若该服务有多个接口，请把每个接口作为一个工具用 createTool 单独创建

保存时的行为

  • 与 MCP 不同，创建/编辑 HTTP 服务不会发起连通性测试，保存成功不代表地址与凭证可用，建议随后用 execute 接口实际调用一次验证
  • parameterSchema 若传了，会做 JSON Schema 合法性校验，不合法直接报错

完整示例

  • 仅服务级配置（各接口另行用 createTool 创建）：{"baseUrl":"https://api.example.com","auth":{"type":"CUSTOM","customHeaders":{"em_api_key":"xxx"}}}
  • 服务本身即一个端点：{"baseUrl":"https://api.example.com","auth":{"type":"BEARER","credential":"my-token"},"serviceEndpoint":{"method":"POST","path":"/api/query","contentType":"application/json","timeout":30000}}
  • 服务端点为 SSE 流式：{"baseUrl":"https://api.example.com","serviceEndpoint":{"method":"POST","path":"/api/chat/stream","contentType":"application/json","streaming":true,"resultEventName":"tool_observation"}}

serviceEndpoint 的字段说明

  • method：HTTP 方法（必填），如 GET / POST / PUT / DELETE
  • path：相对 baseUrl 的请求路径（必填），支持 {变量} 占位，如 /api/stock/{symbol}
  • contentType：请求体 Content-Type（选填），如 application/json
  • timeout：超时时间（毫秒，选填），不传时使用服务默认值
  • queryParams：字段名数组（选填），声明哪些入参通过 URL 查询参数传递，未声明的入参走请求体
  • inheritAuth：是否继承服务级鉴权（选填，默认 true）
  • auth：端点级鉴权（选填），仅当 inheritAuth=false、该接口使用独立凭证时才需要，字段说明见下方
  • streaming：是否以 SSE（text/event-stream）方式消费该端点（选填，默认 false）
  • resultEventName：SSE 流中作为「模型观察结果」的保留事件名（选填，默认 tool_observation）。streaming=true 时，中间帧实时透传给终端界面，只有该事件名对应帧的 data 会作为模型观察结果；流中没有该事件时回退取最后一帧

端点示例

  • 普通 JSON 接口：{"method":"POST","path":"/api/data/query","contentType":"application/json","timeout":30000,"queryParams":["page","size"]}
  • GET 接口（参数走 URL）：{"method":"GET","path":"/api/stock/{symbol}","queryParams":["period"]}
  • SSE 流式接口：{"method":"POST","path":"/api/chat/stream","contentType":"application/json","streaming":true,"resultEventName":"tool_observation"}

auth（鉴权配置，选填。不传或 type=NONE 表示该服务无需鉴权）

  • type：鉴权类型。请求侧键名是 type；响应侧（getServiceDetail、getAuthSchema）回显时叫 authType，两者不要混用。可选值：
    • NONE：无需认证
    • API_KEY：API 密钥放在请求头
    • BEARER：Bearer 令牌
    • BASIC：HTTP Basic 认证
    • CUSTOM：一个或多个自定义请求头
    • CUSTOM_HTTP_TOKEN：先调用一个 HTTP 接口动态换取令牌
    • OAUTH：OAuth 2.1 按用户授权（平台预置数据源专用，见下文）
  • headerName：API_KEY 使用的请求头名，不传时默认 X-API-Key
  • tokenPrefix：BEARER 使用的令牌前缀，不传时默认 Bearer（BASIC 固定使用 Basic，此字段对它无效）
  • credential：主凭证值，API_KEY / BEARER / BASIC 使用。BEARER 只填令牌本身、不要带 Bearer 前缀；BASIC 填 base64(用户名:密码) 的结果
  • customHeaders：自定义请求头键值对，CUSTOM 使用，运行时按原样作为请求头发送
  • queryParams：URL 查询参数键值对，可与任意 type 叠加，运行时拼接到请求 URL 上（如 ?apiKey=xxx）
  • requireUserProvided：凭证由谁提供，不传时默认 false
    • false（平台统一凭证）：在 auth 里直接写真实凭证值，该服务的所有用户共用这一份凭证
    • true（用户各自提供）：auth 只作为模板，仅声明字段名、凭证值留空串；每个用户后续通过 saveAuthCredential 提交自己的凭证
  • tokenFetchConfig：动态换取令牌的配置，仅 type=CUSTOM_HTTP_TOKEN 时需要，子字段：
    • method：换取令牌的请求方法，不传时默认 POST
    • url：换取令牌的接口地址（必填）
    • headers：换取令牌时携带的请求头，客户端凭证放在这里（如 {"Authorization":"Basic xxx"}）
    • body：换取令牌的请求体字符串（如 grant_type=client_credentials）
    • tokenField：从响应 JSON 中取令牌的字段名，不传时默认 access_token
    • expiresInField：从响应 JSON 中取有效期（秒）的字段名，不传时默认 expires_in
    • targetHeaderName：把令牌注入业务请求时使用的请求头名，不传时默认 Authorization
    • targetTokenPrefix：注入令牌时使用的前缀，不传时默认 Bearer
    • refreshBufferSeconds：在令牌到期前多少秒主动刷新，不传时默认 60

各 type 的 auth 写法示例

  • NONE：{"type":"NONE"}
  • API_KEY（默认请求头 X-API-Key）：{"type":"API_KEY","credential":"sk-abcdef123456"}
  • API_KEY（自定义请求头名）：{"type":"API_KEY","headerName":"X-Custom-Key","credential":"sk-abcdef123456"}
  • BEARER：{"type":"BEARER","credential":"eyJhbGciOiJIUzI1NiJ9.payload.sig"}
  • BASIC：{"type":"BASIC","credential":"dXNlcjpwYXNz"}（dXNlcjpwYXNz 即 base64 编码后的 user:pass）
  • CUSTOM（多个自定义头）：{"type":"CUSTOM","customHeaders":{"X-App-Id":"123","X-App-Secret":"abc"}}
  • CUSTOM_HTTP_TOKEN：{"type":"CUSTOM_HTTP_TOKEN","tokenFetchConfig":{"method":"POST","url":"https://auth.example.com/oauth2/token","headers":{"Authorization":"Basic dXNlcjpwYXNz","Content-Type":"application/x-www-form-urlencoded"},"body":"grant_type=client_credentials","tokenField":"access_token","expiresInField":"expires_in","targetHeaderName":"Authorization","targetTokenPrefix":"Bearer","refreshBufferSeconds":60}}
  • 用户各自提供凭证（只声明字段名、值留空）：{"type":"CUSTOM","customHeaders":{"X-App-Secret":""},"requireUserProvided":true}
  • 鉴权信息放 URL 参数（与 BEARER 叠加）：{"type":"BEARER","credential":"my-token","queryParams":{"appId":"123"}}
  • OAUTH：仅用于平台预置的「按用户授权」数据源，需平台侧先完成 OAuth 客户端注册，通过本接口自助创建服务时暂不支持自行配置，如有此类需求请联系平台

凭证安全

  • credential、customHeaders 与 queryParams 的值落库前会加密存储；getServiceDetail 只回显含 *** 的脱敏值，不会返回明文
  • 编辑服务时把脱敏值原样回传即表示「保留原值」，星号不会被写入库；要真正修改就传新的明文值

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

dataintegernullable

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/updateHttpService

编辑HTTP服务

全量替换指定 HTTP 类型 Finx 服务的配置（名称、展示名、Logo、描述、parameterSchema、httpConfig）。允许修改 serviceName 并会做唯一性校验（排除自身）。

更新语义：httpConfig 整体覆盖原配置，auth 也按请求内容整体保存；值为脱敏形式（含 ***）的凭证字段会自动回填库中原值，星号不会落库。因此建议先调用 getServiceDetail 拿到当前完整配置（含 httpConfig.serviceEndpoint），在其上修改后回传，避免字段丢失。

注意：本接口不会做连通性测试；且切勿传入 MCP 服务 ID，后端会按服务类型校验，类型不匹配直接报错。用户各自的凭证仍由 saveAuthCredential 独立管理。

请求参数

请求体（JSON）8 个字段

agentIdintegerrequired

智能体ID，需与该服务归属的智能体一致，否则报错

idintegerrequired

服务ID，由 listServices / getServiceDetail 返回；必须是 HTTP 类型服务的 ID，传入 MCP 服务 ID 会因类型不匹配直接报错

serviceNamestringrequired

服务标识名，创建后作为 finx 命令中调用该服务的名字。必须以英文字母或下划线开头，只能包含字母、数字、下划线和连字符，长度不超过 64；在同一智能体内以及与平台全局服务之间都不能重名，重名会直接报错。允许修改，会做唯一性校验（排除自身）

displayNamestringnullable

服务中文名（前端展示用，可为空，为空时展示服务标识名），长度不超过64

logoUrlstringnullable

服务Logo URL（前端展示用，可为空），长度不超过512

descriptionstringnullable

服务描述，长度不超过 512。智能体依赖这段描述判断什么场景该调用该服务，请写清能力范围、覆盖的数据品类与适用问题场景，描述越准确调用时机越准

parameterSchemastringnullable

参数Schema（JSON字符串，不是JSON对象）

  • 内容为标准 JSON Schema，需作为字符串传递（注意转义内部的双引号）；保存时会做合法性校验，不合法直接报错
  • 作用：告诉智能体调用该接口时要传哪些参数。每个属性的 description 直接影响模型选参的准确度，务必写清楚含义与取值示例
  • HTTP 类型的工具 / serviceEndpoint 建议填写；MCP 类型不需要（工具入参由 MCP Server 动态提供）
  • Schema 内容示例：{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"自然语言查询，如：宁德时代最新研报"},"limit":{"type":"integer","description":"返回条数，默认10"}}}
  • 本字段描述的是 httpConfig.serviceEndpoint 的入参，仅在配置了 serviceEndpoint 时有意义；服务下各工具的入参用 updateTool 单独维护
httpConfigobjectrequired

整体覆盖原配置。建议先调用 getServiceDetail 拿到当前完整配置（含 serviceEndpoint），在其上修改后回传，避免字段丢失。

HTTP服务配置（JSON对象）

  • baseUrl：服务基础地址（必填），与工具的 path 拼接成最终请求地址，如 https://api.example.com + /api/data/query
  • auth：服务级鉴权配置，字段说明见下方；该服务下的工具默认继承服务级鉴权（工具端点的 inheritAuth 默认 true）
  • serviceEndpoint：服务自身可直接调用的端点（选填）。只有「服务本身就是一个可调用接口」时才填；若该服务有多个接口，请把每个接口作为一个工具用 createTool 单独创建

保存时的行为

  • 与 MCP 不同，创建/编辑 HTTP 服务不会发起连通性测试，保存成功不代表地址与凭证可用，建议随后用 execute 接口实际调用一次验证
  • parameterSchema 若传了，会做 JSON Schema 合法性校验，不合法直接报错

完整示例

  • 仅服务级配置（各接口另行用 createTool 创建）：{"baseUrl":"https://api.example.com","auth":{"type":"CUSTOM","customHeaders":{"em_api_key":"xxx"}}}
  • 服务本身即一个端点：{"baseUrl":"https://api.example.com","auth":{"type":"BEARER","credential":"my-token"},"serviceEndpoint":{"method":"POST","path":"/api/query","contentType":"application/json","timeout":30000}}
  • 服务端点为 SSE 流式：{"baseUrl":"https://api.example.com","serviceEndpoint":{"method":"POST","path":"/api/chat/stream","contentType":"application/json","streaming":true,"resultEventName":"tool_observation"}}

serviceEndpoint 的字段说明

  • method：HTTP 方法（必填），如 GET / POST / PUT / DELETE
  • path：相对 baseUrl 的请求路径（必填），支持 {变量} 占位，如 /api/stock/{symbol}
  • contentType：请求体 Content-Type（选填），如 application/json
  • timeout：超时时间（毫秒，选填），不传时使用服务默认值
  • queryParams：字段名数组（选填），声明哪些入参通过 URL 查询参数传递，未声明的入参走请求体
  • inheritAuth：是否继承服务级鉴权（选填，默认 true）
  • auth：端点级鉴权（选填），仅当 inheritAuth=false、该接口使用独立凭证时才需要，字段说明见下方
  • streaming：是否以 SSE（text/event-stream）方式消费该端点（选填，默认 false）
  • resultEventName：SSE 流中作为「模型观察结果」的保留事件名（选填，默认 tool_observation）。streaming=true 时，中间帧实时透传给终端界面，只有该事件名对应帧的 data 会作为模型观察结果；流中没有该事件时回退取最后一帧

端点示例

  • 普通 JSON 接口：{"method":"POST","path":"/api/data/query","contentType":"application/json","timeout":30000,"queryParams":["page","size"]}
  • GET 接口（参数走 URL）：{"method":"GET","path":"/api/stock/{symbol}","queryParams":["period"]}
  • SSE 流式接口：{"method":"POST","path":"/api/chat/stream","contentType":"application/json","streaming":true,"resultEventName":"tool_observation"}

auth（鉴权配置，选填。不传或 type=NONE 表示该服务无需鉴权）

  • type：鉴权类型。请求侧键名是 type；响应侧（getServiceDetail、getAuthSchema）回显时叫 authType，两者不要混用。可选值：
    • NONE：无需认证
    • API_KEY：API 密钥放在请求头
    • BEARER：Bearer 令牌
    • BASIC：HTTP Basic 认证
    • CUSTOM：一个或多个自定义请求头
    • CUSTOM_HTTP_TOKEN：先调用一个 HTTP 接口动态换取令牌
    • OAUTH：OAuth 2.1 按用户授权（平台预置数据源专用，见下文）
  • headerName：API_KEY 使用的请求头名，不传时默认 X-API-Key
  • tokenPrefix：BEARER 使用的令牌前缀，不传时默认 Bearer（BASIC 固定使用 Basic，此字段对它无效）
  • credential：主凭证值，API_KEY / BEARER / BASIC 使用。BEARER 只填令牌本身、不要带 Bearer 前缀；BASIC 填 base64(用户名:密码) 的结果
  • customHeaders：自定义请求头键值对，CUSTOM 使用，运行时按原样作为请求头发送
  • queryParams：URL 查询参数键值对，可与任意 type 叠加，运行时拼接到请求 URL 上（如 ?apiKey=xxx）
  • requireUserProvided：凭证由谁提供，不传时默认 false
    • false（平台统一凭证）：在 auth 里直接写真实凭证值，该服务的所有用户共用这一份凭证
    • true（用户各自提供）：auth 只作为模板，仅声明字段名、凭证值留空串；每个用户后续通过 saveAuthCredential 提交自己的凭证
  • tokenFetchConfig：动态换取令牌的配置，仅 type=CUSTOM_HTTP_TOKEN 时需要，子字段：
    • method：换取令牌的请求方法，不传时默认 POST
    • url：换取令牌的接口地址（必填）
    • headers：换取令牌时携带的请求头，客户端凭证放在这里（如 {"Authorization":"Basic xxx"}）
    • body：换取令牌的请求体字符串（如 grant_type=client_credentials）
    • tokenField：从响应 JSON 中取令牌的字段名，不传时默认 access_token
    • expiresInField：从响应 JSON 中取有效期（秒）的字段名，不传时默认 expires_in
    • targetHeaderName：把令牌注入业务请求时使用的请求头名，不传时默认 Authorization
    • targetTokenPrefix：注入令牌时使用的前缀，不传时默认 Bearer
    • refreshBufferSeconds：在令牌到期前多少秒主动刷新，不传时默认 60

各 type 的 auth 写法示例

  • NONE：{"type":"NONE"}
  • API_KEY（默认请求头 X-API-Key）：{"type":"API_KEY","credential":"sk-abcdef123456"}
  • API_KEY（自定义请求头名）：{"type":"API_KEY","headerName":"X-Custom-Key","credential":"sk-abcdef123456"}
  • BEARER：{"type":"BEARER","credential":"eyJhbGciOiJIUzI1NiJ9.payload.sig"}
  • BASIC：{"type":"BASIC","credential":"dXNlcjpwYXNz"}（dXNlcjpwYXNz 即 base64 编码后的 user:pass）
  • CUSTOM（多个自定义头）：{"type":"CUSTOM","customHeaders":{"X-App-Id":"123","X-App-Secret":"abc"}}
  • CUSTOM_HTTP_TOKEN：{"type":"CUSTOM_HTTP_TOKEN","tokenFetchConfig":{"method":"POST","url":"https://auth.example.com/oauth2/token","headers":{"Authorization":"Basic dXNlcjpwYXNz","Content-Type":"application/x-www-form-urlencoded"},"body":"grant_type=client_credentials","tokenField":"access_token","expiresInField":"expires_in","targetHeaderName":"Authorization","targetTokenPrefix":"Bearer","refreshBufferSeconds":60}}
  • 用户各自提供凭证（只声明字段名、值留空）：{"type":"CUSTOM","customHeaders":{"X-App-Secret":""},"requireUserProvided":true}
  • 鉴权信息放 URL 参数（与 BEARER 叠加）：{"type":"BEARER","credential":"my-token","queryParams":{"appId":"123"}}
  • OAUTH：仅用于平台预置的「按用户授权」数据源，需平台侧先完成 OAuth 客户端注册，通过本接口自助创建服务时暂不支持自行配置，如有此类需求请联系平台

凭证安全

  • credential、customHeaders 与 queryParams 的值落库前会加密存储；getServiceDetail 只回显含 *** 的脱敏值，不会返回明文
  • 编辑服务时把脱敏值原样回传即表示「保留原值」，星号不会被写入库；要真正修改就传新的明文值

编辑时 auth 的处理（本接口）

  • httpConfig 整体覆盖原配置，auth 也按请求内容整体保存：customHeaders / queryParams 的最终 key 集合完全以请求为准，未出现的 key 即被删除（本接口不支持 customHeaderKeys / queryParamKeys）
  • 唯一例外：值为脱敏形式（含 ***）的字段会自动回填库中原值，星号不会落库
  • 因此建议先调用 getServiceDetail 取到完整配置，在其上修改后整体回传，避免字段丢失

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

dataobjectnullable

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
GET/api/agent/finx/listServices

查询服务列表

查询指定智能体可用的 Finx 服务摘要列表，包含全局服务。每个服务项包含 categories（所属市场分类）和 groups（供应商分组标签）两组标签，标签含 id（稳定键，用于前端筛选/回链）和 name（展示名）；仅全局/市场服务可能有值，智能体专属服务恒为空数组。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

Query 参数1 个字段

agentIdintegerrequired

智能体ID，必填

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
GET/api/agent/finx/listMarketServices

获取市场服务

查询指定智能体可见的全部市场/全局服务，不会按启用状态过滤。agentId 必填，enabled 始终表示该智能体是否实际启用服务，与 listServices 完全一致，按白名单、黑名单、服务默认值和授权状态计算。categoryId 可选：传入则仅返回归属该分类的服务，不传则返回全部市场服务。hasAuth 反映当前用户在该智能体下是否已授权，principalId 由当前登录身份自动注入。返回每项服务含 categories（所属分类）、groups（供应商分组）两组标签及完整的 authRequired/hasAuth 授权状态。注意：本接口列表范围始终仅为市场服务，不包含该智能体的专属服务；查询某智能体全部可用服务请用 listServices。

请求参数

Query 参数2 个字段

agentIdintegerrequired

智能体ID，必填。用于计算实际 enabled 和 hasAuth，不影响列表范围（始终仅返回市场服务）

categoryIdintegernullable

分类ID，可选。传入时仅返回归属该分类的市场服务

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
GET/api/agent/finx/getServiceDetail

获取服务详情

获取单个 Finx 服务的完整详情，包括基本信息（id、name、displayName、type、enabled、toolCount等）、类型化配置（MCP服务的serverUrl/transportType/requestTimeoutSeconds，HTTP服务的baseUrl及 serviceEndpoint，serviceEndpoint 含 method/path/contentType/timeout/queryParams/streaming/resultEventName）以及授权状态（authType、是否已配置凭证、凭证字段列表含脱敏值、凭证来源等）。其中 streaming 标识服务端点是否以SSE方式连接客户端（默认false），resultEventName 为SSE流中作为模型观察结果的保留事件名（默认 tool_observation）。注意：授权状态里的字段名为 authType，而创建/编辑服务时请求体里的键名是 auth.type，回传时不要混用。凭证值均为脱敏返回，不会暴露明文；编辑服务时将脱敏值原样回传即表示保留原值。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

Query 参数2 个字段

agentIdintegerrequired

智能体ID，必填

serviceNamestringrequired

服务名称，必填

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
GET/api/agent/finx/listCategories

查询服务分类列表

查询全部可选的市场服务分类，供前端做服务筛选/回链。返回列表每项含 id（稳定键，筛选/提交时用它做值）、name（下拉框展示文案）和 description（分类描述）。分类为全局目录数据，与具体智能体无关，无需传参。

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
GET/api/agent/finx/listTools

查询工具列表

查询指定服务下的工具列表，返回工具ID（toolId，HTTP类型有值，MCP为null）、工具名称、描述、参数Schema及工具类型（type字段，值为HTTP/MCP/BUILTIN）。HTTP服务从数据库获取，MCP服务实时连接远程服务器获取。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

Query 参数2 个字段

agentIdintegerrequired

智能体ID，必填

serviceNamestringrequired

服务名称，必填

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
GET/api/agent/finx/getToolDetail

获取工具详情

获取指定工具的完整定义，包含参数Schema和调用方式信息。响应中 toolId 为工具唯一标识（HTTP类型有值，MCP为null，用于 updateTool/deleteTool 操作）；type 字段标识工具所属服务类型（HTTP/MCP/BUILTIN）；当 type=HTTP 时，httpEndpoint 字段包含HTTP端点配置（method、path、contentType、timeout、queryParams、streaming、resultEventName），其中 streaming 标识工具是否以SSE方式连接客户端端点（默认false），resultEventName 为SSE流中作为模型观察结果的保留事件名（默认 tool_observation）；其余类型该字段为null。用于工具能力预览页面渲染。身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

Query 参数3 个字段

agentIdintegerrequired

智能体ID，必填

serviceNamestringrequired

服务名称，必填

toolNamestringrequired

工具名称，必填

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/createTool

创建工具

为指定的 HTTP 类型服务创建一个工具（一个工具对应该服务下的一个可调用接口）。

仅支持 HTTP 类型服务：MCP 服务的工具由远端 MCP Server 动态提供，不能手工创建。

关键拼接规则：最终请求地址 = 服务的 httpConfig.baseUrl + 本工具 httpEndpoint.path；工具默认继承服务级鉴权（inheritAuth 默认 true），仅当该接口用独立凭证时才需在 httpEndpoint 里传 inheritAuth=false 与 auth。

入参定义：用 parameterSchema（JSON Schema 字符串）描述该接口的入参；需要走 URL 查询参数或路径变量的字段，在 httpEndpoint.queryParams 中声明，其余入参默认走请求体。

请求参数

请求体（JSON）6 个字段

agentIdintegerrequired

智能体ID，需与该服务归属的智能体一致

serviceIdintegerrequired

所属服务ID，由 listServices / getServiceDetail 返回。仅支持 HTTP 类型服务；MCP 服务的工具由远端 MCP Server 提供，不能手工创建

toolNamestringrequired

工具标识名，即 finx 命令中的工具名。必须以英文字母或下划线开头，只能包含字母、数字、下划线和连字符，长度不超过 64；同一服务内不可重名

descriptionstringnullable

工具描述。智能体依赖这段描述判断什么场景该调用该工具，请写清这个接口能做什么、何时用

parameterSchemastringnullable

参数Schema（JSON字符串，不是JSON对象）

  • 内容为标准 JSON Schema，需作为字符串传递（注意转义内部的双引号）；保存时会做合法性校验，不合法直接报错
  • 作用：告诉智能体调用该接口时要传哪些参数。每个属性的 description 直接影响模型选参的准确度，务必写清楚含义与取值示例
  • HTTP 类型的工具 / serviceEndpoint 建议填写；MCP 类型不需要（工具入参由 MCP Server 动态提供）
  • Schema 内容示例：{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"自然语言查询，如：宁德时代最新研报"},"limit":{"type":"integer","description":"返回条数，默认10"}}}
httpEndpointobjectnullable

HTTP端点配置（JSON对象，仅 HTTP 类型服务的工具需要填写）

  • 最终请求地址 = 服务的 baseUrl + 本端点的 path
  • method：HTTP 方法（必填），如 GET / POST / PUT / DELETE
  • path：相对 baseUrl 的请求路径（必填），支持 {变量} 占位，如 /api/stock/{symbol}
  • contentType：请求体 Content-Type（选填），如 application/json
  • timeout：超时时间（毫秒，选填），不传时使用服务默认值
  • queryParams：字段名数组（选填），声明哪些入参通过 URL 查询参数传递，未声明的入参走请求体
  • inheritAuth：是否继承服务级鉴权（选填，默认 true）
  • auth：端点级鉴权（选填），仅当 inheritAuth=false、该接口使用独立凭证时才需要，字段说明见下方
  • streaming：是否以 SSE（text/event-stream）方式消费该端点（选填，默认 false）
  • resultEventName：SSE 流中作为「模型观察结果」的保留事件名（选填，默认 tool_observation）。streaming=true 时，中间帧实时透传给终端界面，只有该事件名对应帧的 data 会作为模型观察结果；流中没有该事件时回退取最后一帧

端点示例

  • 普通 JSON 接口：{"method":"POST","path":"/api/data/query","contentType":"application/json","timeout":30000,"queryParams":["page","size"]}
  • GET 接口（参数走 URL）：{"method":"GET","path":"/api/stock/{symbol}","queryParams":["period"]}
  • SSE 流式接口：{"method":"POST","path":"/api/chat/stream","contentType":"application/json","streaming":true,"resultEventName":"tool_observation"}

auth（鉴权配置，选填。不传或 type=NONE 表示该服务无需鉴权）

  • type：鉴权类型。请求侧键名是 type；响应侧（getServiceDetail、getAuthSchema）回显时叫 authType，两者不要混用。可选值：
    • NONE：无需认证
    • API_KEY：API 密钥放在请求头
    • BEARER：Bearer 令牌
    • BASIC：HTTP Basic 认证
    • CUSTOM：一个或多个自定义请求头
    • CUSTOM_HTTP_TOKEN：先调用一个 HTTP 接口动态换取令牌
    • OAUTH：OAuth 2.1 按用户授权（平台预置数据源专用，见下文）
  • headerName：API_KEY 使用的请求头名，不传时默认 X-API-Key
  • tokenPrefix：BEARER 使用的令牌前缀，不传时默认 Bearer（BASIC 固定使用 Basic，此字段对它无效）
  • credential：主凭证值，API_KEY / BEARER / BASIC 使用。BEARER 只填令牌本身、不要带 Bearer 前缀；BASIC 填 base64(用户名:密码) 的结果
  • customHeaders：自定义请求头键值对，CUSTOM 使用，运行时按原样作为请求头发送
  • queryParams：URL 查询参数键值对，可与任意 type 叠加，运行时拼接到请求 URL 上（如 ?apiKey=xxx）
  • requireUserProvided：凭证由谁提供，不传时默认 false
    • false（平台统一凭证）：在 auth 里直接写真实凭证值，该服务的所有用户共用这一份凭证
    • true（用户各自提供）：auth 只作为模板，仅声明字段名、凭证值留空串；每个用户后续通过 saveAuthCredential 提交自己的凭证
  • tokenFetchConfig：动态换取令牌的配置，仅 type=CUSTOM_HTTP_TOKEN 时需要，子字段：
    • method：换取令牌的请求方法，不传时默认 POST
    • url：换取令牌的接口地址（必填）
    • headers：换取令牌时携带的请求头，客户端凭证放在这里（如 {"Authorization":"Basic xxx"}）
    • body：换取令牌的请求体字符串（如 grant_type=client_credentials）
    • tokenField：从响应 JSON 中取令牌的字段名，不传时默认 access_token
    • expiresInField：从响应 JSON 中取有效期（秒）的字段名，不传时默认 expires_in
    • targetHeaderName：把令牌注入业务请求时使用的请求头名，不传时默认 Authorization
    • targetTokenPrefix：注入令牌时使用的前缀，不传时默认 Bearer
    • refreshBufferSeconds：在令牌到期前多少秒主动刷新，不传时默认 60

各 type 的 auth 写法示例

  • NONE：{"type":"NONE"}
  • API_KEY（默认请求头 X-API-Key）：{"type":"API_KEY","credential":"sk-abcdef123456"}
  • API_KEY（自定义请求头名）：{"type":"API_KEY","headerName":"X-Custom-Key","credential":"sk-abcdef123456"}
  • BEARER：{"type":"BEARER","credential":"eyJhbGciOiJIUzI1NiJ9.payload.sig"}
  • BASIC：{"type":"BASIC","credential":"dXNlcjpwYXNz"}（dXNlcjpwYXNz 即 base64 编码后的 user:pass）
  • CUSTOM（多个自定义头）：{"type":"CUSTOM","customHeaders":{"X-App-Id":"123","X-App-Secret":"abc"}}
  • CUSTOM_HTTP_TOKEN：{"type":"CUSTOM_HTTP_TOKEN","tokenFetchConfig":{"method":"POST","url":"https://auth.example.com/oauth2/token","headers":{"Authorization":"Basic dXNlcjpwYXNz","Content-Type":"application/x-www-form-urlencoded"},"body":"grant_type=client_credentials","tokenField":"access_token","expiresInField":"expires_in","targetHeaderName":"Authorization","targetTokenPrefix":"Bearer","refreshBufferSeconds":60}}
  • 用户各自提供凭证（只声明字段名、值留空）：{"type":"CUSTOM","customHeaders":{"X-App-Secret":""},"requireUserProvided":true}
  • 鉴权信息放 URL 参数（与 BEARER 叠加）：{"type":"BEARER","credential":"my-token","queryParams":{"appId":"123"}}
  • OAUTH：仅用于平台预置的「按用户授权」数据源，需平台侧先完成 OAuth 客户端注册，通过本接口自助创建服务时暂不支持自行配置，如有此类需求请联系平台

凭证安全

  • credential、customHeaders 与 queryParams 的值落库前会加密存储；getServiceDetail 只回显含 *** 的脱敏值，不会返回明文
  • 编辑服务时把脱敏值原样回传即表示「保留原值」，星号不会被写入库；要真正修改就传新的明文值

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

dataintegernullable

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/updateTool

编辑工具

全量替换指定 HTTP 类型工具的配置（名称、描述、参数Schema、HTTP端点）。仅支持 HTTP 类型服务下的工具，MCP 工具不支持编辑。

全量替换语义：未传的字段会被清空，请先调用 getToolDetail 获取当前配置，修改后整体提交。

鉴权限制：本接口的 httpEndpoint 不支持 inheritAuth 与端点级 auth，编辑后该端点一律按「继承服务级鉴权」处理；需要端点独立凭证的场景请在 createTool 时配置。

请求参数

请求体（JSON）6 个字段

agentIdintegerrequired

智能体ID，需与该工具所属服务归属的智能体一致

toolIdintegerrequired

工具ID，由 listTools / getToolDetail 的 toolId 字段返回（HTTP 类型工具才有值）

toolNamestringrequired

工具标识名，即 finx 命令中的工具名。必须以英文字母或下划线开头，只能包含字母、数字、下划线和连字符，长度不超过 64；同一服务内不可重名

descriptionstringnullable

工具描述。智能体依赖这段描述判断什么场景该调用该工具，请写清这个接口能做什么、何时用

parameterSchemastringnullable

参数Schema（JSON字符串，不是JSON对象）

  • 内容为标准 JSON Schema，需作为字符串传递（注意转义内部的双引号）；保存时会做合法性校验，不合法直接报错
  • 作用：告诉智能体调用该接口时要传哪些参数。每个属性的 description 直接影响模型选参的准确度，务必写清楚含义与取值示例
  • HTTP 类型的工具 / serviceEndpoint 建议填写；MCP 类型不需要（工具入参由 MCP Server 动态提供）
  • Schema 内容示例：{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"自然语言查询，如：宁德时代最新研报"},"limit":{"type":"integer","description":"返回条数，默认10"}}}

HTTP端点配置（全量替换，仅 HTTP 类型服务的工具需要填写）。

  • 最终请求地址 = 服务的 baseUrl + 本端点的 path
  • 注意：本接口的端点配置不支持 inheritAuth 与端点级 auth，编辑后该端点一律按「继承服务级鉴权」处理；如需为单个接口配置独立凭证，请在 createTool 时通过 httpEndpoint 传入 inheritAuth=false 与 auth

字段说明

  • method：HTTP 方法（必填），如 GET / POST / PUT / DELETE
  • path：相对 baseUrl 的请求路径（必填），支持 {变量} 占位，如 /api/stock/{symbol}
  • contentType：请求体 Content-Type（选填），如 application/json
  • timeout：超时时间（毫秒，选填），不传时使用服务默认值
  • queryParams：字段名数组（选填），声明哪些入参通过 URL 查询参数传递，未声明的入参走请求体
  • streaming：是否以 SSE（text/event-stream）方式消费该端点（选填，默认 false）
  • resultEventName：SSE 流中作为「模型观察结果」的保留事件名（选填，默认 tool_observation）。streaming=true 时，中间帧实时透传给终端界面，只有该事件名对应帧的 data 会作为模型观察结果；流中没有该事件时回退取最后一帧

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

dataobjectnullable

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/deleteTool

删除工具

删除指定的HTTP类型工具（软删除）。仅支持HTTP类型服务下的工具，MCP工具不支持删除。

请求参数

请求体（JSON）2 个字段

agentIdintegerrequired

智能体ID

toolIdintegerrequired

工具ID

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

dataobjectnullable

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/execute

执行Finx命令

执行 Finx CLI 命令，用于调试服务与工具是否配置正确（包括地址、参数与鉴权凭证）。

命令格式：finx <服务名> <工具名> [--参数名 参数值 ...] [--body '<请求体JSON>']，命令必须以 finx 开头，不支持管道等 shell 操作符。

不确定参数时先查 --help：finx --help 列服务，finx <服务名> --help 列工具，finx <服务名> <工具名> --help 看准确入参与请求体要求。

调用样例：finx example-api search-news --body '{"query":"宁德时代最新研报"}'。

凭证缺失时：若该服务要求用户自备凭证且当前身份尚未配置，执行会失败，请先调用 getAuthSchema + saveAuthCredential 完成授权。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

请求体（JSON）2 个字段

agentIdintegernullable

智能体ID（可选）。传入时只能调用该智能体可用的服务，并使用该智能体下的凭证

commandstringrequired

Finx 命令，格式：finx <服务名> <工具名> [--参数名 参数值 ...] [--body '<请求体JSON>']

  • 参数名与该工具 parameterSchema 中声明的属性名一致；走 URL 查询参数或路径变量的用 --参数名 值，请求体参数统一放在 --body 的 JSON 里
  • 命令必须以 finx 开头，且不支持管道等 shell 操作符
  • 任意层级都可以加 --help 查看用法：
    • finx --help：列出当前可用的全部服务
    • finx <服务名> --help：列出该服务下的工具
    • finx <服务名> <工具名> --help：查看该工具的准确参数与请求体要求
  • 示例：finx eastmoney-mx search-news --body '{"query":"宁德时代最新研报","limit":10}'
  • 示例（参数走 URL）：finx market-data quote --symbol 600519 --period 1d

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

datastringnullable

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/deleteService

删除服务

删除指定的 Finx 服务，同时级联删除该服务下的所有工具。

请求参数

请求体（JSON）2 个字段

agentIdintegerrequired

智能体ID

idintegerrequired

服务ID

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

dataobjectnullable

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/toggleServiceEnabled

启用/禁用服务

切换指定 Finx 服务的启用状态，enabled=true 启用，enabled=false 禁用。

请求参数

请求体（JSON）3 个字段

agentIdintegerrequired

智能体ID

serviceNamestringnullable

服务名称

enabledbooleanrequired

是否启用，true=启用，false=禁用

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

dataobjectnullable

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/getAuthSchema

获取服务授权Schema

返回结构化的授权字段描述，前端据此渲染授权配置表单，API 调用方据此确定要提交哪些凭证字段。

与 saveAuthCredential 的对应关系：响应中的 fields[].key 就是 saveAuthCredential 的 credentials 里要填的 key，命名规则为：credential（API_KEY / BEARER / BASIC 的主凭证）、customHeaders.<请求头名>（CUSTOM）、queryParams.<参数名>（URL 参数，可与任意类型叠加）；不在该列表内的 key 会被拒绝。

其余响应说明：authType 为鉴权类型（注意：创建/编辑服务时请求体里的键名是 auth.type）；configured 表示该字段是否已配置，maskedValue 为脱敏后的当前值；guidance 为该服务的凭证获取指引（纯文本/Markdown 片段，空字符串表示无指引），建议非空时在授权表单顶部渲染；authScope=AGENT 的 agent 级授权表单同样返回该字段。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

请求体（JSON）3 个字段

agentIdintegerrequired

智能体ID

serviceNamestringrequired

服务标识名，取 listServices 返回的服务名。响应的 fields[].key 就是后续调用 saveAuthCredential 时 credentials 里要填的 key，两者必须一致，不在该列表内的 key 会被拒绝

toolNamestringnullable

工具标识名。不传（null）时查服务级授权要求（最常用）；仅当需要查看某个使用独立凭证的工具时才传工具名

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/saveAuthCredential

保存服务授权凭证

提交当前身份在指定服务/工具上的授权凭证。

调用流程：先调 getAuthSchema 拿到 authType 与 fields[]，确定本次要提交哪些 key；再调本接口提交 credentials。

增量更新：未传入的字段保留上次的值，要清空请显式传空字符串。

完成后自动校验：所有必填字段补齐后，系统会立即对凭证发起一次连通性校验（HTTP 服务发 HEAD 请求，MCP 服务执行 listTools），结果在响应的 verified / verifyMessage 中返回。

key 命名规则与各鉴权类型的提交样例见 credentials 参数说明。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

请求体（JSON）4 个字段

agentIdintegerrequired

智能体ID，凭证在该智能体下生效

serviceNamestringrequired

服务标识名，与 getAuthSchema 使用同一个值

toolNamestringnullable

工具标识名。不传（null）表示为整个服务配置凭证（服务级授权，最常用）；仅当该服务下某个工具使用独立凭证时才需要传工具名

credentialsobjectrequired

凭证键值对（key 与 getAuthSchema 返回的 fields[].key 一一对应）

调用流程

  • 先调用 getAuthSchema 获取该服务/工具的 authType 与 fields[]，确定本次需要提交哪些 key
  • 再调用本接口提交 credentials：增量更新，未传入的字段保留上次的值，要清空请显式传空字符串
  • 所有必填字段补齐后，系统会立即对凭证发起一次连通性校验（HTTP 服务发 HEAD 请求，MCP 服务执行 listTools），结果在响应的 verified / verifyMessage 中返回

key 命名规则

  • credential：API_KEY / BEARER / BASIC 的主凭证字段
  • customHeaders.<请求头名>：CUSTOM 类型的某个自定义请求头
  • queryParams.<参数名>：URL 查询参数，任意 authType 都可叠加
  • 不在 getAuthSchema 的 fields[].key 列表内的 key 会被拒绝并报错

各 authType 的 credentials 写法示例

  • API_KEY（值为 API 密钥明文，运行时按 <headerName>: <值> 注入请求头，headerName 默认 X-API-Key）：{"credential":"sk-abcdef123456"}
  • BEARER（值为令牌本身，不要带 Bearer 前缀，运行时自动注入 Authorization: Bearer <值>）：{"credential":"eyJhbGciOiJIUzI1NiJ9.payload.sig"}
  • BASIC（值为 base64(用户名:密码)，运行时自动注入 Authorization: Basic <值>）：{"credential":"dXNlcjpwYXNz"}
  • CUSTOM（服务模板声明的每个自定义请求头都要填）：{"customHeaders.X-App-Id":"123","customHeaders.X-App-Secret":"abc"}
  • CUSTOM_HTTP_TOKEN（令牌由服务的 tokenFetchConfig 在运行时自动换取，通常无需提交 credential；若模板要求填写换取令牌所需的密钥，按 getAuthSchema 返回的字段提交）：{"customHeaders.X-Client-Secret":"abc"}
  • NONE（一般无需调用本接口，仅当服务在 queryParams 上要求用户提供值时才需要）：{"queryParams.api_key":"xxx","queryParams.app_id":"123"}
  • 叠加 URL 参数（可与上述任意类型组合）：{"credential":"my-token","queryParams.app_id":"123"}

凭证安全：提交的凭证加密存储，任何查询接口都只回显含 *** 的脱敏值

响应

200

httpStatusCodeintegernullable

HTTP状态码

messagestringnullable

响应消息

响应数据

successbooleannullable

是否成功

requestIdstringnullable

上游请求ID，用于跨系统链路追踪排查问题

errCodestringnullable

上游错误码，前端可据此做特殊UI处理

查看 Markdown
POST/api/agent/finx/createMcpService/stream

创建MCP服务（流式）

与 createMcpService 功能完全相同，仅响应形式不同：以 SSE 流式推送创建进度，包含 VALIDATING / CONNECTING / GENERATING_DESCRIPTION / PERSISTING / COMPLETED / FAILED 事件。

请求体与 createMcpService 完全一致，mcpConfig、auth 鉴权配置的字段清单与样例请参考 createMcpService 的参数说明。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

请求体（JSON）7 个字段

agentIdintegerrequired

智能体ID，服务创建后归属该智能体

serviceNamestringrequired

服务标识名，创建后作为 finx 命令中调用该服务的名字。必须以英文字母或下划线开头，只能包含字母、数字、下划线和连字符，长度不超过 64；在同一智能体内以及与平台全局服务之间都不能重名，重名会直接报错

displayNamestringnullable

服务中文名（前端展示用，可为空，为空时展示服务标识名），长度不超过64

logoUrlstringnullable

服务Logo URL（前端展示用，可为空），长度不超过512

descriptionstringnullable

服务描述，长度不超过 512。智能体依赖这段描述判断什么场景该调用该服务，请写清能力范围、覆盖的数据品类与适用问题场景，描述越准确调用时机越准

mcpConfigobjectrequired

MCP服务配置（JSON对象）

  • serverUrl：MCP Server 的接入地址（必填），如 https://mcp.example.com/sse
  • transportType：传输协议，可选值 SSE、STREAMABLE_HTTP，不传时默认 SSE
  • requestTimeoutSeconds：单次请求超时时间（秒），不传时默认 30
  • description：配置备注（选填，仅作记录，不影响调用）
  • auth：鉴权配置，字段说明见下方
  • testVariables：连通性测试用的临时变量值（选填），仅当配置中使用了 ${...} 占位符时才需要

保存时的行为

  • 后端会用本配置真实连接 MCP Server 执行一次 listTools，连不通会直接返回错误原因、服务不会被创建
  • 若 auth.requireUserProvided=true，创建期没有可用凭证，会跳过连通性测试，此时必须显式填写 description（autoGenerateDescription 会被忽略）

运行时变量占位符（进阶用法）

  • serverUrl、auth.credential、auth.customHeaders 的值、auth.queryParams 的值支持 ${ctx.xxx}（发起运行时由调用方传入）与 ${sys.xxx}（系统注入，如 ${sys.agentId}）
  • 使用了占位符时，请在 testVariables 中给出本次连通性测试用的值，key 需带命名空间前缀，如 {"ctx.union_id":"u-123"}；该值只用于保存时的测试，运行时取真实上下文值

完整示例

  • 无鉴权：{"serverUrl":"https://mcp.example.com/sse","transportType":"SSE","requestTimeoutSeconds":30}
  • 平台统一 Bearer 凭证：{"serverUrl":"https://mcp.example.com/mcp","transportType":"STREAMABLE_HTTP","requestTimeoutSeconds":30,"auth":{"type":"BEARER","credential":"my-token"}}
  • 用户各自提供凭证：{"serverUrl":"https://mcp.example.com/sse","transportType":"SSE","auth":{"type":"CUSTOM","customHeaders":{"X-App-Secret":""},"requireUserProvided":true}}

auth（鉴权配置，选填。不传或 type=NONE 表示该服务无需鉴权）

  • type：鉴权类型。请求侧键名是 type；响应侧（getServiceDetail、getAuthSchema）回显时叫 authType，两者不要混用。可选值：
    • NONE：无需认证
    • API_KEY：API 密钥放在请求头
    • BEARER：Bearer 令牌
    • BASIC：HTTP Basic 认证
    • CUSTOM：一个或多个自定义请求头
    • CUSTOM_HTTP_TOKEN：先调用一个 HTTP 接口动态换取令牌
    • OAUTH：OAuth 2.1 按用户授权（平台预置数据源专用，见下文）
  • headerName：API_KEY 使用的请求头名，不传时默认 X-API-Key
  • tokenPrefix：BEARER 使用的令牌前缀，不传时默认 Bearer（BASIC 固定使用 Basic，此字段对它无效）
  • credential：主凭证值，API_KEY / BEARER / BASIC 使用。BEARER 只填令牌本身、不要带 Bearer 前缀；BASIC 填 base64(用户名:密码) 的结果
  • customHeaders：自定义请求头键值对，CUSTOM 使用，运行时按原样作为请求头发送
  • queryParams：URL 查询参数键值对，可与任意 type 叠加，运行时拼接到请求 URL 上（如 ?apiKey=xxx）
  • requireUserProvided：凭证由谁提供，不传时默认 false
    • false（平台统一凭证）：在 auth 里直接写真实凭证值，该服务的所有用户共用这一份凭证
    • true（用户各自提供）：auth 只作为模板，仅声明字段名、凭证值留空串；每个用户后续通过 saveAuthCredential 提交自己的凭证
  • tokenFetchConfig：动态换取令牌的配置，仅 type=CUSTOM_HTTP_TOKEN 时需要，子字段：
    • method：换取令牌的请求方法，不传时默认 POST
    • url：换取令牌的接口地址（必填）
    • headers：换取令牌时携带的请求头，客户端凭证放在这里（如 {"Authorization":"Basic xxx"}）
    • body：换取令牌的请求体字符串（如 grant_type=client_credentials）
    • tokenField：从响应 JSON 中取令牌的字段名，不传时默认 access_token
    • expiresInField：从响应 JSON 中取有效期（秒）的字段名，不传时默认 expires_in
    • targetHeaderName：把令牌注入业务请求时使用的请求头名，不传时默认 Authorization
    • targetTokenPrefix：注入令牌时使用的前缀，不传时默认 Bearer
    • refreshBufferSeconds：在令牌到期前多少秒主动刷新，不传时默认 60

各 type 的 auth 写法示例

  • NONE：{"type":"NONE"}
  • API_KEY（默认请求头 X-API-Key）：{"type":"API_KEY","credential":"sk-abcdef123456"}
  • API_KEY（自定义请求头名）：{"type":"API_KEY","headerName":"X-Custom-Key","credential":"sk-abcdef123456"}
  • BEARER：{"type":"BEARER","credential":"eyJhbGciOiJIUzI1NiJ9.payload.sig"}
  • BASIC：{"type":"BASIC","credential":"dXNlcjpwYXNz"}（dXNlcjpwYXNz 即 base64 编码后的 user:pass）
  • CUSTOM（多个自定义头）：{"type":"CUSTOM","customHeaders":{"X-App-Id":"123","X-App-Secret":"abc"}}
  • CUSTOM_HTTP_TOKEN：{"type":"CUSTOM_HTTP_TOKEN","tokenFetchConfig":{"method":"POST","url":"https://auth.example.com/oauth2/token","headers":{"Authorization":"Basic dXNlcjpwYXNz","Content-Type":"application/x-www-form-urlencoded"},"body":"grant_type=client_credentials","tokenField":"access_token","expiresInField":"expires_in","targetHeaderName":"Authorization","targetTokenPrefix":"Bearer","refreshBufferSeconds":60}}
  • 用户各自提供凭证（只声明字段名、值留空）：{"type":"CUSTOM","customHeaders":{"X-App-Secret":""},"requireUserProvided":true}
  • 鉴权信息放 URL 参数（与 BEARER 叠加）：{"type":"BEARER","credential":"my-token","queryParams":{"appId":"123"}}
  • OAUTH：仅用于平台预置的「按用户授权」数据源，需平台侧先完成 OAuth 客户端注册，通过本接口自助创建服务时暂不支持自行配置，如有此类需求请联系平台

凭证安全

  • credential、customHeaders 与 queryParams 的值落库前会加密存储；getServiceDetail 只回显含 *** 的脱敏值，不会返回明文
  • 编辑服务时把脱敏值原样回传即表示「保留原值」，星号不会被写入库；要真正修改就传新的明文值
autoGenerateDescriptionbooleannullable

是否自动生成服务描述，不传时默认 false。开启后系统会连接 MCP Server 获取工具列表，再调用大模型生成概括性描述并覆盖 description。注意：当 mcpConfig.auth.requireUserProvided=true（用户各自提供凭证）时，创建期无凭证可连接，本开关会被忽略，此时必须自行填写 description

查看 Markdown
POST/api/agent/finx/importMcpService/stream

导入MCP服务（流式）

与 importMcpService 功能完全相同，仅响应形式不同：以 SSE 流式推送导入进度，包含 VALIDATING / GENERATING_NAME / CONNECTING / GENERATING_DESCRIPTION / PERSISTING / COMPLETED / FAILED 事件。

请求体与 importMcpService 完全一致：mcpServers 为 JSON 对象（非字符串）且只能包含一个 entry，字段清单与 headers 到鉴权类型的映射规则请参考 importMcpService 的参数说明。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

请求体（JSON）3 个字段

agentIdintegerrequired

智能体ID，服务导入后归属该智能体

mcpServersobjectrequired

MCP服务配置（JSON对象，非字符串）。key为服务名称，value为该服务的配置对象，且只能包含一个服务。

常见错误提示：

  • 该字段必须传JSON对象，不要将其序列化为字符串后传入
  • 不要再包裹一层 mcpServers，请直接传标准MCP JSON中 mcpServers 键对应的值

服务配置项：

  • url：MCP服务器地址（必填）
  • type：传输协议类型（选填），可选值：sse、streamable-http；不传时默认按 streamable-http 尝试，且因协议不匹配连接失败时会自动换另一种协议重试；显式传入时不做自动重试
  • headers：自定义请求头（JSON对象，选填）

导入时的行为

  • 后端会先连接该 MCP Server 拉取工具列表，连不通直接报错、服务不会被创建
  • key 不符合服务标识名规则（字母/下划线开头，仅含字母、数字、下划线、连字符）时，系统会自动生成合规的服务标识名与中文展示名
  • 服务描述由系统根据工具列表自动生成

headers 会被自动识别为鉴权配置

  • 不传或为空对象：识别为无需鉴权（NONE）
  • Authorization: Bearer <令牌>：识别为 BEARER，令牌自动去掉 Bearer 前缀后存为凭证
  • Authorization: Basic <凭证>：识别为 BASIC
  • 其他任意请求头：识别为 CUSTOM，所有 header 原样存为自定义请求头
  • 导入后如需调整鉴权方式（例如改为「用户各自提供凭证」），请再调用 updateMcpService 编辑
autoGenerateDescriptionbooleannullable

保留字段，不传时默认 false。导入场景下服务描述始终由系统根据工具列表自动生成，本开关不影响结果

查看 Markdown
POST/api/agent/finx/createHttpService/stream

创建HTTP服务（流式）

与 createHttpService 功能完全相同，仅响应形式不同：以 SSE 流式推送创建进度。

请求体与 createHttpService 完全一致，httpConfig、auth 鉴权配置的字段清单与样例请参考 createHttpService 的参数说明。

身份说明：当您通过API访问本系统时，请求头中必须传递 X-Principal-Id 以标识操作主体；当您通过页面访问本系统时，无需传递。

请求参数

请求头参数1 个字段

X-Principal-Idintegernullable

身份主体ID（Long类型）。通过API访问时必须传递以标识操作主体；通过页面访问时无需传递。可通过「身份主体」模块的创建接口获取。

请求体（JSON）7 个字段

agentIdintegerrequired

智能体ID，服务创建后归属该智能体

serviceNamestringrequired

服务标识名，创建后作为 finx 命令中调用该服务的名字。必须以英文字母或下划线开头，只能包含字母、数字、下划线和连字符，长度不超过 64；在同一智能体内以及与平台全局服务之间都不能重名，重名会直接报错

displayNamestringnullable

服务中文名（前端展示用，可为空，为空时展示服务标识名），长度不超过64

logoUrlstringnullable

服务Logo URL（前端展示用，可为空），长度不超过512

descriptionstringnullable

服务描述，长度不超过 512。智能体依赖这段描述判断什么场景该调用该服务，请写清能力范围、覆盖的数据品类与适用问题场景，描述越准确调用时机越准

parameterSchemastringnullable

参数Schema（JSON字符串，不是JSON对象）

  • 内容为标准 JSON Schema，需作为字符串传递（注意转义内部的双引号）；保存时会做合法性校验，不合法直接报错
  • 作用：告诉智能体调用该接口时要传哪些参数。每个属性的 description 直接影响模型选参的准确度，务必写清楚含义与取值示例
  • HTTP 类型的工具 / serviceEndpoint 建议填写；MCP 类型不需要（工具入参由 MCP Server 动态提供）
  • Schema 内容示例：{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"自然语言查询，如：宁德时代最新研报"},"limit":{"type":"integer","description":"返回条数，默认10"}}}
  • 本字段描述的是 httpConfig.serviceEndpoint 的入参，仅在配置了 serviceEndpoint 时有意义；服务下各工具的入参在 createTool 时单独定义
httpConfigobjectrequired

HTTP服务配置（JSON对象）

  • baseUrl：服务基础地址（必填），与工具的 path 拼接成最终请求地址，如 https://api.example.com + /api/data/query
  • auth：服务级鉴权配置，字段说明见下方；该服务下的工具默认继承服务级鉴权（工具端点的 inheritAuth 默认 true）
  • serviceEndpoint：服务自身可直接调用的端点（选填）。只有「服务本身就是一个可调用接口」时才填；若该服务有多个接口，请把每个接口作为一个工具用 createTool 单独创建

保存时的行为

  • 与 MCP 不同，创建/编辑 HTTP 服务不会发起连通性测试，保存成功不代表地址与凭证可用，建议随后用 execute 接口实际调用一次验证
  • parameterSchema 若传了，会做 JSON Schema 合法性校验，不合法直接报错

完整示例

  • 仅服务级配置（各接口另行用 createTool 创建）：{"baseUrl":"https://api.example.com","auth":{"type":"CUSTOM","customHeaders":{"em_api_key":"xxx"}}}
  • 服务本身即一个端点：{"baseUrl":"https://api.example.com","auth":{"type":"BEARER","credential":"my-token"},"serviceEndpoint":{"method":"POST","path":"/api/query","contentType":"application/json","timeout":30000}}
  • 服务端点为 SSE 流式：{"baseUrl":"https://api.example.com","serviceEndpoint":{"method":"POST","path":"/api/chat/stream","contentType":"application/json","streaming":true,"resultEventName":"tool_observation"}}

serviceEndpoint 的字段说明

  • method：HTTP 方法（必填），如 GET / POST / PUT / DELETE
  • path：相对 baseUrl 的请求路径（必填），支持 {变量} 占位，如 /api/stock/{symbol}
  • contentType：请求体 Content-Type（选填），如 application/json
  • timeout：超时时间（毫秒，选填），不传时使用服务默认值
  • queryParams：字段名数组（选填），声明哪些入参通过 URL 查询参数传递，未声明的入参走请求体
  • inheritAuth：是否继承服务级鉴权（选填，默认 true）
  • auth：端点级鉴权（选填），仅当 inheritAuth=false、该接口使用独立凭证时才需要，字段说明见下方
  • streaming：是否以 SSE（text/event-stream）方式消费该端点（选填，默认 false）
  • resultEventName：SSE 流中作为「模型观察结果」的保留事件名（选填，默认 tool_observation）。streaming=true 时，中间帧实时透传给终端界面，只有该事件名对应帧的 data 会作为模型观察结果；流中没有该事件时回退取最后一帧

端点示例

  • 普通 JSON 接口：{"method":"POST","path":"/api/data/query","contentType":"application/json","timeout":30000,"queryParams":["page","size"]}
  • GET 接口（参数走 URL）：{"method":"GET","path":"/api/stock/{symbol}","queryParams":["period"]}
  • SSE 流式接口：{"method":"POST","path":"/api/chat/stream","contentType":"application/json","streaming":true,"resultEventName":"tool_observation"}

auth（鉴权配置，选填。不传或 type=NONE 表示该服务无需鉴权）

  • type：鉴权类型。请求侧键名是 type；响应侧（getServiceDetail、getAuthSchema）回显时叫 authType，两者不要混用。可选值：
    • NONE：无需认证
    • API_KEY：API 密钥放在请求头
    • BEARER：Bearer 令牌
    • BASIC：HTTP Basic 认证
    • CUSTOM：一个或多个自定义请求头
    • CUSTOM_HTTP_TOKEN：先调用一个 HTTP 接口动态换取令牌
    • OAUTH：OAuth 2.1 按用户授权（平台预置数据源专用，见下文）
  • headerName：API_KEY 使用的请求头名，不传时默认 X-API-Key
  • tokenPrefix：BEARER 使用的令牌前缀，不传时默认 Bearer（BASIC 固定使用 Basic，此字段对它无效）
  • credential：主凭证值，API_KEY / BEARER / BASIC 使用。BEARER 只填令牌本身、不要带 Bearer 前缀；BASIC 填 base64(用户名:密码) 的结果
  • customHeaders：自定义请求头键值对，CUSTOM 使用，运行时按原样作为请求头发送
  • queryParams：URL 查询参数键值对，可与任意 type 叠加，运行时拼接到请求 URL 上（如 ?apiKey=xxx）
  • requireUserProvided：凭证由谁提供，不传时默认 false
    • false（平台统一凭证）：在 auth 里直接写真实凭证值，该服务的所有用户共用这一份凭证
    • true（用户各自提供）：auth 只作为模板，仅声明字段名、凭证值留空串；每个用户后续通过 saveAuthCredential 提交自己的凭证
  • tokenFetchConfig：动态换取令牌的配置，仅 type=CUSTOM_HTTP_TOKEN 时需要，子字段：
    • method：换取令牌的请求方法，不传时默认 POST
    • url：换取令牌的接口地址（必填）
    • headers：换取令牌时携带的请求头，客户端凭证放在这里（如 {"Authorization":"Basic xxx"}）
    • body：换取令牌的请求体字符串（如 grant_type=client_credentials）
    • tokenField：从响应 JSON 中取令牌的字段名，不传时默认 access_token
    • expiresInField：从响应 JSON 中取有效期（秒）的字段名，不传时默认 expires_in
    • targetHeaderName：把令牌注入业务请求时使用的请求头名，不传时默认 Authorization
    • targetTokenPrefix：注入令牌时使用的前缀，不传时默认 Bearer
    • refreshBufferSeconds：在令牌到期前多少秒主动刷新，不传时默认 60

各 type 的 auth 写法示例

  • NONE：{"type":"NONE"}
  • API_KEY（默认请求头 X-API-Key）：{"type":"API_KEY","credential":"sk-abcdef123456"}
  • API_KEY（自定义请求头名）：{"type":"API_KEY","headerName":"X-Custom-Key","credential":"sk-abcdef123456"}
  • BEARER：{"type":"BEARER","credential":"eyJhbGciOiJIUzI1NiJ9.payload.sig"}
  • BASIC：{"type":"BASIC","credential":"dXNlcjpwYXNz"}（dXNlcjpwYXNz 即 base64 编码后的 user:pass）
  • CUSTOM（多个自定义头）：{"type":"CUSTOM","customHeaders":{"X-App-Id":"123","X-App-Secret":"abc"}}
  • CUSTOM_HTTP_TOKEN：{"type":"CUSTOM_HTTP_TOKEN","tokenFetchConfig":{"method":"POST","url":"https://auth.example.com/oauth2/token","headers":{"Authorization":"Basic dXNlcjpwYXNz","Content-Type":"application/x-www-form-urlencoded"},"body":"grant_type=client_credentials","tokenField":"access_token","expiresInField":"expires_in","targetHeaderName":"Authorization","targetTokenPrefix":"Bearer","refreshBufferSeconds":60}}
  • 用户各自提供凭证（只声明字段名、值留空）：{"type":"CUSTOM","customHeaders":{"X-App-Secret":""},"requireUserProvided":true}
  • 鉴权信息放 URL 参数（与 BEARER 叠加）：{"type":"BEARER","credential":"my-token","queryParams":{"appId":"123"}}
  • OAUTH：仅用于平台预置的「按用户授权」数据源，需平台侧先完成 OAuth 客户端注册，通过本接口自助创建服务时暂不支持自行配置，如有此类需求请联系平台

凭证安全

  • credential、customHeaders 与 queryParams 的值落库前会加密存储；getServiceDetail 只回显含 *** 的脱敏值，不会返回明文
  • 编辑服务时把脱敏值原样回传即表示「保留原值」，星号不会被写入库；要真正修改就传新的明文值