灵珠接入三方智能体协议

灵珠平台对接三方智能体的协议规范与示例。

本文档来自《灵珠接入三方智能体协议》原始文档内容，以下为表格化整理（非截图）。

三方智能体 SSE 接口协议（请求）

Header

属性	类型	必填	属性值	说明
Authorization	String	是	Bearer <智能体鉴权AK>	智能体请求鉴权
Content-Type	String	是	application/json	固定值

Body

属性	类型	必填	说明
message_id	String	是	消息 ID，维持上下文
agent_id	String	是	智能体 ID
message	Message Object[]	是	用户输入数组
user_id	String	否	用户 ID
metadata	Metadata Object	否	可选元数据

Message Object

属性	类型	必填	说明
role	string	是	角色：user / agent
type	string	是	消息类型：text / image
text	string	否	文本内容（type=text 时必填）
image_url	string	否	图片内容（type=image 时必填）

Metadata Object

属性	类型	必填	说明
context	Context Object	是	灵珠平台传入的设备信息（天气、电量、位置等）

Context Object

属性	类型	必填	说明
location	string	是	设备当前所在位置信息
latitude	string	是	设备当前所在纬度
longitude	string	是	设备当前所在经度
weather	string	是	设备当前所在地天气信息
battery	string	是	设备当前电量

SSE 输出协议（响应）

事件行

字段	类型	必填	取值	说明
event	event	是	message / done	事件类型，done 表示结束

data 对象

字段	类型	必填	取值	说明
role	String	是	agent	角色
message_id	String	是	消息 ID	维持上下文
agent_id	String	是	智能体 ID
answer_stream	String	否	输出内容	流式输出
is_finish	Boolean	是	true/false	是否完成
type	String	是	answer / tool_call / follow_up	返回类型（文本/工具调用/用户问题建议）
follow_up	string[]	否	用户问题建议	用户问题建议列表
tool_call	Tool Object	否	工具调用	工具调用

Tool Object

属性	类型	必填	说明
command	String	是	命令：take_photo（拍照）/ take_navigation（导航）/ notify_agent_off（退出智能体）/ control_calendar（添加日程）
action	String	否	take_navigation 时：open / close；control_calendar 时：create
poi_name	String	否	take_navigation 时：目标地址
navi_type	String	否	导航类型：0 驾车 / 1 步行 / 2 骑行
title	String	否	control_calendar 时：日程标题
start_time	String	否	control_calendar 时：日程开始时间
end_time	String	否	control_calendar 时：日程结束时间

请求示例（curl）

curl -N -X POST "https://example.com/agent/sse" \
  -H "Authorization: Bearer <智能体鉴权AK>" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "msg_123",
    "agent_id": "agent_123",
    "message": [
      { "role": "user", "type": "text", "text": "你好" }
    ],
    "user_id": "user_001",
    "metadata": {
      "context": {
        "location": "上海市浦东新区",
        "latitude": "31.2304",
        "longitude": "121.4737",
        "weather": "晴",
        "battery": "78"
      }
    }
  }'

请求示例（JSON）

{
  "metadata": {
    "lang": "zh-CN",
    "location": "中国浙江省杭州市余杭区仓前街道良睦路1288号梦想小镇创业集市8幢",
    "company_id": 1,
    "latitude": "30.287759999999999",
    "longitude": "120.00449",
    "currentTime": "2026-02-09 下午4:22:15",
    "weather": "1. 今日：当前天气阴，8度，最低0度，最高8度。\\n2. 明天：小雨，最低3度，最高15度。\\n3. 后天：晴，最低3度，最高15度。",
    "battery": "99",
    "runningApp": ""
  },
  "agent_id": "f537f6a2c01f47b1aa48f073d921364f",
  "user_id": "D20197B06A604D959C5A37EE28324DE7",
  "message_id": "1770625332",
  "message": [
    {
      "role": "user",
      "type": "text",
      "text": "你好。",
      "image_url": null
    }
  ]
}

输出示例（SSE）

event: message
data: {"role":"agent","type":"answer","answer_stream":"helfen","message_id":"7597792895776587776","agent_id":"agent_123","is_finish":false}

event: message
data: {"role":"agent","type":"follow_up","follow_up":["你想了解哪种智能体能力？","是否需要我展示配置示例？"],"message_id":"7597792895776587776","agent_id":"agent_123","is_finish":true}

event: message
data: {"role":"agent","type":"tool_call","tool_call":{"command":"take_navigation","action":"open","poi_name":"上海虹桥火车站","navi_type":"0"},"message_id":"7597792895776587776","agent_id":"agent_123","is_finish":true}