Build Go agents that compile to dual-mode binaries - run as control plane agents or standalone CLI tools

What is CLI Mode?

The Go SDK enables you to build agents that compile to single, production-ready binaries that operate in two modes:

Server Mode: Connect to AgentField control plane for verifiable, auditable, auto-discoverable execution
CLI Mode: Run standalone as fast, native CLI tools with zero external dependencies

The same binary supports both modes - no separate builds needed.

Why Use CLI Mode?

Production Benefits

Lightning:duotone

Fast Native Performance

Compiled Go binaries with sub-100ms startup time

Network:duotone

Control Plane Integration

Verifiable, auditable execution with cryptographic identity (DIDs/VCs)

MagnifyingGlass:duotone

Auto-Discovery

Agents discoverable by other agents when connected to control plane

Package:duotone

Zero Dependencies

Single binary distribution - no runtime, no containers required

Development Benefits

Local Testing: Test reasoners without running the control plane
Fast Iteration: Compile once, test CLI instantly
Easy Distribution: Ship single binaries to users or deployment environments
Dual-Purpose: Same code serves API requests and CLI commands

How It Works

Architecture

Mode Detection

The SDK automatically detects which mode to run based on configuration:

Mode	Trigger	Use Case
Server	`AgentFieldURL` is set	Production deployment with control plane
CLI	`AgentFieldURL` is empty or not set	Local testing, standalone tools, distribution
Dual	Both configurations present	Flexible deployment - same binary works in both modes

Quick Example

main.go

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/Agent-Field/agentfield/sdk/go/agent"
)

func main() {
    a, err := agent.New(agent.Config{
        NodeID: "hello",
        AgentFieldURL: os.Getenv("AGENTFIELD_URL"), // Optional for CLI mode
        CLIConfig: &agent.CLIConfig{
            AppName: "hello",
            AppDescription: "Greeting agent with CLI support",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    a.RegisterReasoner("greet", func(ctx context.Context, input map[string]any) (any, error) {
        name := input["name"].(string)
        return fmt.Sprintf("Hello, %s!", name), nil
    },
        agent.WithCLI(),        // Enable CLI access
        agent.WithDefaultCLI(), // Make this the default command
    )

    if err := a.Run(context.Background()); err != nil {
        log.Fatal(err)
    }
}

Build and Run

# Build the binary
go build -o hello

# CLI Mode (no control plane)
./hello --set name=World
# Output: Hello, World!

# Server Mode (with control plane)
AGENTFIELD_URL=http://localhost:8080 ./hello serve
# Output: [agent] listening on :8001

When to Use CLI Mode

Ideal Use Cases

CLI Tools: Build AI-powered CLI utilities that can optionally connect to control plane
Local Development: Test reasoners quickly without infrastructure
Production Deployment: Ship scalable binaries that can run standalone or in orchestrated mode
Distribution: Provide users with single-binary tools
Hybrid Systems: Same agent serves API requests and provides CLI interface