Send images, regenerate answers, and respond to interactions

Use the same A2A endpoint for images and control messages. Read the original task or pending interaction and preserve its task, context, and request identifiers before submitting.

Prepare and call

Configure credentials and workspace using API call basics. Select an agent through Agent discovery. Examples select an agent in the current workspace.

Save one complete request below as a2a-request.json, replace all identifiers, then run:

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

This entry point selects the workspace through X-Workspace-ID and the agent through request-body agent_id. After HTTP success, still check JSON-RPC errors and task state. See invoke an agent through A2A for the base protocol.

Send an image

Upload the PNG to a Catalog volume in the current workspace, retain its root volume, file, and workspace IDs, and select an available vision model. The volume_id value 123 is an example; replace it with an actual positive integer. The URI, file ID, and catalog identity in the snippet must identify the same file.

{
  "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>"
          }
        }
      ]
    }
  }
}

Save returned task id and contextId, then query state and answers as described at the end of the page. File acceptance does not mean recognition is complete. Local paths, arbitrary download URLs, and result IDs do not replace this Catalog file identity.

Regenerate a completed answer

Read id and contextId from the original task and confirm completed. Generate and retain a control ID and message ID for this operation, then enter the requested changes. The example uses branch to retain a conversation branch. Regeneration can execute tools again, so review external write effects before submitting.

{
  "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>"
            }
          }
        }
      ]
    }
  }
}

The response may be a new task or an acknowledgment with kind=message and data type moi.run.control.result. For a task, use its id; for an acknowledgment, obtain the new taskId from data with the same controlId. Query the new task to confirm the result. If ambiguous, retain the original request and IDs to avoid duplicate operations.

Answer a tool input request

Read a task in input-required. In status.message.parts, find moi.tool.call data and obtain inputRequestId and arguments.questions. Use the current pending request and actual question IDs:

{
  "agent_id": "<原智能体 ID>",
  "jsonrpc": "2.0",
  "id": "<请求 ID>",
  "method": "matrixflow/input.submit",
  "params": {
    "taskId": "<等待输入的任务 ID>",
    "requestId": "<当前 inputRequestId>",
    "answers": {
      "<真实问题 ID>": {
        "answers": [
          "<实际答案>"
        ]
      }
    }
  }
}

Use the current inputRequestId as requestId, rather than the JSON-RPC request ID. The service validates required values, options, and types. Continue tracking the original task after submitting answers.

Respond to a provider interaction

For data type moi.provider_interaction.required, use the original interaction’s requestId, target, and payload structure. The following example applies only when the original interaction requires this question-and-answer 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": [
                    "<实际答案>"
                  ]
                }
              }
            }
          }
        }
      ]
    }
  }
}

To cancel the interaction, send cancelled:true and omit payload; do not include both. A moi.provider_interaction.received acknowledgement confirms receipt only. Inspect the original task afterward. Check the original interaction after an unconfirmed outcome rather than changing identifiers and resubmitting.

Query results

Submit the real task ID using the same endpoint:

{
  "agent_id": "<同一智能体 ID>",
  "jsonrpc": "2.0",
  "id": "<查询请求 ID>",
  "method": "tasks/get",
  "params": {
    "id": "<目标任务 ID>"
  }
}

After completed, check the answer and outputs. Continue tracking submitted and working; handle input for input-required and authorization for auth-required. Diagnose errors using the JSON-RPC code and message.

For runnable examples, see the SDK guides Send Image Messages, Regenerate Agent Replies, and Submit Interactive Replies, and the CLI guide Agents, Conversations, and Automations.

Select skills and knowledge bases with a message

Select resources from the workspace skill and agent knowledge-base lists. Submit their IDs with the message. Maintain persistent bindings through the agent binding API.

{
  "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>"
          }
        ]
      }
    }
  }
}

Skills may reference available resources in the current/system workspace; knowledge base references belong to the current workspace. The server validates actual resources, enabled state, and privileges. One conversation may retain historical selections. Start a new context when scope isolation is needed. For SDK usage, see Invoke Agents and Track Tasks.

Last updated on