这次我们来看一个智能体开发的核心概念用 Claude Code 和 Bash 实现一个仅需 30 行代码的智能体循环内核。这个项目的重点不是构建一个复杂的框架而是揭示智能体自主执行任务的最简逻辑——一个while True循环加上 Bash 命令执行。如果你对 AI 智能体如何“自己思考、自己行动”感到好奇或者想从零开始理解智能体开发的内核原理这篇文章将带你直接动手拆解这个极简但强大的核心循环。智能体开发听起来高大上但其最核心的“行动-观察-再行动”循环本质就是让模型如 Claude Code在循环中不断分析当前状态生成下一步要执行的系统命令如 Bash 命令然后执行它并根据结果决定后续动作。本文将聚焦于使用 Claude Code一个专注于代码生成与执行的 AI 模型作为“大脑”Bash 作为“手脚”构建一个可以持续运行、自主处理任务的智能体原型。我们将重点关注这个内核的实现逻辑、环境搭建、以及如何让它实际跑起来处理任务。整个过程不依赖复杂的 Agent 框架硬件门槛极低任何能运行 Python 和 Bash 的环境包括 CPU都可以尝试。文章将带你完成从环境准备、代码编写、到实际运行和效果验证的全过程并探讨其扩展潜力与使用边界。1. 核心能力速览能力项说明项目类型智能体开发原型 / 核心循环演示核心逻辑while True循环 AI 模型决策 Bash 命令执行“大脑”模型Claude Code (通过 API 调用)“手脚”接口系统 Bash Shell (或兼容的命令行)硬件门槛极低。主要消耗在于调用 Claude API 的令牌数本地仅需能运行 Python 脚本和 Bash 的环境。启动方式命令行直接运行 Python 脚本。是否支持 API是核心依赖于 Claude Code 的 API 进行对话与决策。是否支持批量任务是智能体循环可设计为持续处理任务队列。适合场景理解智能体核心原理、自动化脚本编写与执行、探索 AI 与系统交互的边界、教育演示。主要风险命令执行安全AI 生成的命令可能具有破坏性必须在受控的沙箱或测试环境中运行。2. 适用场景与使用边界这个极简智能体内核最适合以下几类读者和场景智能体开发初学者希望绕过复杂框架直接理解智能体最核心的“感知-思考-行动”循环是如何用代码实现的。自动化脚本探索者需要一种能根据动态上下文如文件内容、命令输出自动生成并执行后续步骤的自动化工具。教育与原型开发用于快速验证一个 AI 驱动的工作流是否可行或作为教学案例展示 AI 与操作系统交互的基本模式。它能解决什么问题自动化复杂流程给定一个高级目标如“整理我的下载文件夹”智能体能自行分解步骤判断文件类型移动文件并处理可能出现的错误。交互式问题诊断根据系统命令如df -h,ps aux的输出智能体能分析问题尝试修复命令如清理缓存、重启服务。动态脚本编写根据不断变化的需求和环境实时生成并执行对应的 Bash、Python 或其他脚本。它不适合什么场景高可靠生产环境缺乏完善的错误处理、回滚机制和安全性保障不适合直接处理关键业务或生产数据。需要精确控制每一步的场景AI 模型的决策具有不可预测性可能产生非预期的命令。无监督的开放环境绝对不能在具有重要数据或权限的生产服务器上未经严格限制地运行。安全与合规边界至关重要沙箱环境必须在虚拟机、容器Docker或专门创建的、无重要权限的测试用户环境中运行。命令审查在核心循环中可以加入“人工确认”环节或者对 AI 生成的命令进行关键词过滤如禁止rm -rf /,dd, 格式化命令等。权限最小化运行脚本的用户权限应被严格限制不能是 root 或具有 sudo 权限的账户。明确责任开发者需对智能体执行的所有操作负最终责任。用于处理任何受版权保护或涉及个人隐私的数据前必须确保有合法授权。3. 环境准备与前置条件在开始编写那 30 行核心代码之前我们需要先搭建好运行环境。这个环境非常简单。操作系统支持 Bash 的 Linux 或 macOS。Windows 用户可以通过 WSL (Windows Subsystem for Linux) 获得完整的 Bash 环境或者使用 Git Bash但需要注意路径等兼容性问题。Python 环境需要 Python 3.7 或更高版本。推荐使用venv或conda创建独立的虚拟环境。Claude API 密钥这是智能体的“大脑”燃料。你需要前往 Claude 官网 注册账号并创建 API Key。请妥善保管此 Key不要泄露。网络连接需要能够稳定访问 Claude API 服务。基础命令行技能需要会使用cd,ls,python等基本命令。环境检查清单[ ] 打开终端输入python3 --version确认版本 3.7。[ ] 输入bash --version确认 Bash 可用。[ ] 准备好你的 Claude API Key。4. 安装部署与启动方式部署就是安装必要的 Python 库然后编写并运行我们的脚本。没有复杂的服务启动过程。第一步安装依赖我们主要需要anthropic这个官方库来调用 Claude API。在终端中执行以下命令# 创建并进入项目目录 mkdir simple_agent_core cd simple_agent_core # 创建虚拟环境 (可选但推荐) python3 -m venv venv # 激活虚拟环境 # Linux/macOS: source venv/bin/activate # Windows (cmd): # venv\Scripts\activate.bat # Windows (PowerShell): # venv\Scripts\Activate.ps1 # 安装 anthropic 库 pip install anthropic第二步编写核心智能体脚本创建一个名为simple_agent.py的文件并将以下代码复制进去。这就是我们所说的“30行内核”的精简增强版包含了基本的错误处理和提示词工程。import os import subprocess import anthropic from typing import Optional class SimpleBashAgent: def __init__(self, api_key: str, model: str claude-3-5-sonnet-20241022): 初始化智能体设置 Claude 客户端和系统提示词。 self.client anthropic.Anthropic(api_keyapi_key) self.model model # 核心系统提示词定义了智能体的角色和行为规范 self.system_prompt 你是一个运行在 Bash 环境中的 AI 助手。你的任务是分析用户的请求和当前系统状态然后生成一个单一、安全、有效的 Bash 命令来推进任务。 你必须遵守以下规则 1. 只输出一个可执行的 Bash 命令不要有任何额外的解释、Markdown 代码块标记或前言。 2. 命令必须相对安全避免使用 rm -rf /、dd 等具有极高破坏性的命令除非上下文明确要求且用户知晓风险。 3. 如果任务已完成或无法继续输出 DONE。 4. 如果用户请求不明确输出一个能帮助澄清情况的命令如 ls 查看目录pwd 显示位置。 当前工作目录{cwd} def execute_command(self, command: str) - tuple[str, str, int]: 执行 Bash 命令并返回标准输出、标准错误和返回码。 try: result subprocess.run( command, shellTrue, capture_outputTrue, textTrue, cwdos.getcwd(), timeout30 # 防止命令长时间运行 ) return result.stdout, result.stderr, result.returncode except subprocess.TimeoutExpired: return , Command timed out after 30 seconds., -1 except Exception as e: return , fFailed to execute command: {e}, -1 def run_loop(self, initial_goal: str): 运行智能体的主循环。 print(f 目标{initial_goal}) print(输入 quit 退出循环。\n) # 初始化对话历史包含用户的目标 messages [ {role: user, content: f我的目标是{initial_goal}. 我现在应该运行什么命令来开始请只输出命令。} ] while True: # 1. 获取当前上下文工作目录 current_dir os.getcwd() system_msg self.system_prompt.format(cwdcurrent_dir) # 2. 调用 Claude 模型获取下一个命令 try: response self.client.messages.create( modelself.model, max_tokens1024, systemsystem_msg, messagesmessages ) command response.content[0].text.strip() except Exception as e: print(f❌ 调用 Claude API 失败{e}) break # 3. 处理特殊指令 if command.lower() quit: print( 用户请求退出。) break if command DONE: print(✅ 智能体认为任务已完成。) break if not command: print(⚠️ 模型未返回有效命令循环结束。) break print(f 模型建议命令{command}) user_input input(是否执行(y/n/直接输入新命令)).strip().lower() if user_input n: # 用户拒绝将拒绝信息反馈给模型让它重新规划 messages.append({role: user, content: f命令 {command} 被拒绝。请基于当前状态重新建议一个不同的命令。只输出命令。}) continue elif user_input ! y: # 用户输入了新命令则执行用户命令并将其作为新的上下文 if user_input: command user_input else: continue # 4. 执行命令 print(f 执行{command}) stdout, stderr, returncode self.execute_command(command) # 5. 显示结果 if stdout: print(f 标准输出\n{stdout}) if stderr: print(f⚠️ 标准错误\n{stderr}) print(f 返回码{returncode}\n) # 6. 将执行结果构建成反馈加入对话历史供模型进行下一轮决策 result_summary f命令 {command} 已执行。返回码{returncode}。 if stdout: result_summary f\n标准输出\n{stdout[:500]} # 截断长输出 if stderr: result_summary f\n标准错误\n{stderr[:500]} messages.append({role: user, content: result_summary \n接下来应该做什么请只输出下一个命令。}) if __name__ __main__: # 从环境变量获取 API Key更安全 API_KEY os.environ.get(ANTHROPIC_API_KEY) if not API_KEY: print(❌ 请设置环境变量 ANTHROPIC_API_KEY。) print( 例如export ANTHROPIC_API_KEYyour-api-key-here) exit(1) agent SimpleBashAgent(api_keyAPI_KEY) initial_goal input(请输入智能体的初始目标例如清空 /tmp 目录下的所有 .log 文件).strip() agent.run_loop(initial_goal)第三步设置 API Key 并运行在运行脚本前需要将你的 Claude API Key 设置为环境变量。# Linux/macOS/WSL export ANTHROPIC_API_KEY你的实际API密钥 # Windows (cmd) # set ANTHROPIC_API_KEY你的实际API密钥 # Windows (PowerShell) # $env:ANTHROPIC_API_KEY你的实际API密钥 # 运行智能体 python simple_agent.py运行后程序会提示你输入一个初始目标然后进入交互循环。这就是我们智能体的启动方式。5. 功能测试与效果验证现在让我们用几个具体的场景来测试这个智能体内核看看它如何“思考”和“行动”。5.1 测试一文件系统探索与整理测试目的验证智能体能否理解一个模糊的目标并自主通过一系列命令来探索和完成任务。操作步骤运行python simple_agent.py。输入初始目标“帮我找出当前目录下所有超过 1MB 的 .txt 文件并列出它们。”观察模型生成的第一个命令。它很可能会生成find . -name *.txt -size 1M。输入y执行。模型会根据find命令的输出生成后续命令。例如如果找到了文件它可能会建议ls -lh来查看详情或者直接输出DONE。预期结果智能体能够成功组合使用find、ls、du等命令最终向你报告符合条件的文件列表。这演示了它根据命令输出进行“观察”并决定“下一步行动”的能力。5.2 测试二交互式问题诊断测试目的验证智能体能否根据系统状态进行分析和尝试性修复。操作步骤在运行脚本前先创建一个占用磁盘空间的测试文件dd if/dev/zero of./test_large_file bs1M count10。运行智能体输入目标“检查当前磁盘使用情况如果空间紧张尝试清理一下。”模型可能会首先生成df -h .来查看磁盘使用率。执行后它看到使用率可能会生成du -sh * | sort -hr | head -5来找出大文件。看到test_large_file后它可能会建议rm test_large_file。这里就是安全边界脚本会要求你确认 (y/n)。预期结果智能体完成从诊断 (df) 到分析 (du) 再到行动建议 (rm) 的链条。人工确认环节防止了自动执行危险操作。5.3 测试三处理复杂、多步骤任务测试目的验证循环处理长链条任务的能力。操作步骤运行智能体输入一个更开放的目标“为我的新项目‘my_app’创建一个基本的 Python 项目结构包含 src、tests 目录和 README.md 文件。”观察模型的命令序列。它可能会依次生成mkdir -p my_app(创建项目目录)cd my_app(进入目录)mkdir -p src tests(创建子目录)touch README.md(创建文件)echo # My App README.md(写入内容)最后输出DONE。预期结果智能体将一个高级目标分解为多个可执行的 Bash 命令并依次执行最终完成项目结构的搭建。这体现了智能体“规划”能力的雏形。6. 接口 API 与批量任务我们这个内核本身就是一个通过标准输入/输出交互的“接口”。但我们可以很容易地将其改造成一个可编程的 API 服务或批量任务处理器。改造为异步任务处理器核心思想是将initial_goal从一个用户输入变成一个任务队列并移除交互式确认在生产环境中需极度谨慎或改用更安全的策略。# 示例批量任务处理骨架 (batch_processor.py) import json from queue import Queue from simple_agent import SimpleBashAgent # 假设我们把之前的类移到了这个模块 class BatchAgentProcessor: def __init__(self, api_key: str): self.agent SimpleBashAgent(api_key) self.task_queue Queue() def add_task(self, goal: str): self.task_queue.put(goal) def process_all(self): while not self.task_queue.empty(): goal self.task_queue.get() print(f\n 开始处理任务{goal} ) # 这里需要修改原 run_loop 方法使其能非交互地运行一个任务到完成 # 可能需要一个自动化的“批准”逻辑例如只允许白名单内的命令自动执行 self.agent.run_loop_auto(goal) # 这是一个假设的方法 print(f 任务完成{goal} \n) # 使用示例 if __name__ __main__: processor BatchAgentProcessor(api_keyos.environ.get(ANTHROPIC_API_KEY)) processor.add_task(备份 /var/log 目录下的 .log 文件到 /backup) processor.add_task(检查系统最近的错误日志) processor.process_all()通用 API 调用示例更常见的模式是将智能体作为后台服务通过 HTTP API 接收目标并返回执行日志或最终结果。# 示例使用 FastAPI 创建智能体服务 (agent_service.py) from fastapi import FastAPI, HTTPException from pydantic import BaseModel import asyncio import threading from simple_agent import SimpleBashAgent app FastAPI() agent SimpleBashAgent(api_keyos.environ.get(ANTHROPIC_API_KEY)) class AgentRequest(BaseModel): goal: str session_id: str None class AgentResponse(BaseModel): session_id: str status: str # running, completed, error logs: list[str] final_output: str None # 内存中存储会话生产环境需用数据库 sessions {} app.post(/run, response_modelAgentResponse) async def run_agent(request: AgentRequest): session_id request.session_id or str(uuid.uuid4()) if session_id in sessions: raise HTTPException(status_code400, detailSession already exists) sessions[session_id] {status: running, logs: []} # 在新线程中运行智能体避免阻塞 API def run_goal(): # 这里需要重写 agent.run_loop使其将日志写入 sessions[session_id][logs] # 并将最终结果写入 sessions[session_id][final_output] pass thread threading.Thread(targetrun_goal) thread.start() return AgentResponse(session_idsession_id, statusrunning, logs[]) app.get(/status/{session_id}) async def get_status(session_id: str): if session_id not in sessions: raise HTTPException(status_code404, detailSession not found) return sessions[session_id]启动服务后就可以用 curl 或 Python requests 库来提交任务了。curl -X POST http://127.0.0.1:8000/run \ -H Content-Type: application/json \ -d {goal: 找出当前目录下所有 .py 文件并统计行数}7. 资源占用与性能观察由于这个智能体的“大脑”是云端 Claude API因此本地资源占用几乎可以忽略不计主要性能考量在于网络延迟和 API 调用成本。本地资源CPU/内存运行 Python 脚本和子进程Bash消耗极少任何现代计算机都绰绰有余。显存不占用本地显存所有模型推理都在 Anthropic 的服务器上完成。网络延迟每个决策循环都需要一次 API 调用因此智能体的“思考”速度取决于你与 Claude API 服务器的网络延迟。通常一次往返在几百毫秒到几秒之间。API 成本与限额这是主要的“性能”瓶颈。Claude API 按输入/输出 Token 数收费并有速率限制。一个复杂的、多轮对话的智能体任务可能会消耗数百甚至数千个 Token。在开发测试时务必关注你的用量。性能优化点提示词精简系统提示词和消息历史要尽可能简洁减少不必要的 Token 消耗。结果截断如代码所示将过长的命令输出截断后再喂给模型能有效节省 Token。超时控制对执行的 Bash 命令设置超时如代码中的timeout30防止某个命令卡住整个智能体。会话管理对于长任务可以考虑定期总结状态而不是将全部历史记录都发送给模型以控制上下文长度。8. 常见问题与排查方法在运行这个智能体内核时你可能会遇到以下问题问题现象可能原因排查方式解决方案运行脚本报错ModuleNotFoundError: No module named anthropic依赖未安装或不在当前 Python 环境。在终端输入 pip listgrep anthropic。提示请设置环境变量 ANTHROPIC_API_KEYAPI Key 未正确设置。在终端执行echo $ANTHROPIC_API_KEY(Linux/macOS) 或echo %ANTHROPIC_API_KEY%(Windows cmd)。确保在运行脚本的同一个终端会话中正确设置了环境变量。调用 Claude API 失败返回认证错误API Key 无效、过期或格式错误。检查 Key 是否复制完整是否包含多余空格。前往 Anthropic 控制台确认 Key 状态。重新生成 API Key 并更新环境变量。模型生成的命令被拒绝执行权限不足运行脚本的用户权限较低。在终端执行whoami和ls -la查看当前用户和目录权限。要么在具有足够权限的目录操作要么极其谨慎地以更高权限运行但强烈不推荐。更好的方式是在提示词中让模型生成适配当前权限的命令。命令执行超时模型生成了一个长时间运行或卡住的命令。查看脚本打印的Command timed out错误信息。检查生成的命令本身是否有问题。可以尝试在交互中输入一个已知快速的命令如pwd来恢复循环。在execute_command函数中调整timeout参数。智能体陷入循环或行为怪异提示词不够清晰或模型对当前状态理解有误。观察对话历史 (messages)看模型是否收到了混乱的上下文。优化系统提示词 (system_prompt)更明确地规定输出格式和边界。在消息历史中加入更清晰的指令。在 Windows Git Bash 中路径或命令异常Git Bash 与原生 Bash 以及 Windows 路径存在兼容性问题。在 Git Bash 中测试简单命令如ls、pwd看输出是否正常。尽量在 WSL 或 Linux/macOS 环境下运行。如果必须用 Git Bash提示词中可注明环境并让模型生成兼容性更好的命令。API 调用达到速率限制短时间内发送了过多请求。Anthropic API 会返回包含rate_limit信息的错误。在代码中增加请求间隔 (time.sleep)。对于批量任务需要实现队列和速率控制逻辑。9. 最佳实践与使用建议基于这个极简内核进行开发或实验时遵循以下建议可以事半功倍并确保安全始终在沙箱中开始第一次运行任何智能体代码前务必在 Docker 容器、虚拟机或一个全新的、无关紧要的用户目录中进行。永远不要直接在存有重要数据或拥有高权限的环境中裸跑。实现“安全开关”我们的示例代码包含了交互式确认 (y/n)。在生产构想中可以扩展为命令白名单只允许执行ls,cat,grep,find(不含-delete) 等安全命令。关键词黑名单过滤掉包含rm -rf,mkfs,dd,chmod 777等危险模式的命令。模拟执行先使用echo或dry-run模式打印出命令而不实际执行。精心设计提示词智能体的“性格”和“能力”几乎完全由系统提示词定义。花时间迭代你的提示词使其目标明确、格式严格、安全边界清晰。可以要求模型在输出命令前先进行简短的理由阐述虽然我们的示例要求只输出命令但调试时可以放宽。管理上下文长度Claude 模型有上下文窗口限制。对于长周期任务不要无限制地增长messages历史。可以定期让模型自己总结当前状态然后用总结替换掉冗长的历史记录重新开始一个“会话”。日志记录一切将所有输入用户目标、输出模型生成的命令、执行结果stdout, stderr, returncode都记录到文件或数据库中。这是调试和事后审计的唯一依据。从简单任务开始验证不要一开始就让智能体去执行“优化我的数据库”这种复杂任务。从“列出当前目录文件”、“创建一个文本文件”开始逐步增加复杂度观察其决策逻辑。明确失败处理当前示例中命令执行失败返回码非0后模型会接收到错误信息并尝试下一步。你需要思考这是否总是你期望的行为有时失败意味着应该停止整个任务。在提示词中定义好失败处理策略。成本监控在 Anthropic 控制台设置预算和用量告警。在代码中记录每个请求消耗的 Token 数便于分析成本。10. 总结与下一步这个仅用while True循环、Claude Code API 和 Bash 构建的 30 行智能体内核虽然简单却完整地演示了自主智能体的核心范式在循环中感知环境读取命令输出、思考决策调用 AI 模型、执行动作运行 Bash 命令。它剥离了框架的复杂性让你能直接触摸到智能体开发的本质。最值得尝试的点在于你可以用极低的代码成本快速验证一个 AI 自动化工作流的想法是否可行。例如能否让 AI 自动管理服务器日志能否根据测试结果自动调试代码这个内核为你提供了一个绝佳的起点。最先应该验证的功能就是文件系统操作和简单信息检索。通过这两个场景你能最直观地感受到 AI 如何理解你的自然语言目标并将其转化为精确的系统操作。最容易踩的坑无疑是命令执行安全。在兴奋于智能体自动完成任务的同时务必时刻牢记它生成的是能在你系统上真实执行的代码。没有安全措施的智能体就是一个拥有最高权限的、不可预测的自动化漏洞。后续扩展方向有很多增加工具库让智能体不仅能调用 Bash还能调用 Python 函数、HTTP API、数据库等成为真正的“工具使用者”Tool Use。集成记忆引入向量数据库让智能体能够记住长期的目标和上下文处理更复杂的多会话任务。可视化与监控为智能体的决策过程和执行流水线构建一个 Web 控制面板实时观察其“思考”过程。连接专业框架当你理解了这个内核后可以更容易地学习和使用像 LangChain、AutoGen、CrewAI 这样的成熟 Agent 框架理解它们底层在做什么。建议将本文的示例代码保存下来作为你探索智能体世界的第一块基石。在安全的沙箱里大胆地给它设定目标观察它的行为迭代你的提示词你会对 AI 如何与真实世界互动产生前所未有的具体认知。