目录

异常处理与任务取消

Task 取消

用户在对话过程中主动点击停止按钮,小艺向Agent发起任务取消请求。

小艺发起取消(小艺发送至Agent):

{
   "jsonrpc":"2.0",
   "id":"req-001",
   "method":"TasksCancel",
   "params":{
     "id":"task-001",
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001"
     }
   }
 }

Agent返回取消成功(Agent发送至小艺):

{
   "jsonrpc":"2.0",
   "id":"req-001",
   "result":{
     "id":"task-001",
     "contextId":"ctx-001",
     "status":{
       "state":"TASK_STATE_CANCELED",
       "timestamp":"2026-03-24T10:00:05.000Z"
     }
   }
 }

Agent返回取消失败——任务已终止(Agent发送至小艺):

{
     "jsonrpc":"2.0",
     "id":"req-001",
     "result":{
         "id":"task-001",
         "contextId":"ctx-001",
         "status":{
             "state":"TASK_STATE_FAILED",
             "message":{
                 "role":"ROLE_AGENT",
                 "parts":[
                     {
                         "data":{
                             "error":{
                                 "code":"99911200",
                                 "message":"错误原因"
                             }
                         }
                     }
                 ]
             },
             "timestamp":"2026-03-24T10:00:05.000Z"
         }
     }
 }

基于实际情况返回错误码,(TASK_STATE_COMPLETED/TASK_STATE_CANCELED/TASK_STATE_FAILED(code:99911200))。

Agent返回取消失败——任务无法中断(Agent发送至小艺)

{
     "jsonrpc":"2.0",
     "id":"req-001",
     "result":{
         "id":"task-001",
         "contextId":"ctx-001",
         "status":{
             "state":"TASK_STATE_FAILED",
             "message":{
                 "role":"ROLE_AGENT",
                 "parts":[
                     {
                         "data":{
                             "error":{
                                 "code":"-32002",
                                 "message":"错误原因"
                             }
                         }
                     }
                 ]
             },
             "timestamp":"Task cannot be canceled"
         }
     }
 }

错误通知

Agent处理过程中发生错误时,需要将错误通知到小艺。错误基于当前状态分为三类:

{
   "jsonrpc":"2.0",
   "id":"req-001",
   "error":{
     "code":-32001,
     "message":"Task not found"
   }
 }
{
   "jsonrpc":"2.0",
   "id":"req-001",
   "result":{
     "statusUpdate":{
       "taskId":"task-001",
       "contextId":"ctx-001",
       "status":{
         "state":"TASK_STATE_FAILED",
         "message":{
           "role":"ROLE_AGENT",
           "messageId":"msg-001",
           "parts":[
             {
               "text":"查询快递失败,请稍后重试",
               "mediaType":"text/plain"
             },
             {
               "data":{
                 "error":{
                   "code":"32603",
                   "message":"快递查询不到"
                 }
               }
             }
           ]
         },
         "timestamp":"2026-03-24T10:00:05.000Z"
       }
     },
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001",
       "agentVersion":"1.2.0"
     }
   }
 }

如果task首帧报错,也可以这样返回:

{
   "jsonrpc":"2.0",
   "id":"req-001",
   "result":{
     "task":{
       "id":"task-7f8a2b3c-0001",
       "contextId":"ctx-session-xyz",
       "status":{
         "state":"TASK_STATE_FAILED",
         "timestamp":"2026-03-04T10:24:02.500Z"
       },
       "artifacts":[
         {
           "artifactId":"artifact-001",
           "parts":[
             {
               "text":"非必要,可以不填",
               "mediaType":"text/plain"
             },
             {
               "data":{
                 "error":{
                   "code":"32603",
                   "message":"快递查询不到"
                 }
               }
             }
           ]
         }
       ]
     },
     "metadata":{
       "traceId":"trace-7f8a2b3c-0001",
       "agentId":"agent-example-001",
       "agentVersion":"1.2.0"
     }
   }
 }
  1. text用于面向用户呈现信息,错误情况下非必要,不用填写。
  2. 错误判定基于state=TASK_STATE_FAILED,data.error仅用于呈现错误信息,供调试、定位。
  • 长时任务/界面操控发生错误:建议Agent侧发生可恢复错误时,内部自行处理,需要用户介入时,通过对话胶囊/状态胶囊告知用户,不可恢复错误时,主动关闭task(TASK_STATE_FAILED)。
  • 小艺侧识别错误时,通过uiSession.action=ERROR通知Agent,错误信息在parts.data.error中承载,Agent可以进行关闭task处理。