ghuntley/how-to-build-a-coding-agent
GitHub: ghuntley/how-to-build-a-coding-agent
手把手教你用 Go 和 Claude API 从零构建编程智能体的分步教程，涵盖聊天、文件操作、命令执行和代码搜索等核心能力。
Stars: 5379 | Forks: 608
# 🧠 通过分步研讨会构建你自己的编码智能体
欢迎！👋 本次研讨会将指导你构建自己的 **AI 驱动的编程助手** —— 从一个基础的聊天机器人开始，逐步添加强大的工具，如文件读取、Shell 命令执行和代码搜索。
你不需要是 AI 专家。只需跟随步骤，一步步构建即可！
🌐 **想要详细概览？** 请查看博客文章：[ghuntley.com/agent](https://ghuntley.com/agent/)
## 🎯 你将学到什么
在本次研讨会结束时，你将了解如何：
- ✅ 连接到 Anthropic Claude API
- ✅ 构建一个简单的 AI 聊天机器人
- ✅ 添加读取文件、编辑代码和运行命令等工具
- ✅ 处理工具请求和错误
- ✅ 构建一个每一步都变得更聪明的智能体
## 🛠️ 我们要构建什么
你将构建编程助手的 6 个版本。
每个版本都会增加更多功能：
1. **基础聊天** —— 与 Claude 对话
2. **文件读取器** —— 读取代码文件
3. **文件浏览器** —— 列出文件夹中的文件
4. **命令运行器** —— 运行 Shell 命令
5. **文件编辑器** —— 修改文件
6. **代码搜索** —— 使用模式搜索你的代码库
```
graph LR
subgraph "Application Progression"
A[chat.go
Basic Chat] --> B[read.go
+ File Reading] B --> C[list_files.go
+ Directory Listing] C --> D[bash_tool.go
+ Shell Commands] D --> E[edit_tool.go
+ File Editing] E --> F[code_search_tool.go
+ Code Search] end subgraph "Tool Capabilities" G[No Tools] --> H[read_file] H --> I[read_file
list_files] I --> J[read_file
list_files
bash] J --> K[read_file
list_files
bash
edit_file] K --> L[read_file
list_files
bash
code_search] end A -.-> G B -.-> H C -.-> I D -.-> J E -.-> K F -.-> L ``` 最后，你将获得一个强大的本地开发者助手！ ## 🧱 它是如何工作的（架构） 每个智能体的工作方式如下： 1. 等待你的输入 2. 将其发送给 Claude 3. Claude 可能直接响应或请求使用工具 4. 智能体运行工具（例如，读取文件） 5. 将结果发送回 Claude 6. Claude 给你最终答案 我们称之为 **事件循环 (event loop)** —— 它就像智能体的心跳。 ``` graph TB subgraph "Agent Architecture" A[Agent] --> B[Anthropic Client] A --> C[Tool Registry] A --> D[getUserMessage Function] A --> E[Verbose Logging] end subgraph "Shared Event Loop" F[Start Chat Session] --> G[Get User Input] G --> H{Empty Input?} H -->|Yes| G H -->|No| I[Add to Conversation] I --> J[runInference] J --> K[Claude Response] K --> L{Tool Use?} L -->|No| M[Display Text] L -->|Yes| N[Execute Tools] N --> O[Collect Results] O --> P[Send Results to Claude] P --> J M --> G end subgraph "Tool Execution Loop" N --> Q[Find Tool by Name] Q --> R[Execute Tool Function] R --> S[Capture Result/Error] S --> T[Add to Tool Results] T --> U{More Tools?} U -->|Yes| Q U -->|No| O end ``` ## 🚀 开始使用 ### ✅ 前置条件 * Go 1.24.2+ 或 [devenv](https://devenv.sh/)（推荐，易于设置） * 一个 [Anthropic API Key](https://www.anthropic.com/product/claude) ### 🔧 设置你的环境 **选项 1：推荐（使用 devenv）** ``` devenv shell # Loads everything you need ``` **选项 2：手动设置** ``` # 确保已安装 Go go mod tidy ``` ### 🔐 添加你的 API Key ``` export ANTHROPIC_API_KEY="your-api-key-here" ``` ## 🏁 从基础开始 ### 1. `chat.go` —— 基础聊天 一个与 Claude 对话的简单聊天机器人。 ``` go run chat.go ``` * ➡️ 尝试：“Hello!” * ➡️ 添加 `--verbose` 以查看详细日志 ## 🛠️ 添加工具（一步步来） ### 2. `read.go` —— 读取文件 现在 Claude 可以从你的计算机读取文件了。 ``` go run read.go ``` * ➡️ 尝试：“Read fizzbuzz.js” ### 3. `list_files.go` —— 浏览文件夹 让 Claude 可以查看你的目录。 ``` go run list_files.go ``` * ➡️ 尝试：“List all files in this folder” * ➡️ 尝试：“What’s in fizzbuzz.js?” ### 4. `bash_tool.go` —— 运行 Shell 命令 允许 Claude 运行安全的终端命令。 ``` go run bash_tool.go ``` * ➡️ 尝试：“Run git status” * ➡️ 尝试：“List all .go files using bash” ### 5. `edit_tool.go` —— 编辑文件 Claude 现在可以 **修改代码**、创建文件和进行更改。 ``` go run edit_tool.go ``` * ➡️ 尝试：“Create a Python hello world script” * ➡️ 尝试：“Add a comment to the top of fizzbuzz.js” ### 6. `code_search_tool.go` —— 搜索代码 使用模式搜索（由 [ripgrep](https://github.com/BurntSushi/ripgrep) 驱动）。 ``` go run code_search_tool.go ``` * ➡️ 尝试：“Find all function definitions in Go files” * ➡️ 尝试：“Search for TODO comments” ## 🧪 示例文件（已包含） 1. `fizzbuzz.js`：用于文件读取和编辑 2. `riddle.txt`：一个有趣的文本文件供探索 3. `AGENT.md`：关于项目环境的信息 ## 🐞 故障排除 **API Key 不起作用？** * 确保它已导出：`echo $ANTHROPIC_API_KEY` * 在 [Anthropic’s dashboard](https://www.anthropic.com) 检查你的配额 **Go 错误？** * 运行 `go mod tidy` * 确保你使用的是 Go 1.24.2 或更高版本 **工具错误？** * 使用 `--verbose` 获取完整的错误日志 * 检查文件路径和权限 **环境问题？** * 使用 `devenv shell` 以避免配置问题 ## 💡 工具如何工作（底层原理） 工具就像插件。你需要定义： * **名称**（例如，`read_file`） * **输入 Schema**（它需要什么信息） * **函数**（它做什么） Go 中的工具定义示例： ``` var ToolDefinition = ToolDefinition{ Name: "read_file", Description: "Reads the contents of a file", InputSchema: GenerateSchema[ReadFileInput](), Function: ReadFile, } ``` Schema 生成使用 Go structs —— 因此定义和重用都很容易。 ## 🧭 研讨会路径：通过构建来学习 | 阶段 | 关注点 | | ----- | ------------------------------------------------ | | **1** | `chat.go`: API 集成和响应处理 | | **2** | `read.go`: 工具系统，Schema 生成 | | **3** | `list_files.go`: 多工具，文件系统 | | **4** | `bash_tool.go`: Shell 执行，错误捕获 | | **5** | `edit_tool.go`: 文件编辑，安全检查 | | **6** | `code_search_tool.go`: 模式搜索，ripgrep | ## 🛠️ 开发者环境（可选） 如果你使用 [`devenv`](https://devenv.sh/)，它会为你提供： * Go, Node, Python, Rust, .NET * Git 和其他开发工具 ``` devenv shell # Load everything devenv test # Run checks hello # Greeting script ``` ## 🚀 接下来做什么？ 完成研讨会后，尝试构建： * 自定义工具（例如，API 调用器、网页抓取器） * 工具链（按顺序运行工具） * 记忆功能（跨会话记住事物） * 智能体的 Web UI * 与其他 AI 模型的集成 ## 📦 总结 本次研讨会帮助你： * 理解智能体架构 * 学习构建智能助手 * 逐步扩展能力 * 练习结合使用 Claude 和 Go 享受探索和构建你自己的 AI 驱动工具的乐趣！💻✨ 如果你有问题或想法，请随意 fork 仓库、开启 issue 或与社区交流！
Basic Chat] --> B[read.go
+ File Reading] B --> C[list_files.go
+ Directory Listing] C --> D[bash_tool.go
+ Shell Commands] D --> E[edit_tool.go
+ File Editing] E --> F[code_search_tool.go
+ Code Search] end subgraph "Tool Capabilities" G[No Tools] --> H[read_file] H --> I[read_file
list_files] I --> J[read_file
list_files
bash] J --> K[read_file
list_files
bash
edit_file] K --> L[read_file
list_files
bash
code_search] end A -.-> G B -.-> H C -.-> I D -.-> J E -.-> K F -.-> L ``` 最后，你将获得一个强大的本地开发者助手！ ## 🧱 它是如何工作的（架构） 每个智能体的工作方式如下： 1. 等待你的输入 2. 将其发送给 Claude 3. Claude 可能直接响应或请求使用工具 4. 智能体运行工具（例如，读取文件） 5. 将结果发送回 Claude 6. Claude 给你最终答案 我们称之为 **事件循环 (event loop)** —— 它就像智能体的心跳。 ``` graph TB subgraph "Agent Architecture" A[Agent] --> B[Anthropic Client] A --> C[Tool Registry] A --> D[getUserMessage Function] A --> E[Verbose Logging] end subgraph "Shared Event Loop" F[Start Chat Session] --> G[Get User Input] G --> H{Empty Input?} H -->|Yes| G H -->|No| I[Add to Conversation] I --> J[runInference] J --> K[Claude Response] K --> L{Tool Use?} L -->|No| M[Display Text] L -->|Yes| N[Execute Tools] N --> O[Collect Results] O --> P[Send Results to Claude] P --> J M --> G end subgraph "Tool Execution Loop" N --> Q[Find Tool by Name] Q --> R[Execute Tool Function] R --> S[Capture Result/Error] S --> T[Add to Tool Results] T --> U{More Tools?} U -->|Yes| Q U -->|No| O end ``` ## 🚀 开始使用 ### ✅ 前置条件 * Go 1.24.2+ 或 [devenv](https://devenv.sh/)（推荐，易于设置） * 一个 [Anthropic API Key](https://www.anthropic.com/product/claude) ### 🔧 设置你的环境 **选项 1：推荐（使用 devenv）** ``` devenv shell # Loads everything you need ``` **选项 2：手动设置** ``` # 确保已安装 Go go mod tidy ``` ### 🔐 添加你的 API Key ``` export ANTHROPIC_API_KEY="your-api-key-here" ``` ## 🏁 从基础开始 ### 1. `chat.go` —— 基础聊天 一个与 Claude 对话的简单聊天机器人。 ``` go run chat.go ``` * ➡️ 尝试：“Hello!” * ➡️ 添加 `--verbose` 以查看详细日志 ## 🛠️ 添加工具（一步步来） ### 2. `read.go` —— 读取文件 现在 Claude 可以从你的计算机读取文件了。 ``` go run read.go ``` * ➡️ 尝试：“Read fizzbuzz.js” ### 3. `list_files.go` —— 浏览文件夹 让 Claude 可以查看你的目录。 ``` go run list_files.go ``` * ➡️ 尝试：“List all files in this folder” * ➡️ 尝试：“What’s in fizzbuzz.js?” ### 4. `bash_tool.go` —— 运行 Shell 命令 允许 Claude 运行安全的终端命令。 ``` go run bash_tool.go ``` * ➡️ 尝试：“Run git status” * ➡️ 尝试：“List all .go files using bash” ### 5. `edit_tool.go` —— 编辑文件 Claude 现在可以 **修改代码**、创建文件和进行更改。 ``` go run edit_tool.go ``` * ➡️ 尝试：“Create a Python hello world script” * ➡️ 尝试：“Add a comment to the top of fizzbuzz.js” ### 6. `code_search_tool.go` —— 搜索代码 使用模式搜索（由 [ripgrep](https://github.com/BurntSushi/ripgrep) 驱动）。 ``` go run code_search_tool.go ``` * ➡️ 尝试：“Find all function definitions in Go files” * ➡️ 尝试：“Search for TODO comments” ## 🧪 示例文件（已包含） 1. `fizzbuzz.js`：用于文件读取和编辑 2. `riddle.txt`：一个有趣的文本文件供探索 3. `AGENT.md`：关于项目环境的信息 ## 🐞 故障排除 **API Key 不起作用？** * 确保它已导出：`echo $ANTHROPIC_API_KEY` * 在 [Anthropic’s dashboard](https://www.anthropic.com) 检查你的配额 **Go 错误？** * 运行 `go mod tidy` * 确保你使用的是 Go 1.24.2 或更高版本 **工具错误？** * 使用 `--verbose` 获取完整的错误日志 * 检查文件路径和权限 **环境问题？** * 使用 `devenv shell` 以避免配置问题 ## 💡 工具如何工作（底层原理） 工具就像插件。你需要定义： * **名称**（例如，`read_file`） * **输入 Schema**（它需要什么信息） * **函数**（它做什么） Go 中的工具定义示例： ``` var ToolDefinition = ToolDefinition{ Name: "read_file", Description: "Reads the contents of a file", InputSchema: GenerateSchema[ReadFileInput](), Function: ReadFile, } ``` Schema 生成使用 Go structs —— 因此定义和重用都很容易。 ## 🧭 研讨会路径：通过构建来学习 | 阶段 | 关注点 | | ----- | ------------------------------------------------ | | **1** | `chat.go`: API 集成和响应处理 | | **2** | `read.go`: 工具系统，Schema 生成 | | **3** | `list_files.go`: 多工具，文件系统 | | **4** | `bash_tool.go`: Shell 执行，错误捕获 | | **5** | `edit_tool.go`: 文件编辑，安全检查 | | **6** | `code_search_tool.go`: 模式搜索，ripgrep | ## 🛠️ 开发者环境（可选） 如果你使用 [`devenv`](https://devenv.sh/)，它会为你提供： * Go, Node, Python, Rust, .NET * Git 和其他开发工具 ``` devenv shell # Load everything devenv test # Run checks hello # Greeting script ``` ## 🚀 接下来做什么？ 完成研讨会后，尝试构建： * 自定义工具（例如，API 调用器、网页抓取器） * 工具链（按顺序运行工具） * 记忆功能（跨会话记住事物） * 智能体的 Web UI * 与其他 AI 模型的集成 ## 📦 总结 本次研讨会帮助你： * 理解智能体架构 * 学习构建智能助手 * 逐步扩展能力 * 练习结合使用 Claude 和 Go 享受探索和构建你自己的 AI 驱动工具的乐趣！💻✨ 如果你有问题或想法，请随意 fork 仓库、开启 issue 或与社区交流！
标签：AI编程, Anthropic Claude, Coding Agent, Cursor, EVTX分析, Go语言, LLM应用开发, Roo Code, Shell执行, 代码助手, 威胁情报, 实战教程, 开发者工具, 技术研讨会, 提示词工程, 文件操作, 日志审计, 智能体构建, 程序破解, 策略决策点, 编程代理, 自动化编程, 软件开发