发送图片、重新生成与提交交互答复¶
通过同一 A2A 入口发送图片或控制消息。先读取原任务或当前交互,保留相应任务、对话和请求标识,再提交操作。
准备与调用¶
按调用前准备配置服务地址、个人访问令牌与工作区。从智能体目录确定目标;本页示例选择当前工作区的智能体。
将对应小节的完整 JSON 保存为 a2a-request.json,替换所有标识,再运行:
curl --fail-with-body "$PRODUCT_API_BASE_URL/agents/a2a" -H "X-API-Key: $PRODUCT_API_KEY" -H "X-Workspace-ID: $WORKSPACE_ID" -H 'Content-Type: application/json' --data-binary @a2a-request.json
该入口通过 X-Workspace-ID 指定本次工作区,通过请求体的 agent_id 选择智能体。HTTP 成功后仍需检查 JSON-RPC 错误及任务状态。基础协议见通过 A2A 调用智能体。
发送图片¶
先将 PNG 上传到当前工作区的 Catalog 卷,保留所属根卷、文件与工作区 ID,并选择可用视觉模型。volume_id 的 123 是示例值,须替换为真实正整数。片段中的 URI、文件 ID 与目录身份要指向同一文件。
{
"agent_id": "<智能体 ID>",
"jsonrpc": "2.0",
"id": "<请求 ID>",
"method": "message/send",
"params": {
"model": "<视觉模型名称>",
"message": {
"kind": "message",
"role": "user",
"messageId": "<消息 ID>",
"parts": [
{
"kind": "text",
"text": "请描述图中的标签和数值。"
},
{
"kind": "file",
"file": {
"uri": "moi://files/<图片文件 ID>",
"mimeType": "image/png",
"name": "chart.png"
},
"metadata": {
"file_id": "<图片文件 ID>"
}
}
]
},
"metadata": {
"files": [
{
"catalog_file": {
"workspace_id": "<当前工作区 ID>",
"volume_id": 123,
"file_id": "<图片文件 ID>"
}
}
]
}
}
}
返回任务后保存 id 和 contextId,并按文末方法查询状态与回答。文件受理不代表识别完成;本地路径、任意下载 URL 和成果 ID 不能替代此目录文件身份。
重新生成已完成的回答¶
从原任务读取 id、contextId,确认其状态为 completed。为本次操作生成并保存控制 ID 和消息 ID,按需求填写修改要求。示例采用 branch 保留对话分支。重新生成可能再次执行工具,提交前确认外部写入影响。
{
"agent_id": "<原智能体 ID>",
"jsonrpc": "2.0",
"id": "<请求 ID>",
"method": "message/send",
"params": {
"message": {
"kind": "message",
"role": "user",
"messageId": "<本次控制消息 ID>",
"taskId": "<已完成原任务 ID>",
"contextId": "<原 contextId>",
"parts": [
{
"kind": "data",
"data": {
"type": "moi.run.control",
"version": 1,
"controlId": "<本次控制 ID>",
"action": "regenerate",
"rerunMode": "same_manifest",
"conversationMode": "branch",
"guidance": "缩短句子,并保留全部来源引用。",
"target": {
"agentId": "<原智能体 ID>",
"contextId": "<原 contextId>",
"taskId": "<已完成原任务 ID>"
}
}
}
]
}
}
}
响应可能为新任务,或为 kind=message、数据类型为 moi.run.control.result 的确认。前者使用任务 id;后者从相同 controlId 的数据中取得新 taskId。查询新任务确认结果。响应不明确时保留原请求与标识,避免创建重复操作。
答复工具输入请求¶
读取处于 input-required 的任务。在 status.message.parts 的 moi.tool.call 数据中取得 inputRequestId 和 arguments.questions。使用当前待答复请求及真实问题 ID:
{
"agent_id": "<原智能体 ID>",
"jsonrpc": "2.0",
"id": "<请求 ID>",
"method": "matrixflow/input.submit",
"params": {
"taskId": "<等待输入的任务 ID>",
"requestId": "<当前 inputRequestId>",
"answers": {
"<真实问题 ID>": {
"answers": [
"<实际答案>"
]
}
}
}
}
requestId 使用当前 inputRequestId,不是 JSON-RPC 请求 ID。服务端校验必填、选项和类型;答案提交后仍需跟踪原任务。
答复供应商交互¶
当数据类型为 moi.provider_interaction.required 时,使用原交互的 requestId、target 和 payload 结构。下例只适用于原交互要求这种问答 payload 的情况:
{
"agent_id": "<原智能体 ID>",
"jsonrpc": "2.0",
"id": "<请求 ID>",
"method": "message/send",
"params": {
"message": {
"kind": "message",
"role": "user",
"messageId": "<消息 ID>",
"contextId": "<原 contextId>",
"parts": [
{
"kind": "data",
"data": {
"type": "moi.provider_interaction.respond",
"version": 1,
"requestId": "<原交互 requestId>",
"target": {
"agentId": "<原智能体 ID>",
"contextId": "<原 contextId>",
"taskId": "<原任务 ID>"
},
"payload": {
"answers": {
"<真实问题 ID>": {
"answers": [
"<实际答案>"
]
}
}
}
}
}
]
}
}
}
取消该交互时,在数据中使用 cancelled:true 并省略 payload,不能同时提交两者。收到 moi.provider_interaction.received 只表示答复已接收;之后继续查询原任务。对结果未确认的答复,先检查原交互状态,不更换请求标识重复提交。
查询结果¶
将真实目标任务 ID 写入请求,按本页相同调用方式提交:
{
"agent_id": "<同一智能体 ID>",
"jsonrpc": "2.0",
"id": "<查询请求 ID>",
"method": "tasks/get",
"params": {
"id": "<目标任务 ID>"
}
}
completed 后检查答案和成果;submitted、working 继续跟踪;input-required、auth-required 分别处理输入或授权。错误按 JSON-RPC 的代码与消息排查。
可运行示例见 SDK 发送图片消息、重新生成回答、提交交互答复 和 CLI 智能体、会话与自动化。
随消息选择技能与知识库¶
从当前工作区的技能和智能体知识库列表选择资源,使用相应资源 ID。以下元数据与发送消息一起提交;长期绑定仍通过智能体绑定接口维护。
{
"agent_id": "<agent-id>",
"jsonrpc": "2.0",
"id": "<request-id>",
"method": "message/send",
"params": {
"model": "<available-model-name>",
"message": {
"kind": "message",
"role": "user",
"messageId": "<message-id>",
"parts": [
{
"kind": "text",
"text": "Answer using the selected knowledge base and skill."
}
]
},
"metadata": {
"homepage_skill_refs": [
{
"id": "<skill-id>",
"workspace_id": "<current-workspace-id>"
}
],
"homepage_extras": {
"kbs": [
{
"id": "<agent-knowledge-base-id>",
"workspace_id": "<current-workspace-id>"
}
]
}
}
}
}
技能可按已开放范围引用当前工作区或系统资源,知识库引用属于当前工作区。服务端校验实际资源、启用状态和权限。同一对话可保留历史选择;需要隔离范围时开始新上下文。SDK 用法见 调用智能体与跟踪任务。