附件与多模态输入

KsADK 把文本、图片、文件和上传附件在进入框架 runner 之前归一化。本地 UI、Hosted 托管上传、Responses / Chat Completions / ADK 风格 part 都收敛到同一条 attachment 解析路径。

推荐做法

• 图片分析优先交给支持视觉的模型（见默认多模态模型）。
• 大文件不要直接塞进 prompt，先抽取摘要或结构化内容。
• 工具需要文件时使用 workspace 或附件引用，不猜测浏览器上传路径。
• 不把附件二进制写入长期记忆。

输入类型

常见协议形态：

{"type": "input_text", "text": "..."}

{"type": "input_image", "image_url": "data:image/png;base64,..."}

{"type": "input_file", "filename": "note.txt", "file_data": "data:text/plain;base64,..."}

业务 Agent 应处理缺失、过期或不支持的附件引用，并给出明确错误。

URI Scheme 与统一解析

统一解析的收益：

• 会话切换或浏览器刷新后，runner 与 workspace preview 仍能通过 file_uri 读到真实文件内容。
• Hosted 附件首次解析后会被物化到本地 files/ 目录，后续读取走本地 cache，不再重复远端下载。
• 业务代码不需要区分本地与 Hosted：拿到 file_uri 后交给运行时解析即可。

AttachmentContent 端点

Hosted 托管 runtime 通过 KOP Action 端点下载 ae-upload:// 附件字节流：

GET /agentengine/api/v1/AttachmentContent?FileUri=<uri>

响应为字节流，Content-Type 反映真实 MIME，Content-Disposition 携带原始文件名。

业务 Agent 消费建议

业务 Agent 应直接消费 runner payload 里的结构化附件字段，不猜测上传路径或自行解析 file_uri：

def ksadk_prepare_state(payload: dict, session_context: dict) -> dict:
    return {
        "messages": payload.get("input_messages", []),
        # 仅当前 turn 新上传的文件
        "files": payload.get("current_attachment_results", []),
        # follow-up 仍可引用的历史附件上下文
        "file_context": payload.get("attachment_results", []),
    }

• 「处理我刚上传的文件」这类工作流用 current_attachment_results。
• 「现在总结第二段」这类 follow-up 用 attachment_results，文本后续轮次 current_attachment_results 预期为空。
• 工具需要文件句柄时，从 current_attachments / attachments 拿 file_uri 交给运行时统一解析，不要拼接本地绝对路径。

默认多模态模型

显式请求级模型参数 > 显式环境变量 > 策略默认值。

会话与刷新后继续读取

只要 file_uri 仍有效（本地 cache 或 Hosted ae-upload:// 可解析），刷新或会话恢复后 runner 与 workspace preview 都能继续读到真实文件内容，业务代码无需特殊处理。