跳转至

沿工具注册表读懂编码 Agent

编码 Agent 需要把模型提出的操作变成真实函数调用，再把结果送回上下文。本教程对应 agent_new.py 的模块化实现。先读主实验，再沿工具定义、注册、执行和结果回传四个环节阅读本页。

从声明走到执行

tools.json 给出模型可见的名称、参数和说明；tool_registry.py 把名称映射到实现；system_state.py 管理工作目录等状态；agent_new.py 组织消息与工具循环。一个工具被列在 schema 中，并不说明已经实现了全部能力，还需检查具体类与返回值。

例如，选择一个读取文件的工具，先写出模型需要提供的路径，再找到路径如何解析、文件不存在时怎样返回错误，以及内容如何进入下一轮工具消息。这条路径读通以后，再观察写入与编辑操作。

按职责阅读工具

职责 工具 需要核对的问题
文件读写 Read、Write、Edit、MultiEdit 输入路径、内容类型、精确匹配与写入后的检查是什么？
查找 Grep、Glob、LS 查询模式、过滤范围和输出格式如何影响后续决策？
Shell Bash、BashOutput、KillBash 会话怎样保持，后台任务怎样返回结果和结束？
进展管理 TodoWrite、ExitPlanMode 状态怎样更新并进入模型上下文？
其他接口 NotebookEdit、WebFetch、WebSearch、Task 哪些有具体实现，哪些仍是占位接口？

早期英文说明把整套工具概括为 pure Python，并列出 WebFetch、WebSearch、Task 的 stub 状态。应逐个区分 Python 内实现的文件搜索与需要系统环境的 Shell 操作；不要把“有工具名称”或“使用 Python 编写”解释为没有任何系统依赖。

配置并运行一个小任务

按下方完整安装与配置示例准备服务凭据，并确认调用入口确实使用 agent_new.py。在独立练习目录放一个短文本，先让 Agent 读取并复述一个可核对的值；再让它修改一个函数，运行检查，最后调整一项需求。

每轮同时记录模型请求、工具参数、执行返回值和后续决定。这样可以判断失败来自模型选择、工具输入、路径状态，还是执行后的反馈。原始 CLI、Python 调用和工具扩展示例完整保留在后半部分，阅读时可逐项对应到上述模块。

理解状态提示和错误反馈

时间戳、重复调用计数、TODO、工作目录、操作系统和 Python 版本都可以作为状态信息进入上下文。重复调用提醒用于让模型重新检查路径，不能保证它会修正根因；Write/Edit/MultiEdit 后的检查也只能覆盖实现所支持的语言和错误类型。

持久 Shell 会话与后台运行需要分别理解：前者使工作目录或环境变化继续有效，后者允许任务尚未结束时返回控制权。读取后台输出前，先确认对应任务标识；结束会话后，不能继续假设其中状态存在。

添加工具时检查完整接口

先定义模型可见的参数与返回约定，再实现处理函数并加入注册表。使用有效输入、缺失参数和失败路径分别检查，最后让 Agent 在完整循环里调用它。下方保留了原始目录树、配置示例、接口说明与排错细节；遇到声称通用或生产可用的描述，应以具体实现和测试范围判断。

思考：两个工具都读取文件，一个返回纯文本，另一个返回结构化对象，Agent 的结果回传逻辑需要处理哪些差别？

English

Comprehensive Coding Agent - Pure Python Implementation

A production-ready AI coding agent built with Claude, implementing all techniques from Chapter 2 with pure Python tools - no command-line dependencies required!

🌟 Key Features

✅ Pure Python Implementation

All tools implemented without command-line dependencies: - ❌ No grep, rg (ripgrep), find commands needed - ❌ No dependency on system utilities - ✅ 100% pure Python implementations - ✅ Works on any system with Python 3.8+ - ✅ Especially designed for Mac users without command-line tools

🛠️ Complete Tool Suite

All 17 tools from tools.json fully implemented:

File Operations (Pure Python): - Read - File reading with image/PDF/notebook support - Write - File writing with auto lint checking - Edit - Search and replace editing - MultiEdit - Multiple edits in one operation

Search Tools (Pure Python, no rg/grep dependency): - Grep - Pure Python regex search with full ripgrep feature parity - Full regex support - Case insensitive search - Context lines (before/after/around) - Line numbers - Multiline mode - Glob filtering - File type filtering - Multiple output modes - Glob - File pattern matching - LS - Directory listing

Shell Operations: - Bash - Persistent shell sessions - BashOutput - Background job output - KillBash - Terminate shells

Project Management: - TodoWrite - Task list management - ExitPlanMode - Plan mode exit

Advanced: - NotebookEdit - Jupyter notebook editing - WebFetch - Web content fetching (stub) - WebSearch - Web search (stub) - Task - Sub-agent launcher (stub)

🧠 System Hint Techniques (Chapter 2)

  1. Timestamps: Every message and tool result timestamped
  2. Tool Call Counting: Warns after 3+ repeated calls
  3. TODO List Management: Explicit task tracking
  4. Detailed Error Information: Rich error context
  5. System State Awareness: Working directory, OS, Python version
  6. Environment Information: Dynamic state in context

🔧 Terminal Environment

  • Persistent Shell Sessions: Commands in same shell
  • Working Directory Tracking: Directory changes persist
  • Background Execution: Long-running command support

✅ Auto Lint Detection

After Write/Edit/MultiEdit: - Python syntax checking - JavaScript/TypeScript checking
- Errors appear immediately in tool results

📁 Project Structure

coding-agent/
├── agent.py                    # Main agent implementation
├── system_state.py            # System state tracking
├── tool_registry.py           # Tool name → implementation mapping
├── tools/                     # All tool implementations
│   ├── __init__.py
│   ├── base.py               # Base tool class
│   ├── bash_tool.py          # Shell execution
│   ├── bash_output_tool.py   # Background job output
│   ├── kill_bash_tool.py     # Shell termination
│   ├── read_tool.py          # File reading
│   ├── write_tool.py         # File writing
│   ├── edit_tool.py          # File editing
│   ├── multi_edit_tool.py    # Multiple edits
│   ├── grep_tool.py          # 🔥 Pure Python regex search (no rg!)
│   ├── glob_tool.py          # File pattern matching
│   ├── ls_tool.py            # Directory listing
│   ├── todo_write_tool.py    # TODO management
│   ├── exit_plan_mode_tool.py
│   ├── notebook_edit_tool.py
│   ├── web_fetch_tool.py
│   ├── web_search_tool.py
│   ├── task_tool.py
│   └── shell_session.py      # Shell session management
├── tools.json                 # Tool definitions
├── system-prompt.md          # System prompt
├── config.py                 # Configuration
├── requirements.txt          # Dependencies
└── README.md                 # This file

🚀 Installation

# Navigate to project directory
cd /Users/boj/ai-agent-book/projects/week5/coding-agent

# Install dependencies (minimal!)
pip install -r requirements.txt

# Set up environment
cp .env.example .env
# Edit .env and add your API key

Requirements

Minimal dependencies: - Python 3.8+ - anthropic library - python-dotenv

Optional (for enhanced features): - PyPDF2 - For PDF reading - requests, beautifulsoup4, html2text - For WebFetch

No command-line tools needed! Works on macOS without Homebrew packages.

📖 Usage

Basic Example

from agent import CodingAgent

agent = CodingAgent(api_key="your-key")

for event in agent.run("List all Python files"):
    if event["type"] == "text_delta":
        print(event["delta"], end="", flush=True)
    elif event["type"] == "done":
        print("\n✅ Done!")

Run Examples

# Basic quickstart
python quickstart.py

# Complex multi-step task
python example_complex_task.py

# System hints demonstration
python example_with_system_hints.py

🔍 Pure Python Grep Implementation

The Grep tool is fully implemented in pure Python without any dependency on grep, rg, or other command-line tools. It provides all the features of ripgrep:

# Example: Search for pattern in files
{
    "name": "Grep",
    "input": {
        "pattern": "def.*test",
        "path": "/path/to/search",
        "output_mode": "content",
        "-i": True,              # Case insensitive
        "-C": 3,                 # 3 lines context
        "-n": True,              # Show line numbers
        "glob": "*.py",          # Only Python files
        "multiline": False       # Single line matching
    }
}

Features: - ✅ Full regex support (Python re module) - ✅ Case insensitive search (-i) - ✅ Context lines (-A, -B, -C) - ✅ Line numbers (-n) - ✅ Multiline mode - ✅ Glob filtering (glob parameter) - ✅ File type filtering (type parameter) - ✅ Output modes: content, files_with_matches, count - ✅ Head limit - ✅ Recursive directory search - ✅ Binary file skip - ✅ Hidden file/directory skip

🏗️ Architecture

Modular Tool System

Each tool is implemented as a separate class inheriting from BaseTool:

class MyTool(BaseTool):
    @property
    def name(self) -> str:
        return "MyTool"

    def _execute_impl(self, params: Dict[str, Any]) -> Dict[str, Any]:
        # Tool implementation
        return {"result": "success"}

Tool Registry

ToolRegistry maps tool names to implementations:

registry = ToolRegistry()
tool = registry.get_tool("Grep", system_state)
result = tool.execute(params)

System State

SystemState tracks: - Current working directory - Tool call counts - TODO list - Shell sessions - Environment info

System Hints

System hints are injected before each LLM call:

<system_hint>
# System State
Current Time: 2025-10-12 15:30:45
Working Directory: /Users/boj/coding-agent
OS: Darwin
Python: Python 3.11.5

# Tool Call Statistics
- Grep: 2 calls
- Write: 1 calls

# Current TODO List
✅ [1] Search for files (completed)
🔄 [2] Implement feature (in_progress)
⬜ [3] Write tests (pending)
</system_hint>

🎯 Design Principles

1. Pure Python Implementation

Why: Maximum portability and compatibility - Works on any system with Python - No Homebrew, apt, or other package managers needed - Consistent behavior across platforms

2. Modular Tool Architecture

Why: Maintainability and extensibility - Each tool is self-contained - Easy to add new tools - Easy to test individually - Clear separation of concerns

3. No Command-Line Dependencies

Why: Reliability and control - Grep: Pure Python regex search - Glob: Python's pathlib.glob() - LS: Python's os and pathlib - No subprocess calls for core functionality - Full control over behavior

4. System Hints for Self-Awareness

Why: Better agent behavior - Prevents infinite loops (tool call counting) - Maintains task focus (TODO tracking) - Provides environmental context - Enables self-monitoring

📊 Comparison with Chapter 2

Technique Status Implementation
Standard OpenAI Tool Format ✅ Anthropic SDK
Streaming Tool Calls ✅ Real-time JSON delta parsing
Parallel Tool Calls ✅ Multiple tools per response
Pure Python Tools ✅ No command-line dependencies
Grep without rg ✅ Pure Python regex search
Timestamps ✅ All messages/tools
Tool Call Counting ✅ Warns at 3+
TODO List ✅ TodoWrite tool
System State ✅ Working dir, OS, Python
Persistent Shell ✅ Shell sessions
Auto Lint Detection ✅ After Write/Edit/MultiEdit

🔧 Configuration

.env file:

# Required
ANTHROPIC_API_KEY=your_key_here

# Optional
DEFAULT_MODEL=claude-sonnet-4-20250514
MAX_ITERATIONS=50
MAX_TOKENS=8192

📝 Adding New Tools

  1. Create tool file in tools/:
# tools/my_tool.py
from .base import BaseTool

class MyTool(BaseTool):
    @property
    def name(self) -> str:
        return "MyTool"

    def _execute_impl(self, params):
        # Implementation
        return {"result": "success"}
  1. Register in tools/__init__.py:
from .my_tool import MyTool

__all__ = [..., 'MyTool']
  1. Add to tool_registry.py:
self._tools = {
    ...,
    "MyTool": MyTool,
}
  1. Add definition to tools.json

🐛 Troubleshooting

"No module named 'tools'"

Make sure you're running from the project directory: 

cd /Users/boj/ai-agent-book/projects/week5/coding-agent
python agent.py

Grep not finding files

Check: - Path is correct - Pattern is valid regex - Glob pattern matches files - Files contain searchable text (not binary)

Shell commands fail

Ensure: - Bash is available on PATH on macOS/Linux - PowerShell is available on PATH on Windows (cmd.exe is used as a fallback) - Working directory exists - Commands use the native shell syntax and are properly quoted

🎓 Learning Path

  1. Start with examples: Run quickstart.py
  2. Explore system hints: Run example_with_system_hints.py
  3. Study Grep implementation: See tools/grep_tool.py
  4. Read Chapter 2: Understand the theory
  5. Add custom tools: Extend the system

📚 References

  • Chapter 2: Context Engineering (AI Agent Book)
  • Tools specification: tools.json
  • System prompt: system-prompt.md
  • Anthropic Claude API: https://docs.anthropic.com/

🎉 Key Advantages

  1. No Dependencies on External Tools
  2. Pure Python implementation
  3. Works without rg, grep, find, etc.

  4. Perfect for Mac users without Homebrew

  5. Modular Architecture

  6. Each tool is a separate file
  7. Easy to understand and modify

  8. Clear separation of concerns

  9. Production Ready

  10. Comprehensive error handling
  11. Auto lint detection
  12. System hints for reliability

  13. Streaming support for UX

  14. Educational Value

  15. Learn how tools work internally
  16. Understand pure Python file operations
  17. See regex search implementation
  18. Study agent architecture patterns

📄 License

MIT

🤝 Contributing

This is an educational implementation. Feel free to adapt and extend!

Built with pure Python for maximum portability and learning! 🐍✨