Blender云端渲染接入AI Agent：5秒MCP超时的坑与解法

AI Agent要真正干活，光会写代码还不够，还得能操控外部工具。让Agent跑Blender渲染就是一个典型场景——它需要上传场景、估算耗时、提交任务、轮询状态、下载成片。JANCTION Render把整套流程封装成了MCP Server，OpenAI Agents SDK和LangChain都能直接调用。但第一次跑通之前，几乎所有人都会撞上同一个报错。

一个5秒超时引发的失败

用OpenAI Agents SDK的MCPServerStreamableHttp连接渲染服务时，默认的工具调用超时是5秒（client_session_timeout_seconds=5）。问题在于，渲染工具只有在图片真正生成后才会返回结果，而排队时间并不计入响应。

官方给出的实测数据很能说明问题：对示例场景调用render_preview并带四个光照预设，默认5秒超时的情况下，5.1秒后直接抛出McpError: Timed out while waiting for response to ClientRequest. Waited 5.0 seconds.；把超时改成120秒后，同一任务在7.3秒返回结果，实际消耗4.03 GPU秒。

更隐蔽的是，如果场景只用一个预设，返回时间在4.7到5.0秒之间——刚好卡在默认超时边缘。这意味着快速测试时一切正常，一旦换成真实场景立刻失败。显式设置超时不是优化项，而是必选项。

MCP（Model Context Protocol） 是 Anthropic 于 2024 年底提出并开源的协议，用于在 LLM 应用与外部工具、数据源之间建立统一的调用契约。它把工具、资源和提示模板抽象成标准原语，通过 JSON-RPC 传输，让同一个 Server 能被不同框架复用。

MCP 支持多种传输层：stdio 用于本地进程，streamable_http 则用于远程 HTTP 服务，支持流式响应和会话管理。由于 MCP 采用请求-响应模型，客户端在发出 tools/call 后会等待服务端返回，中间没有进度推送，因此当工具执行时间超过客户端配置的超时阈值时，连接就会被判定为失败并抛出 McpError。这正是本文 5 秒默认超时踩坑的根本原因——协议本身没有「后台执行」语义，长耗时只能靠超时设置和 job id 轮询两种手段配合解决。

OpenAI Agents SDK接入方式

服务端点是远程MCP Server：https://render.janction.jp/mcp。认证用Bearer Token，调用curl -s -X POST https://render.janction.jp/v1/keys即可获取，无需注册。

连接代码的关键改动只有一处——把client_session_timeout_seconds设为120：

async with MCPServerStreamableHttp(name="janction-render", client_session_timeout_seconds=120,
                                   params={"url": "https://render.janction.jp/mcp",
                                           "headers": {"Authorization": "Bearer jr_..."}}) as render:
    agent = Agent(name="3D artist", instructions="Render Blender scenes with janction-render.", mcp_servers=[render])
    result = await Runner.run(agent, "Render a preview of https://render.janction.jp/samples/cube_scene.py")

Agent会看到12个可用工具，典型调用链是scene_info → render_preview → render_estimate → render_final → render_status → render_download。这里有个容易被忽略的设计：长渲染并不需要更长的超时。短视频任务一次调用直接返回链接，长任务返回job id，再用render_download(job_id, wait_seconds=45)每次最多等45秒。120秒足以覆盖所有工具。

MCPServerStreamableHttp 是 OpenAI Agents SDK 提供的 MCP 客户端封装，其 client_session_timeout_seconds 参数控制的是底层 MCP 会话等待单次请求响应的最长时间，而非整个 Agent 运行的总时长。需要区分的是：Agent 的 Runner.run 有自己的 run-level 超时（默认通常较长或无限），而每个工具调用都受 MCP 会话超时单独约束。两者层级不同、互不覆盖。

因此即便把 client_session_timeout_seconds 调大，也不会拖慢快速工具的响应——它只是放宽了「等待上限」，只有在请求真正耗时才起作用。反之，如果只调 run-level 超时而忽略会话超时，工具调用仍会在 5 秒处被拦腰截断。理解这一层级关系，是排查所有 MCP 超时问题的关键。

LangChain接入方式

使用langchain-mcp-adapters（0.3.2），同一个服务器作为MultiServerMCPClient的一个条目。传输层名称为streamable_http：

client = MultiServerMCPClient({"janction-render": {"url": "https://render.janction.jp/mcp", "transport": "streamable_http",
                                                   "headers": {"Authorization": "Bearer jr_..."}}})
tools = await client.get_tools()

获取到的工具列表包含render_preview、render_final、render_status、render_download等。整体接入逻辑与OpenAI Agents SDK一致，区别只在于框架层的封装方式。

不用Agent框架的纯Python方案

如果渲染逻辑由代码自己决定，只需要拿到成片，Python客户端更简短。pip install janction-render后，首次调用会自动创建免费key并存放在~/.janction-render.json：

from janction_render.client import Client

c = Client()
scene = c.upload("scene.py")  # 支持bpy脚本、.blend".glb".fbx".usd".obj
job = c.submit(scene["scene_id"], kind="final", frame_start=1, frame_end=48, output="mp4")
job = c.wait(job["job_id"], timeout=1800)
print(job["status"], c.download(job["job_id"], "out", only="mp4"))

面向服务而非脚本的场景，可以在POST /v1/jobs时传入notify_url（必须https），任务完成后收到一次JSON POST回调，免去轮询；同时发送Idempotency-Key请求头，避免重试时意外启动第二个任务。

成本结构与Agent预算控制

每个新key赠送500日元GPU时间（5000 GPU秒），有效期14天，不需要绑卡。之后预览任务每天免费2 GPU分钟，其他GPU时间按0.1日元/GPU秒计费。官方实测一个24帧720p MP4、64采样约消耗58 GPU秒，折合约6日元。

额度耗尽时，任务在运行前就被拒绝——HTTP API返回402并附带充值链接，MCP的工具结果里也会带上同样的链接供人工打开。每个key还设有单任务和单日消费上限，这对让Agent自主花钱的场景是个必要的护栏。

GPU 秒（GPU-second） 是渲染、训练等 GPU 密集型服务常用的计费单位，指任务实际占用 GPU 的时间总量，与墙钟时间（wall-clock time）不同：多个任务并行时墙钟时间重叠，但各自的 GPU 秒独立累加。例如一个任务占满一块 GPU 跑 10 秒，消耗 10 GPU 秒；若只占用半个 GPU 算力跑 10 秒，则计 5 GPU 秒。

文章中「4.03 GPU 秒」就是这个含义——从提交到返回的 7.3 秒墙钟时间里，包含了排队、调度和 I/O 等非计算开销，真正计入账单的只有 GPU 实际工作的 4.03 秒。这种计费方式对 Agent 场景友好：排队等待不会烧钱，但也意味着不能通过「多排队」来降低费用。理解 GPU 秒与墙钟时间的区别，是估算 Agent 渲染成本和设定预算护栏的前提。

核心启示

这个案例真正有价值的地方不在于渲染服务本身，而在于它暴露了LLM Agent调用外部工具时的一个通用陷阱：框架的默认超时通常为交互式调用设计，而真实工具的执行时间往往不可预测。 凡是涉及渲染、编译、数据处理等耗时任务的MCP工具，都应该在接入时显式配置超时。同时，用job id加轮询下载的方式处理长任务，比单纯拉长超时要更稳健——既不会占用Agent的会话时间，也更容易做失败重试。