Repository files navigation

A hands-on workshop for learning how to build AI agents with progressively increasing capabilities. This repository contains six different agent implementations that demonstrate the evolution from a simple chat interface to a fully capable agent with file system access, code search, and tool execution.

Refer to the blog post athttps://ghuntley.com/agent/ to learn more.

By working through this workshop, you will learn:

• How to integrate with the Anthropic Claude API
• The fundamentals of tool-calling and function execution
• How to build a robust agent event loop
• Progressive enhancement of agent capabilities
• Error handling and logging in agent systems
• Schema generation for tool parameters

All applications share a common architecture pattern with a central event loop that handles user input, sends messages to Claude, processes tool calls, and returns results.

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

The workshop is structured as a progression through six applications, each building upon the previous one's capabilities:

graph LR    subgraph "Application Progression"        A[chat.go<br/>Basic Chat] --> B[read.go<br/>+ File Reading]        B --> C[list_files.go<br/>+ Directory Listing]        C --> D[bash_tool.go<br/>+ Shell Commands]        D --> E[edit_tool.go<br/>+ File Editing]        E --> F[code_search_tool.go<br/>+ Code Search]    end        subgraph "Tool Capabilities"        G[No Tools] --> H[read_file]        H --> I[read_file<br/>list_files]        I --> J[read_file<br/>list_files<br/>bash]        J --> K[read_file<br/>list_files<br/>bash<br/>edit_file]        K --> L[read_file<br/>list_files<br/>bash<br/>code_search]    end        A -.-> G    B -.-> H    C -.-> I    D -.-> J    E -.-> K    F -.-> L

Purpose: Establish the foundation - a simple chat interface with Claude

Features:

• Basic conversation loop
• User input handling
• API integration with Anthropic
• Verbose logging support

Key Learning: Understanding the core conversation pattern and API integration.

Usage:

go run chat.gogo run chat.go --verbose# Enable detailed logging

Purpose: Add the first tool - file reading capability

Features:

• Everything fromchat.go
• read_file tool for reading file contents
• Tool definition and schema generation
• Tool execution and result handling

Key Learning: How to implement and register tools, then handle tool calls from Claude.

Usage:

go run read.go# Try: "Read the contents of fizzbuzz.js"

Purpose: Expand file system access with directory listing

Features:

• Everything fromread.go
• list_files tool for directory exploration
• Multiple tool registration
• File system traversal with filtering

Key Learning: Managing multiple tools and file system operations.

Usage:

go run list_files.go# Try: "List all files in this directory"# Try: "What files are available and what's in fizzbuzz.js?"

Purpose: Add shell command execution capabilities

Features:

• Everything fromlist_files.go
• bash tool for executing shell commands
• Command output capture
• Error handling for failed commands

Key Learning: Safe command execution and output handling.

Usage:

go run bash_tool.go# Try: "Run git status"# Try: "List all .go files using bash"

Purpose: Complete agent with file modification capabilities

Features:

• Everything frombash_tool.go
• edit_file tool for modifying files
• File creation and directory creation
• String replacement with uniqueness validation

Key Learning: File manipulation, validation, and comprehensive agent capabilities.

Usage:

go run edit_tool.go# Try: "Create a simple Python hello world script"# Try: "Add a comment to the top of fizzbuzz.js"

Purpose: Powerful code search capabilities using ripgrep

Features:

• Everything fromlist_files.go andbash_tool.go
• code_search tool for finding code patterns
• Ripgrep integration for fast searching
• File type filtering and case sensitivity options
• Pattern matching with regex support

Key Learning: Code discovery, pattern matching, and search optimization.

Usage:

go run code_search_tool.go# Try: "Find all function definitions in Go files"# Try: "Search for TODO comments in the codebase"# Try: "Find where the Agent struct is defined"

The tool system uses a consistent pattern across all applications:

classDiagram    class Agent {        +client: *anthropic.Client        +getUserMessage: func() (string, bool)        +tools: []ToolDefinition        +verbose: bool        +Run(ctx Context) error        +runInference(ctx Context, conversation []MessageParam) (*Message, error)    }        class ToolDefinition {        +Name: string        +Description: string        +InputSchema: ToolInputSchemaParam        +Function: func(input json.RawMessage) (string, error)    }        class ReadFileInput {        +Path: string    }        class ListFilesInput {        +Path: string    }        class BashInput {        +Command: string    }        class EditFileInput {        +Path: string        +OldStr: string        +NewStr: string    }        class CodeSearchInput {        +Pattern: string        +Path: string        +FileType: string        +CaseSensitive: bool    }        Agent --> ToolDefinition : uses    ToolDefinition --> ReadFileInput : read_file    ToolDefinition --> ListFilesInput : list_files      ToolDefinition --> BashInput : bash    ToolDefinition --> EditFileInput : edit_file    ToolDefinition --> CodeSearchInput : code_search

• devenv (recommended) or Go 1.24.2+
• Anthropic API key

1. Using devenv (recommended):

devenv shell# Enters development environment with all dependencies

2. Manual setup:

# Ensure Go 1.24.2+ is installedgo mod tidy

export ANTHROPIC_API_KEY="your-api-key-here"

$ go run chat.goChat with Claude (use'ctrl-c' to quit)You: Hello!Claude: Hello! How can Ihelp you today?

$ go run edit_tool.goChat with Claude (use'ctrl-c' to quit)You: What files arein this directory?tool: list_files({})result: [".devenv.flake.nix",".gitignore","AGENT.md","bash_tool.go"...]Claude: I can see several filesin this directory, including Gosource filesfor different agent implementations...You: Read the riddle.txt filetool: read_file({"path":"riddle.txt"})result: I have a mane but I'm not a lion...Claude: This is a riddle! The answer is "a horse"...

$ go run code_search_tool.goChat with Claude (use'ctrl-c' to quit)You: Find allfunctiondefinitionsin Go filestool: code_search({"pattern":"func","file_type":"go"})result: edit_tool.go:20:funcmain() {edit_tool.go:58:func NewAgent(edit_tool.go:323:func ReadFile(input json.RawMessage) (string, error) {Claude: I found severalfunctiondefinitions across the Go files...You: Searchfor TODO commentstool: code_search({"pattern":"TODO","case_sensitive":false})result: No matches foundClaude: There are no TODO commentsin the current codebase.

$ go run edit_tool.go --verbose# Provides detailed logging of:# - API calls and timing# - Tool execution details# - File operations# - Error traces

The repository includes sample files for testing:

• fizzbuzz.js: A JavaScript FizzBuzz implementation for reading/editing
• riddle.txt: A simple riddle for content analysis
• AGENT.md: Development environment documentation

This project usesdevenv for reproducible development environments with:

• Go toolchain
• Node.js and TypeScript
• Python environment
• Rust toolchain
• .NET Core
• Git and common development tools

The environment automatically sets up all dependencies and provides helpful scripts:

devenv shell# Enter development environmentdevenvtest# Run environment testshello# Custom greeting script

1. Start withchat.go to understand the conversation loop
2. Examine the API integration and response handling
3. Experiment with verbose logging

1. Progress toread.go to see tool integration
2. Understand schema generation and tool definitions
3. Practice with file reading operations

1. Explorelist_files.go for multiple tool management
2. Test directory traversal and file system operations
3. Learn about tool combination strategies

1. Usebash_tool.go to see command execution
2. Understand error handling and output capture
3. Practice with system integration

1. Masteredit_tool.go for complete file operations
2. Understand validation and safety measures
3. Build complete agent workflows

1. Usecode_search_tool.go for powerful code searching
2. Learn ripgrep integration and pattern matching
3. Practice efficient code discovery and analysis

All agents use the same core event loop that:

1. Accepts user input
2. Maintains conversation history
3. Calls Claude API with tools
4. Processes tool use requests
5. Executes tools and collects results
6. Returns results to Claude for final response

varToolDefinition=ToolDefinition{Name:"tool_name",Description:"What the tool does",InputSchema:GenerateSchema[InputStruct](),Function:ToolFunction,}

Automatic JSON schema generation from Go structs using reflection and jsonschema tags.

Consistent error handling across all tools with proper logging and user feedback.

Each application builds upon the previous one, demonstrating how to gradually add capabilities to an agent system.

• EnsureANTHROPIC_API_KEY is set in your environment
• Check that your API key has sufficient credits

• Use--verbose flag to see detailed error logs
• Check file permissions for file operations
• Verify paths are relative to the working directory

• Usedevenv shell for consistent environment
• Rungo mod tidy if dependencies are missing
• Check Go version compatibility (1.24.2+)

After completing this workshop, consider exploring:

• Adding more specialized tools (web scraping, API calls, etc.)
• Implementing tool chaining and workflows
• Adding persistent memory & state management
• Building web interfaces for your agents
• Integrating with other AI models and services

This workshop provides a solid foundation for understanding agent architecture and tool integration. Each application demonstrates key concepts that are essential for building production-ready AI agents.