快速开始

更新时间：2026-11-13

本文介绍如何通过 DuMate Agent API，将具备对话能力并支持工具调用的智能体集成到自有产品中，供开发者参考。

开发者负责定义智能体的角色设定与能力，平台负责运行智能体、维护会话状态，并实时向调用方推送执行事件。

核心概念

对象	是什么	生命周期
Agent（智能体）	预先定义的智能体配置，包括系统提示词、工具、技能和 MCP 服务	长期保存，可被多个会话复用，支持版本管理
Environment（环境）	智能体运行的沙箱，定义预装软件包	长期保存，可被多个会话复用
Session（会话）	绑定一个智能体和一个环境的一次对话上下文	通常对应一次对话
Event（事件）	会话中的一条消息或一次状态变更；通过 POST 发送，通过 SSE 接收	会话内
Thread（线程）	会话内的执行单元，主线程标识与会话标识相同	会话内
File（文件）	调用方上传的文件，以及智能体在会话中生成的产物	长期保存，上传时可设置有效期
Skill（技能）	一组可复用的指令和脚本文件，挂载到智能体后供其使用	长期保存并支持版本管理
Vault / Credential（凭证空间 / 凭证）	存储终端用户的第三方账号凭证，实现用户之间的凭证隔离	随终端用户存在

准备工作

获取 API Key

注意：API Key 具备该账号下智能体和数据的访问权限，属于敏感凭证。请勿将其写入前端代码、Markdown 文件、脚本、日志或截图，也不要提交到代码仓库。

配置环境变量

                Bash
                
                export DUMATE_API_BASE='https://api.dumate.cn/api/dma/v1'
export DUMATE_API_KEY='<YOUR_API_KEY>'

所有请求均通过 Authorization: Bearer <API_KEY> 完成身份认证，请求头说明如下：

头域名称	必填	说明
`Authorization`	是	固定格式 `Bearer <API_KEY>`。
`Content-Type`	有请求体时必填	JSON 接口为 `application/json`；上传文件、创建技能为 `multipart/form-data`。

普通请求的请求体和响应体均为 JSON，文件和技能上传使用 multipart/form-data。

完成首次对话

创建会话需要同时指定智能体和环境，因此首次对话分为五步：创建智能体、创建环境、创建会话、订阅事件流、发送消息。

第 1 步：创建智能体

                Bash
                
            

                DUMATE_AGENT_RESPONSE=$(
  curl -sS --fail-with-body "$DUMATE_API_BASE/agents" \
    --request POST \
    --header "Authorization: Bearer $DUMATE_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Quick Start Agent",
      "description": "DuMate Agent API 快速开始",
      "system": "你是一个乐于助人的助手，回答简洁准确。"
    }'
)

DUMATE_AGENT_ID=$(jq -er '.id' <<<"$DUMATE_AGENT_RESPONSE")
            

请求参数说明：

字段	是否必填	填写规则
name	必填	智能体名称，1–256 个字符。
description	选填	智能体用途描述，最长 2048 个字符。
system	选填	系统提示词，用于定义智能体的角色设定与行为，最长 100000 个字符。
tools	选填	工具配置，包括内置工具集、MCP 工具集和自定义工具。
mcp_servers	选填	要接入的 MCP 服务，最多 20 个。
skills	选填	要启用的技能。
metadata	选填	自定义键值，最多 16 对。

响应中的 id 即为智能体标识，创建会话时需要使用：

                JSON
                
            

                {
  "type": "agent",
  "id": "agt_2ad2d132c698",
  "name": "Quick Start Agent",
  "version": 1
}
            

提示：tools、mcp_servers 和 skills 均可在此步骤挂载。首次验证时可以全部留空，完成基础流程后再参考「为智能体扩展能力」按需添加。

完整字段说明参见「智能体配置 / 创建智能体」。

第 2 步：创建环境

环境定义智能体运行的沙箱。首次验证时只需指定 config.type 为 cloud。

                Bash
                
            

                DUMATE_ENV_RESPONSE=$(
  curl -sS --fail-with-body "$DUMATE_API_BASE/environments" \
    --request POST \
    --header "Authorization: Bearer $DUMATE_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Quick Start Environment",
      "config": {"type": "cloud", "packages": {"pip": ["pandas"]}}
    }'
)

DUMATE_ENV_ID=$(jq -er '.id' <<<"$DUMATE_ENV_RESPONSE")
            

config.packages 用于声明预装软件包，按包管理器分组，仅支持 pip、npm。完整字段说明参见「环境管理 / 创建环境」。

一个环境可以被多个会话复用，无需为每次对话重复创建。

第 3 步：创建会话

                Bash
                
            

                DUMATE_SESSION_RESPONSE=$(
  curl -sS --fail-with-body "$DUMATE_API_BASE/sessions" \
    --request POST \
    --header "Authorization: Bearer $DUMATE_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
      "agent": "'"$DUMATE_AGENT_ID"'",
      "environment_id": "'"$DUMATE_ENV_ID"'",
      "title": "Quick Start Session"
    }'
)

DUMATE_SESSION_ID=$(jq -er '.id' <<<"$DUMATE_SESSION_RESPONSE")
            

agent 支持三种写法：

写法	示例	说明
字符串	`"agt_xxx"`	使用该智能体的最新版本。
`agent` 对象	`{"type": "agent", "id": "agt_xxx", "version": 2}`	固定到指定版本，`version` 不传等同最新版本。
`agent_with_overrides` 对象	`{"type": "agent_with_overrides", "id": "agt_xxx"}`	引用智能体，可为本会话覆盖 `system`、`tools`、`mcp_servers`、`skills`，智能体本身不变。

响应同样会返回一个 id，即会话标识，同时返回 status、usage、stats 等运行时字段。完整字段说明参见「会话管理 / 创建会话」。

第 4 步：订阅事件流

对话过程是异步的：客户端应先订阅会话事件流，再发送消息；智能体的响应会以事件形式推送。

接口	方法	说明
`/sessions/{session_id}/events/stream`	GET	SSE，订阅会话事件流
`/sessions/{session_id}/events`	POST	发送事件，例如用户消息
`/sessions/{session_id}/events`	GET	拉取事件历史

订阅命令不会自己结束，因此放到后台执行，这样后续步骤可以在同一个终端继续使用前面设置的环境变量：

                Bash
                
                curl -sS -g -N "$DUMATE_API_BASE/sessions/$DUMATE_SESSION_ID/events/stream?event_deltas[]=agent.message" \
  --header "Authorization: Bearer $DUMATE_API_KEY" \
  --header 'Accept: text/event-stream' &

-g 用于关闭 curl 对 [] 的通配解析，-N 用于关闭输出缓冲，末尾的 & 让订阅在后台保持连接。event_deltas[] 声明需要逐段输出的事件类型，不传时只推送完整事件帧。

没有新事件时终端不会有输出。如果习惯在另一个终端订阅，需要先在新终端重新执行「配置环境变量」，并设置 DUMATE_SESSION_ID。完整说明参见「会话管理 / 订阅会话事件流」。

第 5 步：发送消息

在同一个终端发送消息，智能体的回复会由后台的订阅命令打印出来：

                Bash
                
            

                curl -sS --fail-with-body \
  "$DUMATE_API_BASE/sessions/$DUMATE_SESSION_ID/events" \
  --request POST \
  --header "Authorization: Bearer $DUMATE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "events": [{
      "type": "user.message",
      "content": [{"type": "text", "text": "用一句话介绍你自己。"}]
    }]
  }'
            

该接口只返回事件回显，processed_at 为 null 表示尚未处理：

                JSON
                
            

                {
  "data": [{
    "id": "sevt_msg_g001a1c356cb9c001egSwADPkMC6ZRu",
    "type": "user.message",
    "content": [{"type": "text", "text": "用一句话介绍你自己。"}],
    "processed_at": null
  }]
}
            

智能体的回复会推送到第 4 步的订阅终端，典型事件顺序如下：

Text

1event: user.message          // 用户消息入队
2event: session.status_running // 会话开始运行
3event: agent.thinking         // 智能体开始思考
4event: agent.message          // 智能体回复
5event: session.usage          // 累计用量快照
6event: session.status_idle    // 本轮结束，stop_reason 为 end_turn

也可以调用获取会话事件历史接口补拉：

                Bash
                
                curl -sS "$DUMATE_API_BASE/sessions/$DUMATE_SESSION_ID/events?order=asc&limit=50" \
  --header "Authorization: Bearer $DUMATE_API_KEY"

为智能体扩展能力

以下能力均为可选项，可根据业务需要启用。

挂载文件

先上传文件并获取文件标识（参见「文件管理 / 上传文件」）：

                Bash
                
            

                DUMATE_FILE_RESPONSE=$(
  curl -sS --fail-with-body "$DUMATE_API_BASE/files" \
    --request POST \
    --header "Authorization: Bearer $DUMATE_API_KEY" \
    --form 'file=@/absolute/path/to/agent-file.txt'
)

DUMATE_FILE_ID=$(jq -er '.id' <<<"$DUMATE_FILE_RESPONSE")
            

拿到文件标识后有三种用法：

在对话中引用：发送消息时在 content 中引用，系统会先把文件挂载到会话再发给智能体。

                JSON
                
            

                {
  "events": [{
    "type": "user.message",
    "content": [
      {"type": "text", "text": "总结一下这个文件。"},
      {"type": "file", "file_id": "node_g001a1c3534dc1001mUC0tecbzGoZuN"}
    ]
  }]
}
            

内容块还支持 {"type": "document", "source": {"type": "file", "file_id": "..."}} 和 {"type": "image", "source": {...}}，分别用于 PDF 文档和图片；file 块用于其他类型的文件。

创建会话时挂载：在 resources 中声明，会话启动时即可访问。

                JSON
                
            

                {
  "agent": "agt_xxx",
  "environment_id": "env_xxx",
  "resources": [{"type": "file", "file_id": "node_xxx"}]
}
            

运行期追加挂载：调用挂载会话资源接口，可指定沙箱内的挂载路径。

                Bash
                
            

                curl -sS "$DUMATE_API_BASE/sessions/$DUMATE_SESSION_ID/resources" \
  --request POST \
  --header "Authorization: Bearer $DUMATE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"type": "file", "file_id": "'"$DUMATE_FILE_ID"'", "mount_path": "/mnt/session/uploads/custom/demo.txt"}'
            

智能体在会话中生成的文件称为会话产物，标识以 art_ 开头，可通过 GET /files?scope_id=<会话标识> 查询。

安装技能

技能是一组可复用的指令和脚本文件。上传时必须包含位于顶层目录下的 SKILL.md，技能的名称和描述从该文件的 YAML 字段解析：

Text

1---
2name: demo-skill
3description: 用于演示技能上传的最小示例。
4---
5
6# demo-skill
7
8技能的指令正文，供智能体在运行时参考。

上传技能（参见「技能管理 / 创建技能」）：

                Bash
                
            

                DUMATE_SKILL_RESPONSE=$(
  curl -sS --fail-with-body "$DUMATE_API_BASE/skills" \
    --request POST \
    --header "Authorization: Bearer $DUMATE_API_KEY" \
    --form 'display_name=demo-skill' \
    --form 'files[]=@demo-skill/SKILL.md;filename=demo-skill/SKILL.md' \
    --form 'files[]=@demo-skill/reference.md;filename=demo-skill/reference.md'
)

DUMATE_SKILL_ID=$(jq -er '.id' <<<"$DUMATE_SKILL_RESPONSE")
            

文件名带目录前缀表示相对路径，下载技能版本内容时会保留该目录结构。上传成功后同时生成第一个版本，响应中的 latest_version_id 即为该版本的标识。

创建或更新智能体时在 skills 字段引用。省略 version 表示使用最新版本：

                JSON
                
                {
  "skills": [{"type": "custom", "skill_id": "<技能标识>"}]
}

需要固定到某个版本时，version 传入技能接口返回的版本标识：

                JSON
                
                {
  "skills": [{"type": "custom", "skill_id": "<技能标识>", "version": "<版本标识>"}]
}

版本标识可从创建技能响应的 latest_version_id，或获取技能版本列表接口的 version 字段获取。version 传入整数会返回 400。

每次上传新内容会生成一个新版本，调用创建技能版本接口即可。

接入 MCP 工具

在智能体配置中声明 MCP 服务，并通过 mcp_toolset 引用，智能体即可在对话中自主调用该服务提供的工具：

                JSON
                
            

                {
  "name": "Quick Start Agent",
  "mcp_servers": [{
    "type": "url",
    "name": "example",
    "url": "https://mcp.example.com/mcp-servers/example"
  }],
  "tools": [{"type": "mcp_toolset", "mcp_server_name": "example"}]
}
            

注意：mcp_servers 中的每个服务都必须被 tools 中某个 mcp_toolset 的 mcp_server_name 引用，否则创建失败。

多用户凭证隔离（Vault）

如果 MCP 服务需要使用终端用户的账号进行鉴权，则需要为每个终端用户创建一个凭证空间，将对应凭证存入其中，并在创建会话时绑定该凭证空间。这样，当同一个智能体为多个终端用户提供服务时，各用户的凭证可以相互隔离。运行时由服务端注入凭证，凭证明文不会出现在会话事件中。

为终端用户创建凭证空间（参见「凭证管理 / 创建凭证空间」）。

                Bash
                
            

                DUMATE_VAULT_RESPONSE=$(
  curl -sS --fail-with-body "$DUMATE_API_BASE/vaults" \
    --request POST \
    --header "Authorization: Bearer $DUMATE_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{"display_name": "user_10001"}'
)

DUMATE_VAULT_ID=$(jq -er '.id' <<<"$DUMATE_VAULT_RESPONSE")
            

将终端用户的凭证写入凭证空间（参见「凭证管理 / 创建凭证」）。

                Bash
                
            

                curl -sS "$DUMATE_API_BASE/vaults/$DUMATE_VAULT_ID/credentials" \
  --request POST \
  --header "Authorization: Bearer $DUMATE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "example",
    "auth": {
      "type": "static_bearer",
      "mcp_server_url": "https://mcp.example.com/mcp-servers/example",
      "token": "<USER_TOKEN>"
    }
  }'
            

auth.type 支持三种认证类型：

类型	用途	必填字段
`static_bearer`	固定 Bearer token	`mcp_server_url`、`token`
`mcp_oauth`	MCP 服务的 OAuth 凭证	`mcp_server_url`、`access_token`
`environment_variable`	以环境变量注入沙箱	`secret_name`、`secret_value`、`networking`

注意：auth.mcp_server_url 必须与智能体中声明的 MCP 服务地址保持一致，平台据此将凭证匹配到对应工具。创建 static_bearer、mcp_oauth 凭证时，系统会用该凭证实际探测一次该地址，服务不可达或凭证被拒绝时创建失败。

创建会话并绑定凭证空间。

                Bash
                
            

                curl -sS "$DUMATE_API_BASE/sessions" \
  --request POST \
  --header "Authorization: Bearer $DUMATE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "agent": "'"$DUMATE_AGENT_ID"'",
    "environment_id": "'"$DUMATE_ENV_ID"'",
    "vault_ids": ["'"$DUMATE_VAULT_ID"'"]
  }'
            

评价此篇文章

有帮助没帮助

认证鉴权

智能体配置

百度智能云

百度搭子