快速开始

更新时间：2026-09-14

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

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

核心概念

对象	是什么	生命周期
Agent（智能体）	预先定义的智能体配置，包括系统提示词、可用技能、MCP 工具和随身文件	长期保存，可被多个会话复用
Session（会话）	与某个 Agent 绑定的一次对话上下文	通常对应一次对话
Event（事件）	会话中的一条消息或一次状态变更；通过 POST 发送，通过 SSE 接收	会话内
Skill（技能）	以技能包形式上传，为智能体提供可复用的任务处理能力	长期保存并支持版本管理
Vault / Credential（凭证空间 / 凭证）	用于存储终端用户的第三方账号凭证，实现用户之间的凭证隔离	随终端用户存在

准备工作

获取 API Key

登录百度搭子管理平台，进入 API 集成 页面创建 API Key，详情参考认证鉴权。

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

配置环境变量

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

所有 API 请求均通过 Authorization: Bearer <API_KEY> 完成身份认证。普通请求的请求体和响应体均为 JSON，文件上传使用 multipart/form-data。

完成首次对话

第 1 步：创建 Agent

                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	必填	智能体名称。
description	选填	智能体用途描述。
system	选填	系统提示词，用于定义智能体的角色设定与行为。
files	选填	要挂载的随身文件。
skills	选填	要启用的技能。
mcpServers	选填	要接入的 MCP 工具服务。

响应中的 id 即为 Agent ID，创建会话时需要使用该 ID：

                JSON
                
                {
  "id": "agt_xxxxxxxxxxxx",
  "name": "Quick Start Agent"
}

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

完整字段说明参见创建智能体。

第 2 步：创建 Session

                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": {"id": "'"$DUMATE_AGENT_ID"'"}}'
)
 
DUMATE_SESSION_ID=$(jq -er '.id' <<<"$DUMATE_SESSION_RESPONSE")
            

响应同样会返回一个 id，即 Session ID。完整字段说明参见创建会话。

第 3 步：订阅 SSE

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

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

                Bash
                
                curl -sS -N "$DUMATE_API_BASE/sessions/$DUMATE_SESSION_ID/events/stream" \
  --header "Authorization: Bearer $DUMATE_API_KEY" \
  --header 'Accept: text/event-stream'

第 4 步：发送消息

                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": "用一句话介绍你自己。"}]
    }]
  }'
            

为智能体扩展能力

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

挂载文件

先上传文件并获取 fileID（参见上传文件）：

                Bash
                
                curl -sS "$DUMATE_API_BASE/files" \
  --request POST \
  --header "Authorization: Bearer $DUMATE_API_KEY" \
  --form 'file=@/absolute/path/to/agent-file.txt'

拿到 fileID 后有两种用法：

挂载到 Agent：创建 Agent 时在 files 字段声明，该 Agent 下的所有会话均可长期访问。

                JSON
                
            

                {
  "name": "Quick Start Agent",
  "system": "读取用户提供的文件并完成任务。",
  "files": [{"fileID": "file_xxxxxxxxxxxx"}]
}
            

在对话中引用：发送消息时在 content 中引用，仅当前会话可见。

                JSON
                
            

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

安装技能

上传技能包（ZIP 格式），参见创建技能（ZIP包）：

                Bash
                
                curl -sS "$DUMATE_API_BASE/skills/upload" \
  --request POST \
  --header "Authorization: Bearer $DUMATE_API_KEY" \
  --form 'file=@/absolute/path/to/skill.zip'

注意：技能包上传后还需要完成解析和发布，不能立即使用。请轮询获取技能详情接口，确认返回 releaseId 后，再将 skillID 与 releaseID 一起写入 Agent 的 skills 字段。

                JSON
                
                {
  "skills": [{"skillID": "skl_xxxxxxxxxxxx", "releaseID": "rel_xxxxxxxxxxxx"}]
}

说明：【待确认：建议的轮询间隔和超时时间是多少？解析失败时如何获取失败原因？】

技能包的目录结构与编写方式请参阅百度搭子技能开发指南。

接入 MCP 工具

在 Agent 配置的 mcpServers 字段中声明外部工具服务：

                JSON
                
            

                {
  "mcpServers": [{
    "type": "url",
    "name": "example",
    "url": "https://mcp.example.com/mcp-servers/example"
  }]
}
            

配置完成后，智能体即可在对话过程中自主调用该服务提供的工具。

多用户凭证隔离（Vault）

如果 MCP 服务需要使用终端用户的账号进行鉴权，则需要为每个终端用户创建一个凭证空间（Vault），将对应凭证存入其中，并在创建会话时绑定相应的 Vault ID。这样，当同一个 Agent 为多个终端用户提供服务时，各用户的凭证可以相互隔离。

为终端用户创建 Vault（参见创建凭证空间）。

                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 '{"name": "user_10001"}'
)
 
DUMATE_VAULT_ID=$(jq -er '.id' <<<"$DUMATE_VAULT_RESPONSE")
            

将终端用户的凭证写入 Vault（参见创建凭证）。

                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 '{
    "name": "example",
    "auth": {
      "type": "static_bearer",
      "mcpServerUrl": "https://mcp.example.com/mcp-servers/example",
      "token": "<USER_TOKEN>"
    }
  }'
            

创建会话并绑定 Vault。

                Bash
                
            

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

注意：auth.mcpServerUrl 必须与 Agent 中声明的 MCP 服务地址保持一致，平台据此将凭证匹配到对应工具。地址不一致时，凭证将不会生效。

下一步

了解如何获取API key：认证鉴权
了解技能包的目录结构与编写方式：百度搭子技能开发指南

评价此篇文章

有帮助没帮助

管理平台

认证鉴权