Terminal AI Agent in Go

A hands-on lab for building a terminal-based AI agent from scratch in Go, inspired by You Should Write An Agent by Fly.io.

Overview

This project walks you through building a fully functional agentic loop in Go — no frameworks, no magic. Just Go's standard library, the Anthropic API, and a terminal. By the end, you'll have an agent that can hold multi-turn conversations, call tools, and execute real actions on your machine.

Lab Checklist

Phase 1 — Project Setup

• Create a new Go module: go mod init agent
• Add the Anthropic Go SDK as a dependency (or use net/http raw)
• Store your API key in an environment variable and read it with os.Getenv
• Write a main.go with a basic REPL: read a line, print it back

Phase 2 — Single-Turn LLM Call

• Define a Message struct with Role and Content fields
• Implement a callClaude(messages []Message) function that POSTs to the Anthropic /v1/messages endpoint
• Parse the JSON response and extract the assistant's reply text
• Print the reply in the terminal; confirm a single Q&A works end-to-end

Phase 3 — Multi-Turn Conversation

• Maintain a context []Message slice in memory across loop iterations
• Append each user message and each assistant reply to context before the next call
• Add a system message at index 0 to give the agent a persona or instructions
• Verify the agent remembers previous turns in a 5-message conversation

Phase 4 — Tool / Function Calling

• Define a Tool struct matching Anthropic's JSON schema (name, description, input_schema)
• Implement at least one concrete tool — e.g. run_shell that executes a bash command via os/exec
• Pass the tools array with every callClaude invocation
• Detect tool_use blocks in the response and dispatch to the correct Go function
• Append tool results back to context as tool_result messages and loop until no more tool calls

Phase 5 — Polish & Context Engineering

• Add a --verbose flag that prints each tool call name and args before executing
• Implement a token-budget guard: if context length exceeds N turns, summarize old messages
• Persist conversation history to a JSON file so sessions survive restarts

Prerequisites

• Go 1.21+
• An Anthropic API key

Getting Started

git clone https://github.com/your-username/agent
cd agent
go mod tidy

Create a .env file:

ANTHROPIC_API_KEY=sk-ant-...

Run the agent:

go run main.go

Project Structure

agent/
├── main.go          # Entry point and REPL loop
├── llm.go           # Anthropic API client
├── tools.go         # Tool definitions and handlers
├── history.json     # Persisted conversation history (Phase 5)
├── .env             # API keys (never commit this)
├── .gitignore
└── go.mod

.gitignore

.env
history.json
agent

References

• You Should Write An Agent — Fly.io Blog
• Anthropic API Docs
• contextwindow — Fly.io's own Go agent