时光里的沙漏1. Claude Code Agent 开发入门：从零构建智能体核心循环
作为一名长期从事AI应用开发的工程师，我一直在探索如何将大语言模型(LLM)转化为真正可用的智能体。今天要分享的这个"循环+工具=Agent"模式，是我在实践中验证过的最基础也最有效的智能体架构方案。这个设计最初来源于learn-claude-code开源项目，但经过我的多次迭代和优化，已经形成了一个稳定可靠的实现版本。
1.1 为什么需要智能体架构？
在日常开发中，我们经常会遇到这样的场景：需要让AI模型完成一个复杂任务，但单次问答无法满足需求。比如：
- 编写并测试一段代码
- 分析服务器日志并给出修复建议
- 自动化处理文件系统操作
这些任务都需要模型能够"思考-行动-观察"的循环过程。智能体架构正是为解决这类问题而生，它让模型具备了持续与环境交互的能力。
1.2 极简设计哲学
这个实现的核心思想可以用一个公式概括：
code复制1个循环 + 1个工具 = 1个智能体
这种极简设计有三大优势：
- 易于理解：代码量少，核心逻辑一目了然
- 便于调试：每个循环的状态清晰可见
- 扩展性强：可以在基础上逐步添加更多功能
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与基础配置
2.1 开发环境搭建
首先需要准备Python开发环境，我推荐使用Python 3.10+版本。关键依赖包包括：
bash复制pip install anthropic python-dotenv
提示：建议使用虚拟环境管理依赖，避免与其他项目冲突
2.2 安全配置管理
安全永远是第一位的，特别是当智能体需要执行系统命令时。我们的配置方案采用环境变量管理敏感信息：
python复制import os
from dotenv import load_dotenv
load_dotenv(override=True)
# 安全考虑：如果使用自定义端点，则移除默认的认证token
if os.getenv("ANTHROPIC_BASE_URL"):
os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)
这种设计实现了：
- 配置与代码分离
- 多环境支持
- 安全防护措施
2.3 客户端初始化
创建Anthropic客户端实例时，我们考虑了生产环境的灵活性：
python复制from anthropic import Anthropic
client = Anthropic(
base_url=os.getenv("ANTHROPIC_BASE_URL") # 支持自定义API端点
)
MODEL = os.environ["MODEL_ID"] # 模型ID可配置
3. 智能体核心组件设计
3.1 系统提示工程
系统提示是引导模型行为的关键。我们的设计原则是：明确、简洁、可操作。
python复制SYSTEM = f"You are a coding agent at {os.getcwd()}. Use bash to solve tasks. Act, don't explain."
这个提示包含三个关键信息：
- 角色定位：当前目录的编码助手
- 能力范围：使用bash解决问题
- 行为准则：直接行动，减少解释
3.2 工具系统实现
工具是智能体与外界交互的桥梁。我们首先实现最基础的bash工具：
python复制TOOLS = [{
"name": "bash",
"description": "Run a shell command.",
"input_schema": {
"type": "object",
"properties": {"command": {"type": "string"}},
"required": ["command"],
},
}]
这个工具定义遵循Anthropic的函数调用规范，包含：
- 工具名称
- 功能描述
- 输入参数schema
4. Bash工具的安全实现
4.1 危险命令拦截
允许执行任意bash命令风险极高，必须实现安全防护：
python复制def run_bash(command: str) -> str:
dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
if any(d in command for d in dangerous):
return "Error: Dangerous command blocked"
这个黑名单机制可以防止：
- 系统文件删除
- 权限提升操作
- 系统关机/重启
- 输出重定向到设备文件
4.2 命令执行与结果处理
安全执行命令需要考虑多种边界情况：
python复制try:
r = subprocess.run(command, shell=True, cwd=os.getcwd(),
capture_output=True, text=True, timeout=120)
out = (r.stdout + r.stderr).strip()
return out[:50000] if out else "(no output)"
except subprocess.TimeoutExpired:
return "Error: Timeout (120s)"
关键设计点：
- 超时控制：120秒自动终止长时间运行命令
- 工作目录：固定到当前目录，避免路径问题
- 输出合并：同时捕获stdout和stderr
- 结果截断：防止大输出耗尽上下文窗口
5. 智能体核心循环实现
5.1 主循环结构
这是整个智能体的"大脑"，实现了经典的思考-行动循环：
python复制def agent_loop(messages: list):
while True:
# 1. 调用LLM获取响应
response = client.messages.create(
model=MODEL, system=SYSTEM, messages=messages,
tools=TOOLS, max_tokens=8000,
)
# 2. 将助手回复加入对话历史
messages.append({"role": "assistant", "content": response.content})
# 3. 检查停止条件
if response.stop_reason != "tool_use":
return # 任务完成
# 4. 处理工具调用
results = []
for block in response.content:
if block.type == "tool_use":
print(f"\033[33m$ {block.input['command']}\033[0m")
output = run_bash(block.input["command"])
print(output[:200]) # 打印部分输出
results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": output
})
# 5. 将工具结果反馈给模型
messages.append({"role": "user", "content": results})
5.2 循环状态机解析
这个循环实际上实现了一个状态机：
- 思考状态：调用LLM获取响应
- 决策分支：
- 如果返回最终答案 → 结束循环
- 如果请求工具调用 → 进入执行状态
- 执行状态：运行请求的工具
- 反馈状态：将结果返回给模型
5.3 对话历史管理
对话历史(messages)是维持上下文的核心。我们的设计要点：
- 始终保持完整的对话轮次
- 工具结果以user角色返回，保持对话结构
- 每次循环都追加新消息，形成持续对话
6. 交互式主循环实现
6.1 用户输入处理
为了让智能体可交互，我们实现了REPL(Read-Eval-Print Loop)：
python复制history = []
while True:
try:
query = input("\033[36ms01 >> \033[0m") # 带颜色的提示符
except (EOFError, KeyboardInterrupt):
break
if query.strip().lower() in ("q", "exit", ""):
break
history.append({"role": "user", "content": query})
agent_loop(history)
这个设计支持：
- 彩色提示符提升可读性
- 安全退出机制(Ctrl+D/Ctrl+C)
- 简单的退出命令(q/exit)
6.2 结果展示优化
为了提升用户体验，我们对输出做了专门处理：
python复制response_content = history[-1]["content"]
if isinstance(response_content, list):
for block in response_content:
if hasattr(block, "text"):
print(block.text)
print()
这样可以：
- 正确提取模型的文本回复
- 忽略工具调用的中间结果
- 保持输出整洁
7. 实战案例与技巧分享
7.1 典型使用场景
这个基础智能体已经能处理许多实用任务：
-
文件操作
bash复制s01 >> 创建一个test目录并在其中生成5个测试文件 $ mkdir test (no output) $ for i in {1..5}; do touch test/file_$i.txt; done (no output) -
系统信息查询
bash复制
s01 >> 查看系统内存使用情况 $ free -h total used free shared buff/cache available Mem: 15G 4.2G 8.1G 345M 3.2G 10G Swap: 2.0G 1.1G 939M -
简单数据处理
bash复制s01 >> 统计当前目录中.py文件的行数 $ find . -name "*.py" | xargs wc -l 123 ./script1.py 456 ./script2.py 789 ./script3.py 1368 total
7.2 调试技巧
开发智能体时，这些调试方法很实用：
-
打印完整对话历史
python复制import json print(json.dumps(history, indent=2)) -
模拟工具响应
python复制# 在agent_loop中临时添加 if "模拟" in query: results = [{"type": "tool_result", "content": "模拟结果"}] -
限制循环次数
python复制max_loops = 5 while max_loops > 0: max_loops -= 1 # ...原有循环逻辑...
7.3 性能优化建议
经过多次实践，我总结出这些优化点：
-
上下文窗口管理
- 定期清理过时的对话历史
- 对长输出进行智能摘要
-
并行工具执行
python复制from concurrent.futures import ThreadPoolExecutor with ThreadPoolExecutor() as executor: futures = [executor.submit(run_bash, cmd) for cmd in commands] results = [f.result() for f in futures] -
缓存机制
- 缓存常用命令的结果
- 对相同输入直接返回缓存
8. 架构演进路线
这个基础架构可以沿多个方向扩展：
8.1 工具系统增强
-
多工具支持
python复制
TOOLS = [bash_tool, python_tool, web_search_tool] -
工具权限控制
python复制class Tool: def __init__(self, name, permission_level): self.name = name self.permission_level = permission_level -
工具组合调用
- 支持工具链式调用
- 实现工具间的数据传递
8.2 规划能力提升
-
任务分解
python复制def plan(task): steps = llm.generate(f"将任务分解为步骤: {task}") return parse_steps(steps) -
子目标管理
- 维护目标栈
- 支持目标暂停/恢复
-
进度跟踪
- 可视化任务进度
- 异常时自动回滚
8.3 记忆系统设计
-
短期记忆
- 对话历史管理
- 上下文窗口优化
-
长期记忆
python复制class VectorMemory: def store(self, key, embedding): self.vector_db.upsert(key, embedding) -
反思机制
- 定期总结经验
- 自动优化策略
9. 生产环境注意事项
将智能体部署到生产环境时，这些经验很重要：
9.1 安全防护升级
-
沙箱环境
python复制import docker client = docker.from_env() container = client.containers.run( "sandbox-image", command=command, remove=True ) -
审计日志
- 记录所有工具调用
- 实现操作回放
-
权限最小化
- 使用低权限用户
- 限制文件系统访问
9.2 监控与告警
-
健康指标
- 循环次数监控
- 响应时间统计
-
异常检测
python复制if loop_count > MAX_LOOPS: alert("Possible infinite loop") -
性能分析
- 工具调用耗时
- Token使用分析
9.3 稳定性保障
-
错误恢复
python复制try: agent_loop(history) except Exception as e: history.append(error_message(e)) continue -
限流措施
- API调用频率限制
- 并发请求控制
-
回退机制
- 自动降级方案
- 人工接管接口
10. 开发心得与未来展望
在实际开发这类智能体系统的过程中，我深刻体会到几个关键点：
- 简单即强大：最基础的循环模式往往最可靠，过度设计反而增加复杂度
- 模型即智能体：核心智能来自模型而非代码，代码只是提供执行环境
- 安全第一：任何工具调用都必须考虑最坏情况
这个基础架构已经可以处理许多自动化任务，但真正的挑战在于：
- 如何平衡灵活性与安全性
- 如何实现可靠的长期任务执行
- 如何让智能体自主学习和改进
我现在的开发重点是构建一个"工具市场"，让智能体能够按需加载和使用工具，这将大大扩展其应用范围。同时，也在探索如何让多个智能体协作完成任务，这需要更复杂的协调机制。