OpenAI Agents SDK #30：HostedTool 收官三件套——ComputerTool × CodeInterpreterTool × LocalShellTool 完整拆解

ComputerTool：让 Agent 操控你的桌面

dataclass 结构

@dataclass(eq=False)
class ComputerTool(Generic[ComputerT]):
    computer: ComputerT | ComputerCreate[ComputerT] | ComputerProvider[ComputerT]
    on_safety_check: Callable[[ComputerToolSafetyCheckData], MaybeAwaitable[bool]] | None = None

@dataclass
class ComputerProvider(Generic[ComputerT]):
    create: ComputerCreate[ComputerT]     # 创建钩子，接收 run_context
    dispose: ComputerDispose[ComputerT] | None = None  # 清理钩子，默认 None

on_safety_check：人工审核阀门

@dataclass
class ComputerToolSafetyCheckData:
    ctx_wrapper: RunContextWrapper[Any]   # 当前 run 上下文
    agent: Agent[Any]                     # 发出动作的 Agent
    tool_call: ResponseComputerToolCall   # 完整的工具调用对象（含动作类型和坐标等）
    safety_check: PendingSafetyCheck      # 待确认的安全检查项

工具 name 的历史注释

@property
def name(self):
    # Keep the released preview-era runtime name for hooks and persisted
    # RunState compatibility.
    return "computer_use_preview"

@property
def trace_name(self):
    # Tracing should display the GA tool alias even while runtime names preserve compatibility.
    return "computer"

CodeInterpreterTool：沙盒代码执行，跑在 OpenAI 云端

dataclass 结构

@dataclass
class CodeInterpreterTool:
    tool_config: CodeInterpreter

class CodeInterpreter(TypedDict, total=False):
    container: Required[CodeInterpreterContainer]
    type: Required[Literal["code_interpreter"]]  # 固定值

class CodeInterpreterContainerAuto(TypedDict, total=False):
    type: Required[Literal["auto"]]         # 固定值
    file_ids: SequenceNotStr[str]           # 可供代码访问的文件 ID 列表（可选）
    memory_limit: Literal["1g","4g","16g","64g"] | None  # 内存上限（可选）
    network_policy: ContainerNetworkPolicy  # 网络访问策略（可选）

四个配置维度

代码示例

from agents import Agent, CodeInterpreterTool, Runner
from openai.types.responses.tool_param import CodeInterpreter

agent = Agent(
    name="DataAnalyst",
    instructions="你是一个数据分析助手，可以执行 Python 代码分析数据。",
    tools=[
        CodeInterpreterTool(
            tool_config=CodeInterpreter(
                type="code_interpreter",
                container={
                    "type": "auto",
                    "file_ids": ["file-abc123"],  # 预先上传的数据文件
                    "memory_limit": "4g",
                    "network_policy": {"type": "disabled"},
                },
            )
        )
    ],
)

async def main():
    result = await Runner.run(agent, "分析上传文件中的销售数据，给出月度趋势。")
    print(result.final_output)

LocalShellTool：真正在你机器上执行命令

dataclass 结构

@dataclass
class LocalShellTool:
    executor: LocalShellExecutor

# LocalShellExecutor 类型定义
LocalShellExecutor = Callable[[LocalShellCommandRequest], MaybeAwaitable[str]]

@dataclass
class LocalShellCommandRequest:
    ctx_wrapper: RunContextWrapper[Any]  # run 上下文
    data: LocalShellCall                 # Shell 调用数据（含 command、working_directory、env、timeout_ms）

为什么设计成「你来执行」

• 只支持 codex-mini-latest 模型，不支持其他模型，也不支持 Chat Completions API
• 命令在你的机器上执行，OpenAI 服务器只返回指令，不负责执行——这是设计上的安全边界

一个生产可用的 executor 模板

import shlex
import subprocess
from agents import Agent, LocalShellTool, Runner
from agents.tool import LocalShellCommandRequest

DENY_LIST = ["rm -rf", "sudo", "curl", "wget"]  # 简单黑名单示例

async def safe_executor(req: LocalShellCommandRequest) -> str:
    command = req.data.action.command  # 取出命令字符串

# 安全检查
    for blocked in DENY_LIST:
        if blocked in command:
            return f"[BLOCKED] 命令包含禁用操作: {blocked}"

try:
        result = subprocess.run(
            shlex.split(command),
            cwd=req.data.action.working_directory or "/tmp/sandbox",
            capture_output=True,
            text=True,
            timeout=30,  # 本地超时，不依赖模型的 timeout_ms hint
        )
        return result.stdout + result.stderr
    except subprocess.TimeoutExpired:
        return "[TIMEOUT] 命令执行超时"

agent = Agent(
    name="ShellAgent",
    model="codex-mini-latest",  # LocalShellTool 强制要求此模型
    instructions="你是一个代码助手，可以执行 Shell 命令来完成编程任务。",
    tools=[LocalShellTool(executor=safe_executor)],
)

三工具横向对比

实践建议