beads/examples/go-agent/README.md

Go Agent Example

Example Go agent that uses bd with optional Agent Mail coordination for multi-agent workflows.

Features

• Uses native Go Agent Mail client (pkg/agentmail)
• Graceful degradation when Agent Mail unavailable
• Handles reservation conflicts
• Discovers and links new work
• Environment-based configuration

Usage

Git-only mode (no Agent Mail)

cd examples/go-agent
go run main.go --agent-name agent-alpha --max-iterations 5

With Agent Mail coordination

# Start Agent Mail server (in separate terminal)
cd integrations/agent-mail
python server.py

# Run agent
cd examples/go-agent
go run main.go \
  --agent-name agent-alpha \
  --project-id my-project \
  --agent-mail-url http://127.0.0.1:8765 \
  --max-iterations 10

Environment Variables

export BEADS_AGENT_NAME=agent-alpha
export BEADS_PROJECT_ID=my-project
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765

go run main.go

Multi-Agent Demo

Run multiple agents concurrently with Agent Mail:

# Terminal 1: Start Agent Mail server
cd integrations/agent-mail
python server.py

# Terminal 2: Agent Alpha
cd examples/go-agent
go run main.go --agent-name agent-alpha --agent-mail-url http://127.0.0.1:8765

# Terminal 3: Agent Beta
go run main.go --agent-name agent-beta --agent-mail-url http://127.0.0.1:8765

How It Works

1. Initialization: Creates Agent Mail client with health check
2. Find work: Queries bd ready for unblocked issues
3. Claim issue: Reserves via Agent Mail (if enabled) and updates status to in_progress
4. Work simulation: Processes the issue (sleeps 1s in this example)
5. Discover work: 33% chance to create linked issue via discovered-from dependency
6. Complete: Closes issue and releases Agent Mail reservation

Collision Handling

When Agent Mail is enabled:

• Issues are reserved before claiming (prevents race conditions)
• Conflicts return immediately (<100ms latency)
• Agents gracefully skip reserved issues

Without Agent Mail:

• Relies on git-based eventual consistency
• Higher latency (2-5s for sync)
• Collision detection via git merge conflicts

Comparison with Python Agent

The Go implementation mirrors the Python agent (examples/python-agent/agent_with_mail.py):

• ✅ Same API surface (ReserveIssue, ReleaseIssue, Notify, CheckInbox)
• ✅ Same graceful degradation behavior
• ✅ Same environment variable configuration
• ✅ Native Go types and idioms (no shell exec for Agent Mail)

Key differences:

• Go uses pkg/agentmail.Client instead of lib/beads_mail_adapter.py
• Go struct methods vs Python class methods
• Type safety with Go structs