简体中文

下载 App

输入关键字搜索

开发者能力认证

鸿蒙高校创新赛

HarmonyOS 7

animation

HarmonyOS行业解决方案

layoutWeight

HarmonyOS模板&组件

bindPopup

bindsheet

CTRL+K

文档管理中心

我的

Hello，

欢迎来到开发者联盟

对话交互

更新时间: 2026-07-27 12:49

本文导读

单轮问答

用户提问，Agent一次返回完整答复，适用于简单播报场景。

用户请求：

收起
自动换行
深色代码主题
复制
{
   "jsonrpc":"2.0",
   "id":"req-002",
   "method":"MessageStream",
   "params":{
     "message":{
       "messageId":"msg-abc-002",
       "role":"ROLE_USER",
       "contextId":"ctx-session-xyz",
       "parts":[
         {
           "text":"请介绍一下量子计算的基本原理",
           "mediaType":"text/plain"
         }
       ]
     },
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001",
       "appVersion":"12.0.1"
     }
   }
 }

Agent一次性返回结果：

收起
自动换行
深色代码主题
复制
{
   "jsonrpc":"2.0",
   "id":"req-001",
   "result":{
     "task":{
       "id":"task-7f8a2b3c-0001",
       "contextId":"ctx-session-xyz",
       "status":{
         "state":"TASK_STATE_COMPLETED",
         "timestamp":"2026-03-04T10:24:02.500Z"
       },
       "artifacts":[
         {
           "artifactId":"artifact-001",
           "parts":[
             {
               "text":"量子计算基本原理...",
               "mediaType":"text/plain"
             },
             {
               "data":{
                 "ttsText":"国航一二三四于下午两点半从三号航站楼起飞，预计准点。"
               }
             }
           ]
         }
       ]
     },
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001",
       "agentVersion":"1.2.0"
     }
   }
 }

说明

data.ttsText为TTS播报内容。同一artifact内只要有任意part包含data.ttsText，则发声内容以ttsText为准。如果播报内容和text一致，可以不传。

流式分批回复（含思考过程、推荐）

Agent逐步输出回答，用户可实时看到思考过程和内容生成。

首帧（TASK_STATE_SUBMITTED）：

收起
自动换行
深色代码主题
复制
{
   "jsonrpc":"2.0",
   "id":"req-002",
   "result":{
     "task":{
       "id":"task-9e1b4d5f-0001",
       "contextId":"ctx-session-xyz",
       "status":{
         "state":"TASK_STATE_SUBMITTED",
         "timestamp":"2026-03-04T10:24:00.000Z"
       }
     },
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001",
       "agentVersion":"1.2.0"
     }
   }
 }

中间帧——过程信息（TASK_STATE_WORKING），message.parts[].text将对用户展示：

收起
自动换行
深色代码主题
复制
{
  "jsonrpc":"2.0",
  "id":"req-001",
  "result":{
    "statusUpdate":{
      "taskId":"task-9e1b4d5f-0001",
      "contextId":"ctx-session-xyz",
      "status":{
        "state":"TASK_STATE_WORKING",
        "message":{
          "role":"ROLE_AGENT",
          "messageId":"msg-001",
          "parts":[
            {
              "text":"正在思考",
              "mediaType":"text/plain",
            }
          ]
        },
        "timestamp":"2026-03-24T10:00:01.000Z"
      }
    },
    "metadata":{
      "traceId":"trace-7f8a2b3c-0001",
      "agentId":"agent-example-001",
      "agentVersion":"1.2.0"
    }
  }
 }

中间帧——思考内容，thinking对用户展示思考过程：

收起
自动换行
深色代码主题
复制
{
   "jsonrpc":"2.0",
   "id":"req-001",
   "result":{
     "artifactUpdate":{
       "taskId":"task-9e1b4d5f-0001",
       "contextId":"ctx-session-xyz",
       "artifact":{
         "artifactId":"art-thinking-001",
         "parts":[
           {
             "data":{
               "thinking":"用户问的是量子计算，需要先解释基本原理..."
             }
           }
         ]
       },
       "append":false,
       "lastChunk":false
     },
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001",
       "agentVersion":"1.2.0"
     }
   }
 }

thinking支持增量发送：append值为true表示本帧内容追加到同一artifactId的上一帧thinking中，未返回或者返回lastChunk=true视为append结束，例如开始返回正文。

中间帧——流式正文，支持增量叠加：

收起
自动换行
深色代码主题
复制
{
   "jsonrpc":"2.0",
   "id":"req-001",
   "result":{
     "artifactUpdate":{
       "taskId":"task-9e1b4d5f-0001",
       "contextId":"ctx-session-xyz",
       "artifact":{
         "artifactId":"art-text-001",
         "parts":[
           {
             "text":"量子计算是一种利用量子力学原理",
             "mediaType":"text/plain"
           }
         ]
       },
       "append":true,
       "lastChunk":false
     },
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001",
       "agentVersion":"1.2.0"
     }
   }
 }

中间帧——流式正文最后一片（lastChunk=true标识正文结束）：

收起
自动换行
深色代码主题
复制
{
   "jsonrpc":"2.0",
   "id":"req-001",
   "result":{
     "artifactUpdate":{
       "taskId":"task-9e1b4d5f-0001",
       "contextId":"ctx-session-xyz",
       "artifact":{
         "artifactId":"art-text-001",
         "parts":[
           {
             "text":"进行信息处理的新型计算模式。",
             "mediaType":"text/plain"
           }
         ]
       },
       "append":true,
       "lastChunk":true
     },
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001",
       "agentVersion":"1.2.0"
     }
   }
 }

末帧（TASK_STATE_COMPLETED）：

收起
自动换行
深色代码主题
复制
{
   "jsonrpc":"2.0",
   "id":"req-001",
   "result":{
     "statusUpdate":{
       "taskId":"task-9e1b4d5f-0001",
       "contextId":"ctx-session-xyz",
       "status":{
         "state":"TASK_STATE_COMPLETED",
         "timestamp":"2026-03-24T10:00:05.000Z"
       }
     },
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001",
       "agentVersion":"1.2.0"
     }
   }
 }

Agent 对话澄清

信息不足时，Agent主动追问用户，补充后继续完成任务。

Agent发起澄清（Agent发送至小艺）：

收起
自动换行
深色代码主题
复制
{
  "jsonrpc":"2.0",
  "id":"req-001",
  "result":{
    "statusUpdate":{
      "taskId":"task-001",
      "contextId":"ctx-001",
      "status":{
        "state":"TASK_STATE_INPUT_REQUIRED",
        "message":{
          "role":"ROLE_AGENT",
          "messageId":"msg-001",
          "parts":[
            {
              "text":"请问您要去哪个城市？",
              "mediaType":"text/plain"
            }
          ]
        },
        "timestamp":"2026-03-24T10:00:01.000Z"
      }
    },
    "metadata":{
      "traceId":"trace-7f8a2b3c-0001",
      "agentId":"agent-example-001",
      "agentVersion":"1.2.0"
    }
  }
 }

注意：state为TASK_STATE_INPUT_REQUIRED，表示需要用户输入。

小艺回复用户答案（小艺发送至Agent）：

收起
自动换行
深色代码主题
复制
{
  "jsonrpc":"2.0",
  "id":"req-002",
  "method":"MessageStream",
  "params":{
    "message":{
      "messageId":"msg-002",
      "taskId":"task-001",
      "contextId":"ctx-001",
      "role":"ROLE_USER",
      "parts":[
        {
          "text":"北京",
          "mediaType":"text/plain"
        }
      ]
    },
    "metadata":{
      "traceId":"trace-7f8a2b3c-0002",
      "agentId":"agent-example-001",
      "appVersion":"12.0.1"
    }
  }
 }

说明

这里小艺会携带相同的taskId。

文件传递

小艺与Agent之间互相传递在线图片或文件。

Agent返回文件（以PNG图片为例）：

收起
自动换行
深色代码主题
复制
{
   "jsonrpc":"2.0",
   "id":"req-001",
   "result":{
     "artifactUpdate":{
       "taskId":"task-001",
       "contextId":"ctx-001",
       "artifact":{
         "artifactId":"art-file-001",
         "parts":[
           {
             "url":"https://example.com/image.png",
             "filename":"image.png",
             "mediaType":"image/png"
           }
         ]
       },
       "append":false,
       "lastChunk":true
     },
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001",
       "agentVersion":"1.2.0"
     }
   }
 }

其中mediaType支持范围见【Part结构定义】章节。

对话返回卡片

Agent触发端侧渲染卡片，向用户展示富媒体内容。

Agent返回卡片（Agent发送至小艺）：

收起
自动换行
深色代码主题
复制
{
   "jsonrpc":"2.0",
   "id":"req-001",
   "result":{
     "artifactUpdate":{
       "taskId":"task-001",
       "contextId":"ctx-001",
       "artifact":{
         "artifactId":"art-card-001",
         "parts":[
           {
             "data":{
               "uiExtensionCard":{
                 "cardId":"卡片id",
                 "bundleName":"com.example.agentapp",
                 "moduleName":"entry",
                 "abilityName":"AgentUIExtensionAbility",
                 "payload":"卡片参数",
                 "dimension":"2x4",
                 "encrypted":false,
                 "summary":"卡片摘要，用于上下文存储和风控"
               }
             }
           }
         ]
       },
       "append":false,
       "lastChunk":true
     },
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001",
       "agentVersion":"1.2.0"
     }
   }
 }