通过 MCP 连接 Agent
让 Agent 观察机器人、运行任务，并通过工具完成标定与手动运动。
完成 安装 后，支持 MCP 的 Agent 可连接本地 RoboAPI，与控制台共用设备和配置。本页列出 0.4.5 提供的 27 个工具。
连接 Agent
同时启动本地控制台和网络 MCP：
roboapi http --with-mcpMCP 默认地址为 http://127.0.0.1:8000/mcp，网页为 http://127.0.0.1:8080/。从另一台电脑访问时，转发两个端口；不要再启动一个占用相同硬件的进程。
stdio 客户端可在控制电脑使用以下配置，将 command 换成安装环境内的绝对路径：
{"mcpServers":{"roboapi":{"command":"/absolute/path/to/.venv/bin/roboapi","args":["serve"]}}}serve 默认也启动 8080 网页。配置属于启动进程的账户；切换启动模式前停止现有服务。
运行任务
已完成 坐标标定 并启用控制后，让 Agent 依次观察、开始任务、观察执行结果，最后停止。
| 工具签名 | 作用 |
|---|---|
robot_get_observation(with_image=true) | 返回状态与腕部图像；false 用于轻量状态查询 |
robot_start_policy(instruction) | 开始任务并立即返回，机器人在后台持续运行 |
robot_set_instruction(instruction) | 更新运行／暂停中的活动指令，下一轮推理生效，不截断当前动作块 |
robot_pause(with_image=true) | 暂停目标发送，保持当前位置，返回观测 |
robot_resume() | 重新观测后恢复已暂停的运行 |
robot_stop(with_image=true) | 停止策略或受控运动，返回观测 |
运行不会自动超时结束，一次推理成功也不表示任务已完成。持续用 robot_get_observation 观察结果，并显式停止。
更新、暂停与恢复须来自发起运行的入口。网页来源的运行先停止，再由 Agent 开始；Agent 运行时网页保留停止能力。
停止后用相同指令再次开始，会继续当前本地任务的记录与录像，但开始新的一次运行。不同指令创建新的本地任务。robot_start_policy 只有 instruction 参数，不接受 HTTP API 的 new_task 参数。
模型设置
| 工具签名 | 作用 |
|---|---|
robot_get_policy_config() | 读取模型地址、ID、动作块间隔及凭据是否配置，不返回 Key 原值 |
robot_configure_policy(url, model, inter_chunk_pause_s, api_key=None) | 空闲时保存完整模型设置；省略 api_key 保留现有凭据 |
工具参数示例：
robot_configure_policy(
url="https://api.pokebot.com/v1",
model="MODEL_ID",
inter_chunk_pause_s=0.5,
)Base URL 使用正式服务地址 https://api.pokebot.com/v1，模型 ID 使用该服务 /models 返回的值。保存前检查 /models，失败保留原配置。inter_chunk_pause_s 为非负秒数，默认 0.5；设为 0 不改变动作的 30 Hz 执行频率。协议要求见 连续任务与会话。
标定与设备
按照 坐标标定 的现场步骤调用。除启用控制外，下列标定工具默认 with_image=false。
| 工具签名 | 作用 |
|---|---|
robot_calibration_status(with_image=false) | 读取阶段、采样、控制状态与本机 profile_file |
robot_calibration_begin(safety_confirmed, with_image=false) | 开始示教，确认采 C 后允许自动返回 |
robot_calibration_accept_home(with_image=false) | 记录 Home |
robot_calibration_set_guiding_axis(axis, with_image=false) | Franka 选择 x、y 或 z 原生平移轴；先松开引导按钮 |
robot_calibration_accept_plane_a(with_image=false) | 记录台面 A 点 |
robot_calibration_accept_plane_b(with_image=false) | 记录台面 B 点，A→B 定义任务 +X |
robot_calibration_accept_plane_c(with_image=false) | 记录台面 C 点并自动返回 Home，会移动机械臂 |
robot_calibration_return_a(with_image=false) | B/C 阶段返回 A，会移动机械臂 |
robot_calibration_return_home(with_image=false) | 重试返回 Home，保留采样点，会移动机械臂 |
robot_calibration_finish(save_confirmed, with_image=false) | 成功返回后保存标定，不启用控制 |
robot_calibration_undo(with_image=false) | 撤回最近一个未保存的记录，不移动机械臂；保留更早的记录与已保存标定 |
robot_calibration_enable_control(safety_confirmed, initialization_confirmed, with_image=true) | 使用已保存标定启用控制，可能初始化并移动夹爪 |
robot_disconnect() | 空闲时释放设备、丢弃未完成的示教，保留已保存标定 |
MCP 的记录 C、保存和启用控制是三个独立步骤。确认参数须来自现场操作人的实际确认；不能仅因 Agent 要完成任务而自动设为 true。已保存的标定不能用 undo 撤回，需重新标定。
方向试动
| 工具签名 | 作用 |
|---|---|
robot_get_direction_check() | 返回 at_home 和 active，不运动 |
robot_check_direction(direction, with_image=true) | forward、left、up 或 home；执行完毕后返回观测 |
控制须就绪且空闲。前三种试动从 Home 出发，分别向 −Y／+X／+Z 平移 5 cm，伴随 Roll −30°／Pitch −30°／Yaw +30°，然后返回 Home。home 仅返回；所有试动保持夹爪开度，不调用模型。
Stop 会取消剩余轨迹，包括回程。停止后先显式返回 Home，再进行下一次试动。可用 方向试动说明 对照动作。
手动运动
| 工具签名 | 作用 |
|---|---|
robot_move_to_pose(x=None, y=None, z=None, roll=None, pitch=None, yaw=None, gripper=None, relative=false, with_image=true) | 到达指定位姿；省略的分量保持当前值 |
robot_move_waypoints(waypoints, with_image=true) | 按非空 waypoint 列表执行有序路径 |
robot_reset(with_image=true) | 打开夹爪并返回 Home |
robot_recover(with_image=true) | 恢复硬件并返回 Home |
这些工具会实际运动。位姿与路径运动须空闲、已标定且控制就绪。
| 位姿参数／waypoint 字段 | 语义 |
|---|---|
x、y、z | 模型坐标中的位置，单位米 |
roll、pitch、yaw | 绕模型 X／Y／Z 轴的角度，单位度 |
gripper | [0,1] 开度，始终为绝对值；省略时保持开度 |
relative | 默认 false；true 为相对偏移。单点相对当前位置，路径中相对前一目标，首点相对当前位置 |
blend | 仅 waypoint 支持，单位米；默认 arm.blend_radius 为 0.02；0 表示到点停，末点始终停 |
每个 waypoint 省略的分量沿用前一点。未知字段被拒绝；with_image 是工具参数，不是 waypoint 字段。
活动范围 对位姿与路径目标同样生效。越界目标收敛到边界，后续相对 waypoint 从收敛后的有效目标继续计算。普通运动从范围内开始；显式 Home 可从范围外返回。路径不执行障碍物检测。
活动范围在控制台或 HTTP API 配置；本版本没有配置活动范围的 MCP 工具。
处理失败
已知运行条件返回结构化对象：
{"ok":false,"error":"loop_running","hint":"call stop() first","detail":"..."}按 本地运行错误 处理 loop_running、calibration_required、control_not_ready 与 policy_unavailable。其他异常可能以 MCP ToolError 返回。失败或请求超时后先观察当前状态，避免重复执行运动。