发送图片消息¶
将工作区卷中的图片与问题一同发送给智能体,再读取返回的任务状态与识别结果。图片理解需要所选模型具备视觉输入能力。
任务流程¶
工作区卷图片(volume_id + file_id)+ 视觉模型
│
▼
构造含文件片段与目录引用的 A2A 消息
│
▼
发送请求并获取任务 ID
│
▼
确认状态为 completed 后核对识别成果
准备¶
已完成 使用 SDK 中的服务地址、个人访问令牌与工作区配置。
已通过 发现与选择智能体 选择当前工作区中的智能体并记录其 ID。
选择具备视觉输入能力的模型名称:可通过
workspace.agents().resource_get("llm", "/models", sdk.with_query_param("type", "vision"))(Go 为workspace.Agents().ResourceGet(ctx, "llm", "/models", sdk.WithQueryParam("type", "vision")))查询已声明的模型名称,并确认后端服务实际支持视觉输入(模型后端查看方式见 查看模型后端与端点)。已通过 管理卷和文件 将 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 无法直接替代。