发送图片消息

将工作区卷中的图片与问题一同发送给智能体,再读取返回的任务状态与识别结果。图片理解需要所选模型具备视觉输入能力。

任务流程

工作区卷图片(volume_id + file_id)+ 视觉模型
                    │
                    ▼
     构造含文件片段与目录引用的 A2A 消息
                    │
                    ▼
          发送请求并获取任务 ID
                    │
                    ▼
    确认状态为 completed 后核对识别成果

准备

  1. 已完成 使用 SDK 中的服务地址、个人访问令牌与工作区配置。

  2. 已通过 发现与选择智能体 选择当前工作区中的智能体并记录其 ID。

  3. 选择具备视觉输入能力的模型名称:可通过 workspace.agents().resource_get("llm", "/models", sdk.with_query_param("type", "vision"))(Go 为 workspace.Agents().ResourceGet(ctx, "llm", "/models", sdk.WithQueryParam("type", "vision")))查询已声明的模型名称,并确认后端服务实际支持视觉输入(模型后端查看方式见 查看模型后端与端点)。

  4. 已通过 管理卷和文件 将 PNG 图片上传到当前工作区卷(或选择已有可读图片),记录所属根卷 ID(正整数)和文件 ID。

在终端设置运行参数:

export AGENT_ID='<智能体 ID>'
export AGENT_MODEL='<支持视觉输入的模型名称>'
export IMAGE_VOLUME_ID='<图片所属根卷 ID>'
export IMAGE_FILE_ID='<图片文件 ID>'

发送图片并检查结果

示例将文本片段与 moi://files/<file_id> 文件片段放在同一条 A2A 消息中,并在 metadata.files 中声明对应的工作区卷文件身份。更换图片格式时,需同步修改 mimeType 与显示文件名,使文件内容、URI 与目录身份指向同一文件。

import json
import os
import uuid

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
workspace = client.workspace(os.environ["WORKSPACE_ID"])
agent = workspace.agent_by_id(os.environ["AGENT_ID"])

file_id = os.environ["IMAGE_FILE_ID"]
volume_id = int(os.environ["IMAGE_VOLUME_ID"])
message_id = str(uuid.uuid4())
print("message_id:", message_id)

params = {
    "model": os.environ["AGENT_MODEL"],
    "message": {
        "kind": "message",
        "role": "user",
        "messageId": message_id,
        "parts": [
            {
                "kind": "text",
                "text": "请描述这张图片中的可见标签和数值。",
            },
            {
                "kind": "file",
                "file": {
                    "uri": "moi://files/" + file_id,
                    "mimeType": "image/png",
                    "name": "chart.png",
                },
                "metadata": {"file_id": file_id},
            },
        ],
    },
    "metadata": {
        "files": [
            {
                "catalog_file": {
                    "workspace_id": os.environ["WORKSPACE_ID"],
                    "volume_id": volume_id,
                    "file_id": file_id,
                }
            }
        ]
    },
}

try:
    result = agent.a2a(
        sdk.A2ARequest("message/send", id_=str(uuid.uuid4()), params=params)
    )
except sdk.Error as error:
    if error.details.get("task_id"):
        print("task_id:", error.details["task_id"])
    raise

payload = sdk.agent_a2a_payload(result)
if payload.get("kind") != "task":
    raise RuntimeError("Expected a task response; inspect returned message payload")

print("task_id:", payload.get("id"))
print("contextId:", payload.get("contextId"))
print("state:", payload.get("status", {}).get("state"))
print(
    "status message:",
    json.dumps(payload.get("status", {}).get("message"), ensure_ascii=False),
)
for artifact in payload.get("artifacts", []):
    print("artifactId:", artifact.get("artifactId"))
    print("parts:", json.dumps(artifact.get("parts", []), ensure_ascii=False))
package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"strconv"
	"time"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	defer client.Close()

	workspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	agent, err := workspace.AgentByID(os.Getenv("AGENT_ID"))
	if err != nil {
		panic(err)
	}

	fileID := os.Getenv("IMAGE_FILE_ID")
	volumeID, err := strconv.ParseInt(os.Getenv("IMAGE_VOLUME_ID"), 10, 64)
	if err != nil || volumeID <= 0 {
		panic("IMAGE_VOLUME_ID must be a positive integer")
	}
	messageID := fmt.Sprintf("image-%d", time.Now().UnixNano())
	fmt.Println("message_id:", messageID)

	params, err := json.Marshal(map[string]any{
		"model": os.Getenv("AGENT_MODEL"),
		"message": map[string]any{
			"kind":      "message",
			"role":      "user",
			"messageId": messageID,
			"parts": []any{
				map[string]any{
					"kind": "text",
					"text": "请描述这张图片中的可见标签和数值。",
				},
				map[string]any{
					"kind": "file",
					"file": map[string]any{
						"uri":      "moi://files/" + fileID,
						"mimeType": "image/png",
						"name":     "chart.png",
					},
					"metadata": map[string]any{"file_id": fileID},
				},
			},
		},
		"metadata": map[string]any{
			"files": []any{
				map[string]any{
					"catalog_file": map[string]any{
						"workspace_id": os.Getenv("WORKSPACE_ID"),
						"volume_id":    volumeID,
						"file_id":      fileID,
					},
				},
			},
		},
	})
	if err != nil {
		panic(err)
	}

	result, err := agent.A2A(ctx, sdk.A2ARequest{
		JSONRPC: "2.0",
		ID:      fmt.Sprintf("request-%d", time.Now().UnixNano()),
		Method:  sdk.A2AMethodSend,
		Params:  params,
	})
	if err != nil {
		var apiError *sdk.Error
		if errors.As(err, &apiError) && apiError.Details["task_id"] != "" {
			fmt.Println("task_id:", apiError.Details["task_id"])
		}
		panic(err)
	}

	payload, err := sdk.AgentA2APayload(result)
	if err != nil {
		panic(err)
	}
	if payload["kind"] != "task" {
		panic("Expected a task response; inspect returned message payload")
	}
	fmt.Println("task_id:", payload["id"], "contextId:", payload["contextId"])
	status, _ := payload["status"].(map[string]any)
	fmt.Println("state:", status["state"])
	message, _ := json.Marshal(status["message"])
	fmt.Println("status message:", string(message))
	artifacts, _ := json.Marshal(payload["artifacts"])
	fmt.Println("artifacts:", string(artifacts))
}

限制和注意事项

  • 任务状态到达 completed 后,再核对 artifacts 中的识别内容;状态为 input-required 或 auth-required 时需先完成对应交互或授权。

  • 等待超时但错误详情已返回 task_id 时,先按任务 ID 回查进度,避免重复提交同一图片请求。

  • catalog_file 必须引用当前工作区卷中的可读文件;本地磁盘路径、智能体成果 ID 或其他工作区的文件 ID 无法直接替代。

下一步

最后更新于