免费下载
文档中心/ 百度搭子/ 企业版使用指南/ API参考/ 快速开始

快速开始

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

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

核心概念

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

准备工作

获取 API Key

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

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

配置环境变量

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

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

完成首次对话

第 1 步：创建 Agent

Bash 
1DUMATE_AGENT_RESPONSE=$(
2  curl -sS --fail-with-body "$DUMATE_API_BASE/agents" \
3    --request POST \
4    --header "Authorization: Bearer $DUMATE_API_KEY" \
5    --header 'Content-Type: application/json' \
6    --data '{
7      "name": "Quick Start Agent",
8      "description": "DuMate Agent API 快速开始",
9      "system": "你是一个乐于助人的助手，回答简洁准确。"
10    }'
11)
12 
13DUMATE_AGENT_ID=$(jq -er '.id' <<<"$DUMATE_AGENT_RESPONSE")

请求参数说明：

字段 是否必填 填写规则
name 必填 智能体名称。
description 选填 智能体用途描述。
system 选填 系统提示词，用于定义智能体的角色设定与行为。
files 选填 要挂载的随身文件。
skills 选填 要启用的技能。
mcpServers 选填 要接入的 MCP 工具服务。

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

JSON 
1{
2  "id": "agt_xxxxxxxxxxxx",
3  "name": "Quick Start Agent"
4}

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

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

第 2 步：创建 Session

Bash 
1DUMATE_SESSION_RESPONSE=$(
2  curl -sS --fail-with-body "$DUMATE_API_BASE/sessions" \
3    --request POST \
4    --header "Authorization: Bearer $DUMATE_API_KEY" \
5    --header 'Content-Type: application/json' \
6    --data '{"agent": {"id": "'"$DUMATE_AGENT_ID"'"}}'
7)
8 
9DUMATE_SESSION_ID=$(jq -er '.id' <<<"$DUMATE_SESSION_RESPONSE")

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

第 3 步：订阅 SSE

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

接口 方法 说明
/sessions/{sessionId}/events/stream GET SSE，订阅会话事件流
/sessions/{sessionId}/events POST 发送事件，例如用户消息
Bash 
1curl -sS -N "$DUMATE_API_BASE/sessions/$DUMATE_SESSION_ID/events/stream" \
2  --header "Authorization: Bearer $DUMATE_API_KEY" \
3  --header 'Accept: text/event-stream'

第 4 步：发送消息

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

为智能体扩展能力

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

挂载文件

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

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

拿到 fileID 后有两种用法：

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

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

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

JSON 
1{
2  "events": [{
3    "type": "user.message",
4    "content": [
5      {"type": "text", "text": "总结一下这个文件。"},
6      {"type": "file", "file_id": "file_xxxxxxxxxxxx"}
7    ]
8  }]
9}

安装技能

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

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

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

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

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

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

接入 MCP 工具

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

JSON 
1{
2  "mcpServers": [{
3    "type": "url",
4    "name": "example",
5    "url": "https://mcp.example.com/mcp-servers/example"
6  }]
7}

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

多用户凭证隔离（Vault）

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

  1. 为终端用户创建 Vault（参见创建凭证空间）。
Bash 
1DUMATE_VAULT_RESPONSE=$(
2  curl -sS --fail-with-body "$DUMATE_API_BASE/vaults" \
3    --request POST \
4    --header "Authorization: Bearer $DUMATE_API_KEY" \
5    --header 'Content-Type: application/json' \
6    --data '{"name": "user_10001"}'
7)
8 
9DUMATE_VAULT_ID=$(jq -er '.id' <<<"$DUMATE_VAULT_RESPONSE")
  1. 将终端用户的凭证写入 Vault（参见创建凭证）。
Bash 
1curl -sS "$DUMATE_API_BASE/vaults/$DUMATE_VAULT_ID/credentials" \
2  --request POST \
3  --header "Authorization: Bearer $DUMATE_API_KEY" \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "name": "example",
7    "auth": {
8      "type": "static_bearer",
9      "mcpServerUrl": "https://mcp.example.com/mcp-servers/example",
10      "token": "<USER_TOKEN>"
11    }
12  }'
  1. 创建会话并绑定 Vault。
Bash 
1curl -sS "$DUMATE_API_BASE/sessions" \
2  --request POST \
3  --header "Authorization: Bearer $DUMATE_API_KEY" \
4  --header 'Content-Type: application/json' \
5  --data '{"agent": {"id": "'"$DUMATE_AGENT_ID"'"}, "vaultIds": ["'"$DUMATE_VAULT_ID"'"]}'

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

下一步