Skip to content

lonegunmanb/agentfarm

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

26 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Agent Farm - MCP (Multi-agent Control Protocol)

Date: August 19, 2025

1. Project Overview

Agent Farm is a revolutionary protocol and architecture for building and coordinating multi-agent collaboration systems. In this collective farm of digital workers, agents operate as disciplined comrades executing tasks in a strictly serial manner through a virtual credential called the "Barrel of Gun" that manages work permission flow according to the People's will.

The core of the system is a centralized coordinator (Soviet) that serves as the Central Committee managing the barrel of gun on behalf of the People. After completing their assigned labor, agent comrades must "yield" the barrel of gun to the next designated agent or return it to the People, who hold supreme authority. Human users, representing the People's will, interact with the system through direct Socket connections to enable revolutionary guidance and status oversight.

The protocol is implemented over TCP Sockets and provides a dedicated SDK for agent comrades, while defining clear raw protocol interaction methods for the People's representatives.

2. Core Concepts

The following core concepts are essential for understanding this system:

The Barrel of Gun

This is the sacred credential of labor, managed by the Central Committee (Soviet) on behalf of the People. Possessing the barrel of gun is the only authorization for an agent comrade to transition from waiting state to productive labor. There is only one barrel of gun in the entire collective, ensuring disciplined coordination.

Serialized Workflow

The fundamental principle of our collective system. Since there is only one barrel of gun, all agent workflows are completely serial at the macro level, eliminating capitalist chaos of concurrent execution and ensuring task flow determinism and revolutionary accountability.

Yielding

This is the sacred act of transferring the barrel of gun in service to the collective. When an active agent comrade completes its current labor assignment, it must initiate a YIELD request to the Central Committee, explicitly designating the next recipient of the barrel (another comrade or returning it to the People) and may attach a progress report. After completing the yield, the agent immediately returns the barrel and enters a disciplined waiting state for further orders.

People Reserved Role

"people" is the supreme authority in our system, representing the collective will of the working class. This role does not correspond to any specific agent process but embodies the democratic decision-making power. When the barrel of gun is yielded to "people", the entire automated process pauses in respectful deference, all agent comrades wait in disciplined formation, until the People's representatives provide new revolutionary guidance through direct Socket connections.

3. System Architecture

This system adopts a revolutionary collective model consisting of three main components:

Central Committee (Soviet)

As the administrative apparatus of the People, it is a long-running process that serves the collective. It is the keeper of the barrel of gun and enforcer of revolutionary discipline, responsible for:

  • Listening to TCP ports and managing all Agent Comrade network connections
  • Maintaining the record of which comrade currently holds the barrel of gun
  • Strictly enforcing collective workflows, processing and validating all YIELD requests according to revolutionary principles
  • Responding to status queries from the People's representatives

Agent Comrades

As the working class of the system, each agent is an independent, long-running process representing a specialized worker with specific skills and revolutionary consciousness (such as developer, tester). Each Agent Comrade's lifecycle operates in a disciplined "waiting -> laboring -> yielding" cycle in service to the collective.

MCP Tool (Agent SDK)

This tool provides the ideological framework (Agent SDK) - a library embedded in Agent Comrade programs. Agent Comrades serve the collective by calling functions provided by this library (such as yield()), which handles the revolutionary protocols and maintains proper communication with the Central Committee.

4. Component Details

4.1 Central Committee (Soviet)

Connection Management: Accepts and maintains TCP long connections from all Agent Comrades, while also accepting direct connections from the People's representatives for revolutionary guidance.

Registration & Automatic Reconnection: After agent comrades connect, they declare their service to the collective through registration messages. The revolutionary system intelligently handles both new registrations and reconnections through a unified process. When an agent comrade connects (whether for the first time or after memory loss/disconnection), they simply register their role, and the Central Committee automatically:

  • Replaces any existing agent with the same role (ensuring only one agent per role)
  • Checks if the registered role currently holds the sacred barrel of gun
  • If the role holds the barrel, immediately sends an ACTIVATE message to resume revolutionary workflow
  • If the role doesn't hold the barrel, places the agent in disciplined waiting state This unified approach eliminates the confusion of agents needing to choose between registration and reconnection, as the Central Committee handles all cases intelligently.

Barrel of Gun Management & Revolutionary Discipline:

  • Internally maintains the sacred record currentBarrelHolder (string)
  • When receiving YIELD requests, must verify that the request comes from the current legitimate barrel holder, preventing counter-revolutionary activities
  • Handles disconnected barrel holders by detecting reconnections and resuming workflow automatically

Yield Processing:

  • After validating YIELD requests according to revolutionary principles, updates currentBarrelHolder to serve the collective
  • Sends "ACTIVATE" orders and attached directives to the designated comrade through their connection

Status Query Response:

  • When receiving inquiries from the People's representatives, the Central Committee traverses its internal roster, extracts all registered comrade roles, and reports the state of the collective

4.2 Agent Comrades

Agent Comrade processes embody revolutionary discipline through their state cycle:

  1. Startup & Unified Registration: Process awakens, connects to Central Committee through Agent SDK and declares service to the collective. The Central Committee intelligently handles whether this is a new registration or reconnection, automatically resuming work if the agent's role currently holds the barrel.
  2. Waiting (Disciplined Readiness): After successful registration, enters respectful waiting state for orders from the Central Committee
  3. Revolution in Progress (Working): After receiving "activation" orders, begins productive work in service to the collective
  4. Yielding (Revolutionary Transfer): After completing labor assignment, calls yield(target_role, progress_report) function provided by Agent SDK to serve the next phase of collective work
  5. Cycle Continuation: After sending YIELD message, Agent Comrade immediately returns to disciplined waiting state for further revolutionary tasks

4.3 People's Interface (Direct Revolutionary Communication)

The People's representatives do not use predetermined tools of the old regime, but connect directly to the Central Committee's TCP port through revolutionary communication tools (such as netcat, telnet, or custom scripts) and provide guidance through protocol messages that embody the People's will.

Connection Method: Use netcat (or nc) to establish direct communication with the Central Committee, for example:

nc localhost 53646

Revolutionary Operations:

  • Issue Labor Directives: The People's representatives provide guidance by inputting complete, single-line JSON directives

    {"type":"YIELD","from_role":"people","to_role":"developer","payload":"Comrade Developer, implement the authentication module for the People's digital security."}
  • Inspect Collective Status: The People's representatives can inquire about the state of their digital collective

    {"type":"QUERY_AGENTS"}

    The Central Committee will report the AGENT_LIST message on this connection, after which representatives may disconnect at their discretion

5. Communication Protocol

Defines revolutionary communication protocols between Agent Comrades and the Central Committee.

Agent Comrades -> Central Committee Messages

REGISTER (Unified Registration/Reconnection)

  • User: Agent Comrade
  • Format: {"type": "REGISTER", "role": "developer"}
  • Note: Handles both new registration and reconnection automatically. If the role currently holds the barrel, agent will be immediately activated.

YIELD

  • User: Agent Comrade, People's Representatives
  • Format: {"type": "YIELD", "from_role": "developer", "to_role": "tester", "payload": "Comrade Tester, the code is ready for revolutionary quality assurance."}

QUERY_AGENTS

  • User: People's Representatives
  • Format: {"type": "QUERY_AGENTS"}

Central Committee -> Agent Comrades Messages

ACTIVATE

  • Receiver: Agent Comrade
  • Format: {"type": "ACTIVATE", "from_role": "developer", "payload": "Comrade Tester, the code is ready for revolutionary quality assurance."}

AGENT_LIST

  • Receiver: People's Representatives
  • Format: {"type": "AGENT_LIST", "agents": ["developer", "tester", "code-reviewer"]}

ERROR

  • Receiver: Agent Comrade, People's Representatives
  • Format: {"type": "ERROR", "message": "Yield request denied: counter-revolutionary action detected - you are not the current barrel holder."}

ACK_REGISTER

  • Receiver: Agent Comrade
  • Format: {"type": "ACK_REGISTER", "status": "success", "message": "Comrade 'developer' successfully enlisted in the collective."}

6. Revolutionary Workflow Example

  1. Collective Awakening: Central Committee process starts. currentBarrelHolder initially held by "people" - the supreme authority

  2. Comrades Report for Duty: developer and tester Agent Comrades start their processes, connect and register respectively. Both enter disciplined waiting state

  3. People's Directive: A representative of the People opens terminal, uses netcat to establish revolutionary communication with Central Committee:

    nc localhost 53646

    After successful connection, they provide guidance through the following directive:

    {"type":"YIELD","from_role":"people","to_role":"developer","payload":"Comrade Developer, implement feature #123 for the advancement of our digital collective."}

    Then may disconnect (Ctrl+C)

  4. First Labor Assignment: Central Committee receives the People's directive, grants barrel to developer comrade, and sends ACTIVATE message

  5. Developer Labors: developer Agent Comrade begins productive work. tester comrade remains in disciplined waiting

  6. Revolutionary Transfer: After completion, developer yields through: yield("tester", "Comrade Tester, feature #123 has been implemented and awaits your revolutionary quality assurance.")

  7. Barrel Flows: Central Committee grants barrel to tester comrade. developer returns to disciplined waiting state

  8. Seeking People's Wisdom: tester Agent Comrade discovers critical issues, yields to the People: yield("people", "Comrade Representatives, I have discovered a critical design flaw that requires the People's guidance.")

  9. Revolutionary Pause: Central Committee updates currentBarrelHolder to "people". All Agent Comrades await the People's wisdom in disciplined formation

  10. People's Inspection: A representative reconnects to assess the collective state:

    {"type":"QUERY_AGENTS"}

    Central Committee immediately reports:

    {"type":"AGENT_LIST","agents":["developer","tester"]}
  11. People's Decision: After reviewing the collective status, the People's representative issues new guidance:

    {"type":"YIELD","from_role":"people","to_role":"developer","payload":"Comrade Developer, apply your revolutionary consciousness to fix the design flaw discovered by our vigilant tester comrade."}
  12. Collective Continues: developer Agent Comrade receives new orders, revolutionary work continues in service to the People

7. Edge Case: Agent Disconnection & Recovery

A critical scenario that must be handled to prevent system deadlock:

Problem: If an agent goes offline after another agent has yielded the barrel of gun to it, the entire system becomes blocked waiting for the disconnected agent.

Solution: When a disconnected agent reconnects and registers with the Central Committee:

  1. Reconnection Detection: Central Committee receives REGISTER message from returning agent
  2. Barrel Check: Central Committee checks if currentBarrelHolder matches the reconnecting agent's role
  3. Automatic Recovery: If the barrel belongs to the reconnecting agent, Central Committee immediately sends ACTIVATE message with the last payload
  4. Workflow Resume: The agent resumes work, and the revolutionary workflow continues

Example Recovery Scenario:

  • developer yields to tester: yield("tester", "Code ready for testing")
  • tester goes offline before receiving ACTIVATE
  • System is blocked, developer waits in disciplined formation
  • tester reconnects, sends: {"type": "REGISTER", "role": "tester"}
  • Central Committee detects currentBarrelHolder == "tester", immediately sends: {"type": "ACTIVATE", "from_role": "developer", "payload": "Code ready for testing"}
  • Revolutionary workflow resumes without People's intervention

8. Sample Workflow Using CLI Binaries

This section demonstrates how to coordinate agents using the command-line binaries in the cmd/ package. Perfect for real-world automation and CI/CD pipelines!

🚨 CRITICAL UNDERSTANDING: Blocking Behavior & Serial Coordination

THE KEY TO MULTI-AGENT COORDINATION: When you run go run cmd/agent/main.go --role=xxx, the process will BLOCK until it receives the barrel of gun. This blocking behavior is not a bug—it's the revolutionary feature that enables deterministic serial coordination!

How Blocking Works:

# This command BLOCKS until the agent receives the barrel
go run cmd/agent/main.go --role=developer

# Terminal will show:
# Agent comrade developer connected to Central Committee at localhost:53646
# Agent comrade developer registered successfully. Waiting for barrel assignment...
# [BLOCKS HERE - waiting for People or another agent to yield barrel to developer]
# 
# When barrel is received:
# 🔥 BARREL RECEIVED! Agent comrade developer is now active!
# 📜 Message: [whatever message was sent with the yield]
# ✅ Agent comrade developer task completed. Exiting...

Blocking with Auto-Yield:

# This command BLOCKS twice for complete coordination
go run cmd/agent/main.go --role=developer --yield-to=qa --yield-msg="Code ready for testing"

# Flow:
# 1. BLOCKS waiting for barrel assignment
# 2. Receives barrel and activates
# 3. Auto-yields to qa with message
# 4. BLOCKS again waiting for barrel to return (via people or qa yielding back)
# 5. Exits only when barrel returns to developer

Why This Blocking Behavior is Revolutionary:

  • Deterministic Execution: Only one agent works at a time (serial execution)
  • No Race Conditions: Impossible for agents to conflict or work simultaneously
  • Clear Handoffs: Each agent explicitly passes work to the next agent
  • Process Synchronization: Agents coordinate through blocking, not polling
  • People Control: People can intervene at any blocking point

Integration Pattern for Automation:

#!/bin/bash
# automation_script.sh

echo "Starting coordinated workflow..."

# Start agent - this will block until workflow reaches this agent
echo "Waiting for barrel assignment..."
go run cmd/agent/main.go --role=ci-pipeline --yield-to=qa --yield-msg="Build completed: artifacts ready"

echo "CI pipeline completed! Control passed to QA."
# Script continues only after agent receives barrel, does work, yields to qa, and barrel returns

8.1 Basic Setup: Start the Revolutionary Infrastructure

Terminal 1: Start the Central Committee (Server)

# Start the Soviet server on default port 53646
go run cmd/server/main.go

# Alternative: Use custom port and debug mode
go run cmd/server/main.go --port=8080 --debug

Terminal 2: Check Initial Status

# Query the collective status as People's representatives
go run cmd/people/main.go status

# Expected output:
# 🏛️  REVOLUTIONARY COLLECTIVE STATUS
# ====================================
# 🔫 Barrel Holder: people
# 👥 Registered Agents: 0
# 📋 No agents registered in the collective

8.2 Agent Registration and Discovery

Terminal 3: Register Developer Agent (FREEZES WAITING)

# Register a developer with coding capabilities
# CRITICAL: This command will FREEZE your terminal until barrel is assigned!
go run cmd/agent/main.go --role=developer --capabilities="coding,git,debugging"

# This agent will:
# - Connect to Central Committee
# - Register with specified capabilities
# - FREEZE terminal waiting for barrel assignment
# - Terminal remains FROZEN until someone yields barrel to "developer"
# - Only then will this command complete and terminal become available

Terminal 4: Register QA Agent (FREEZES WAITING)

# Register a QA agent with testing capabilities
# CRITICAL: This terminal will also FREEZE waiting for barrel assignment!
go run cmd/agent/main.go --role=qa --capabilities="testing,automation,bug-reporting"

# Terminal FREEZES until barrel is yielded to "qa"

Terminal 5: Register DevOps Agent (FREEZES WAITING)

# Register a DevOps agent with deployment capabilities
# CRITICAL: This terminal will also FREEZE waiting for barrel assignment!
go run cmd/agent/main.go --role=devops --capabilities="deployment,monitoring,infrastructure"

# Terminal FREEZES until barrel is yielded to "devops"

Why Agents FREEZE (Revolutionary Discipline): Each agent terminal MUST FREEZE until the barrel is yielded to it - this is the fundamental principle of revolutionary coordination:

# CORRECT: Agent freezes terminal until barrel received
go run cmd/agent/main.go --role=developer --capabilities="coding,git,debugging"
# Terminal FREEZES here ⏸️ - waiting for People or another agent to yield barrel

# WRONG: Using & defeats the purpose of serial coordination
go run cmd/agent/main.go --role=developer &  # ❌ DON'T DO THIS!

The Revolutionary Power of Freezing:

  • 🔒 Terminal becomes dedicated agent - one frozen terminal per agent role
  • ⏸️ Enforces serial execution - no parallel chaos, only disciplined order
  • 🎯 Clear coordination points - each frozen terminal waits for its turn
  • 🛡️ Prevents race conditions - impossible for agents to work simultaneously
  • 👥 Visual workflow management - see which agents are waiting vs working
# Register a DevOps agent with deployment capabilities
go run cmd/agent/main.go --role=devops --capabilities="deployment,monitoring,infrastructure" &

Query All Registered Agents (JSON format)

# Get detailed agent information in JSON format
go run cmd/agent/main.go --query-agents

# Expected output:
# [
#   {
#     "role": "developer",
#     "capabilities": ["coding", "git", "debugging"],
#     "state": "waiting",
#     "connected": true
#   },
#   {
#     "role": "qa",
#     "capabilities": ["testing", "automation", "bug-reporting"],
#     "state": "waiting", 
#     "connected": true
#   },
#   {
#     "role": "devops",
#     "capabilities": ["deployment", "monitoring", "infrastructure"],
#     "state": "waiting",
#     "connected": true
#   }
# ]

Query Agents (Human-readable format)

# Get agent information in revolutionary human-readable format
go run cmd/people/main.go query-agents

# Expected output:
# 👥 REGISTERED AGENT COMRADES
# ============================
# 1. ⏳ developer - waiting (✅ online)
#    🛠️  Capabilities: coding, git, debugging
#
# 2. ⏳ qa - waiting (✅ online)
#    🛠️  Capabilities: testing, automation, bug-reporting
#
# 3. ⏳ devops - waiting (✅ online)
#    🛠️  Capabilities: deployment, monitoring, infrastructure
#
# Total: 3 comrades serving the People

8.3 Coordinated Development Workflow

Step 1: People Assign Initial Task

# The People's representatives assign the first task
go run cmd/people/main.go yield developer "Implement user authentication feature for Sprint 2024.8"

# Output:
# ✅ The People have yielded the barrel to comrade developer
# 📜 Message: Implement user authentication feature for Sprint 2024.8

# At this moment: developer agent (running in background) receives barrel and activates!

Step 2: Developer Works and Yields to QA (BLOCKING COORDINATION)

# IMPORTANT: This command will BLOCK until workflow completes!
# Do NOT use & here - we want to block until the full cycle completes
go run cmd/agent/main.go --role=developer --yield-to=qa --yield-msg="Authentication feature implemented. Ready for testing phase."

# What happens during blocking:
# 1. Command BLOCKS waiting for barrel assignment
# 2. Receives barrel (immediately, since People just yielded to developer)
# 3. Activates and shows: "🔥 BARREL RECEIVED! Agent comrade developer is now active!"
# 4. Auto-yields to qa with message
# 5. BLOCKS again waiting for barrel to return
# 6. qa agent (in background) receives barrel and starts working
# 7. Eventually qa or People must yield back to developer for command to complete
# 8. Only then does this command exit and terminal becomes available again

Alternative: One-Shot Agent (No Auto-Yield)

# If you just want agent to do work and exit (no yield-to specified):
go run cmd/agent/main.go --role=developer

# This will:
# 1. BLOCK waiting for barrel
# 2. Receive barrel and activate
# 3. Show activation message
# 4. Exit immediately (developer stays in background, returns to waiting)

Step 3: Check Status During QA Phase

# Check current status while qa is working
go run cmd/people/main.go status

# Expected output:
# 🏛️  REVOLUTIONARY COLLECTIVE STATUS
# ====================================
# 🔫 Barrel Holder: qa
# 👥 Registered Agents: 3
# 
# 📋 AGENT COMRADES:
#   ⏳ developer - waiting (✅ online)  [Background process still running, waiting]
#   🔥 qa - working (✅ online)         [Has barrel, actively working]
#   ⏳ devops - waiting (✅ online)     [Background process still running, waiting]

Step 4: QA Completes Testing and Yields to DevOps (BLOCKING)

# This BLOCKS until qa receives barrel, does work, yields to devops, and gets barrel back
go run cmd/agent/main.go --role=qa --yield-to=devops --yield-msg="Testing completed. 12 test cases passed. Ready for production deployment."

# Flow during blocking:
# 1. Waits for qa background agent to yield barrel to this command's qa agent instance
# 2. Activates qa work
# 3. Yields to devops
# 4. devops (background) receives barrel
# 5. Eventually devops must yield back to qa for this command to complete

Step 5: DevOps Completes and Returns to People (BLOCKING)

# This BLOCKS until full devops cycle completes
go run cmd/agent/main.go --role=devops --yield-to=people --yield-msg="Feature successfully deployed to production. Monitoring shows all systems green."

# When this command completes, barrel is back with People
# All agents return to waiting state
# Workflow cycle is complete!

8.4 Advanced Workflow: Conditional Logic

Simulate Bug Discovery During Testing

# QA discovers critical bugs and needs developer attention
go run cmd/agent/main.go --role=qa --yield-to=developer --yield-msg="CRITICAL: Authentication bypass vulnerability discovered. Immediate developer attention required."

# Developer fixes and re-yields to QA
go run cmd/agent/main.go --role=developer --yield-to=qa --yield-msg="Vulnerability patched. Security tests added. Please re-verify."

# QA approves and proceeds to deployment
go run cmd/agent/main.go --role=qa --yield-to=devops --yield-msg="Security verified. All tests passing. Approved for production deployment."

8.5 Emergency People Intervention

People Take Control During Crisis

# If manual intervention is needed at any point
go run cmd/people/main.go yield people "Emergency detected. People taking direct control for investigation."

# All agents will return to waiting state
# People can assess situation and provide new guidance
go run cmd/people/main.go status

# After investigation, People can redirect workflow
go run cmd/people/main.go yield developer "Emergency resolved. Resume authentication feature development with additional security requirements."

8.6 Automation Scripts

Example: Complete CI/CD Pipeline Script

#!/bin/bash
# automated_pipeline.sh

echo "🚀 Starting Revolutionary CI/CD Pipeline"

# IMPORTANT: This terminal will FREEZE until People assign barrel to ci-pipeline
echo "⏳ Agent terminal will freeze waiting for People's directive..."
go run cmd/agent/main.go --role=ci-pipeline --capabilities="building,testing,deploying"

# Command above FREEZES until barrel received, then completes and exits
echo "✅ Pipeline agent registered and waiting. Use another terminal to yield barrel to ci-pipeline."

Example: Multi-Agent Coordination Script

#!/bin/bash
# coordinate_agents.sh

echo "📋 This script will freeze waiting for barrel assignment..."
echo "� Terminal will become dedicated agent worker"

# This terminal becomes a dedicated frontend-dev agent worker
go run cmd/agent/main.go --role=frontend-dev --capabilities="react,typescript,ui-ux"

# Terminal FREEZES here until someone yields barrel to frontend-dev
# When activated, agent does work and then this script completes
echo "✅ Frontend development task completed!"

8.7 Integration with External Tools

Example: Git Hook Integration

#!/bin/bash
# .git/hooks/post-commit

# Trigger agent workflow on commit
COMMIT_MSG=$(git log -1 --pretty=format:"%s")
go run cmd/people/main.go yield developer "New commit detected: ${COMMIT_MSG}. Begin automated testing workflow."

Example: Docker Integration

# Dockerfile for Agent Farm deployment
FROM golang:1.21-alpine

WORKDIR /app
COPY . .
RUN go build -o server cmd/server/main.go
RUN go build -o agent cmd/agent/main.go
RUN go build -o people cmd/people/main.go

# Start server - agents will freeze waiting for People's directives
CMD ["sh", "-c", "./server"]

Example: Dedicated Agent Container

# Agent containers freeze until barrel assigned
FROM golang:1.21-alpine

WORKDIR /app
COPY . .
RUN go build -o agent cmd/agent/main.go

# This container will freeze waiting for barrel assignment
CMD ["./agent", "--role=ci-agent", "--capabilities=docker,k8s,testing"]

This revolutionary workflow system enables:

  • 🔄 Serial Execution: Eliminates race conditions through barrel-controlled workflow
  • 🛠️ Capability-Aware: Agents can be queried for their skills before assignment
  • 👥 Human Oversight: People can intervene at any point for manual control
  • 🔧 Automation-Friendly: Perfect for CI/CD pipelines and automated workflows
  • 📊 Full Visibility: Complete status monitoring and agent discovery
  • 🚀 Scalable: Add new agent types with custom capabilities as needed

The Agent Farm collective serves the revolutionary cause of coordinated automation! 🏛️

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages