AI Agent / 系统课时

实现命令执行工具

实现命令执行工具

本课实现一个受控命令执行工具,让智能体能够运行指定命令并获得退出码、标准输出和标准错误。最终结果是一个具备安全限制和结构化结果返回能力的执行接口。

学习目标

  • 理解 Agent 调用 Shell 工具时需要控制的风险。
  • 掌握封装命令执行接口的方法。
  • 学会处理退出状态和执行结果。

设计命令执行接口

命令执行工具通常接收命令文本和工作目录,执行后返回完整结果。与直接开放终端不同,Agent 工具需要增加超时、目录限制和允许命令列表等约束。

一个基础实现如下:

python
import subprocess


def run_command(command: str, cwd: str) -> dict:
    """执行受控命令并返回结构化结果。"""
    process = subprocess.run(
        command,
        shell=True,
        cwd=cwd,
        capture_output=True,
        text=True,
        timeout=30,
    )

    return {
        "exit_code": process.returncode,
        "stdout": process.stdout,
        "stderr": process.stderr,
    }

预期输出

text
{
  "exit_code": 0,
  "stdout": "build completed",
  "stderr": ""
}

增加执行安全控制

命令执行是高风险工具,需要明确边界。生产环境中通常不会直接允许任意 Shell,而是通过命令白名单、容器隔离或权限控制限制执行范围。

例如构建 Agent 可以允许运行测试命令,但禁止删除文件、修改系统配置等高风险操作。

处理执行状态

Agent 不只需要知道命令是否成功,还需要理解失败原因。工具返回值至少应该包含:

  • exit_code:判断成功或失败。
  • stdout:提供正常执行信息。
  • stderr:提供错误定位线索。

如果命令超时,也应该转换为明确的工具错误,而不是让 Agent 等待未知状态。

常见失败处理

命令执行失败可能来自路径错误、依赖缺失、权限不足或程序本身异常。工具层应该保留原始错误信息,同时提供稳定格式,避免不同系统返回格式差异影响模型判断。

本课总结

  • 命令执行工具需要同时关注能力和安全边界。
  • 结构化返回值帮助 Agent 判断下一步动作。
  • 生产环境应优先采用隔离执行和权限控制。

下一课预告

下一课将继续完善工具调用系统,讨论工具参数校验和调用流程管理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现命令执行工具

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通