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 判断下一步动作。
- 生产环境应优先采用隔离执行和权限控制。
下一课预告
下一课将继续完善工具调用系统,讨论工具参数校验和调用流程管理。
按自己的节奏,确认真正理解。