# 发送图片消息

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

(sdk-ai-studio-agent-image-flow)=
## 任务流程

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

(sdk-ai-studio-agent-image-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. 已通过 [发现与选择智能体](发现与选择智能体.md#sdk-ai-studio-agents-s1) 选择当前工作区中的智能体并记录其 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"))`）查询已声明的模型名称，并确认后端服务实际支持视觉输入（模型后端查看方式见 [查看模型后端与端点](../资源中心/管理模型后端.md)）。
4. 已通过 [管理卷和文件](../资源中心/管理卷和文件.md#sdk-ai-studio-volume-file-upload) 将 PNG 图片上传到当前工作区卷（或选择已有可读图片），记录所属根卷 ID（正整数）和文件 ID。

在终端设置运行参数：

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

(sdk-ai-studio-agent-image-send)=
## 发送图片并检查结果

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

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
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))
```

::::

::::{tab-item} Go
:sync: go

```go
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))
}
```

::::

:::::

(sdk-ai-studio-agent-image-follow)=
## 限制和注意事项

- 任务状态到达 `completed` 后，再核对 `artifacts` 中的识别内容；状态为 `input-required` 或 `auth-required` 时需先完成对应交互或授权。
- 等待超时但错误详情已返回 `task_id` 时，先按任务 ID 回查进度，避免重复提交同一图片请求。
- `catalog_file` 必须引用当前工作区卷中的可读文件；本地磁盘路径、智能体成果 ID 或其他工作区的文件 ID 无法直接替代。

(sdk-ai-studio-agent-image-next)=
## 下一步

- [调用智能体与跟踪任务](调用智能体并跟踪任务.md#sdk-ai-studio-agent-task-continue)
- [重新生成回答](重新生成智能体回答.md#sdk-ai-studio-agent-regenerate-prepare)
