The Agentfield CLI is your primary tool for creating, developing, and deploying agents. It enforces best practices and provides a consistent development experience.

Philosophy

The CLI embodies Agentfield's core principles:

Convention over configuration: Sensible defaults, minimal boilerplate
Production-ready from day one: Generated code follows production patterns
Language-agnostic: Same workflow for Python and Go
Developer experience: Fast, intuitive, helpful error messages

Core Commands

`af init`

Create a new agent project with interactive prompts.

af init my-agent

What it does:

Scaffolds project structure
Generates configuration files
Sets up language-specific dependencies
Creates example reasoners and skills

Full Reference →

`af server`

Start the Agentfield control plane server for local development.

af server

What it provides:

API gateway for all agents
Service discovery and routing
Identity management (DIDs)
Shared memory fabric
Workflow orchestration
Real-time observability

Default port: 8080

Full Reference →

`af add`

Add MCP servers and external tools to your agent.

af add --mcp --url https://github.com/modelcontextprotocol/server-github

What it does:

Downloads and configures MCP servers
Registers tools with your agent
Updates agent configuration
Handles authentication and secrets

Full Reference →

Development Workflow

Standard Development Flow

# 1. Create agent
af init my-agent
cd my-agent

# 2. Install dependencies (Python only)
pip install -r requirements.txt

# 3. Start control plane (separate terminal)
af server

# 4. Run your agent
python main.py  # or: go run .

# 5. Test it
curl -X POST http://localhost:8080/api/v1/execute/my-agent.demo_echo \
  -H "Content-Type: application/json" \
  -d '{"input": {"message": "Hello!"}}'

Iterative Development

Agents support hot reload for rapid iteration:

Edit code in your agent files
Save - changes are detected automatically
Test - new code is live immediately

No need to restart your agent during development.

Multi-Agent Development

Run multiple agents simultaneously:

# Terminal 1: Control plane
af server

# Terminal 2: First agent
cd sentiment-agent
python main.py

# Terminal 3: Second agent
cd analytics-agent
python main.py

# Terminal 4: Third agent
cd orchestrator-agent
go run .

All agents register with the same control plane and can communicate via app.call().

Production Deployment

Python Agents

# Build Docker image
docker build -t my-agent:latest .

# Run in production
docker run -e AGENTFIELD_SERVER=https://agentfield.company.com my-agent:latest

Go Agents

# Build single binary
go build -o my-agent main.go

# Deploy anywhere
scp my-agent user@server:/opt/agents/
ssh user@server '/opt/agents/my-agent'

Go advantage: No runtime dependencies. Single binary deployment.

Configuration Files

agentfield.yaml

Agent configuration and metadata:

node_id: my-agent
version: 1.0.0
author:
  name: Jane Smith
  email: jane@company.com

description: My production agent
tags:
  - production
  - analytics

runtime:
  language: python
  port: auto

Environment Variables

Set via .env file or environment:

# Control plane URL
AGENTFIELD_SERVER=http://localhost:8080

# LLM API keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Agent configuration
NODE_ID=my-agent
DEV_MODE=true

CLI Flags and Options

Global Flags

Available for all commands:

--help, -h        Show help
--version, -v     Show version
--verbose         Enable verbose logging
--quiet           Suppress output

Command-Specific Flags

Each command has its own flags. Use --help to see them:

af init --help
af server --help
af add --help

Common Patterns

Quick Start (Python)

af init analytics-agent -l python
cd analytics-agent
pip install -r requirements.txt
python main.py

Quick Start (Go)

af init api-gateway -l go
cd api-gateway
go run .

CI/CD Pipeline

# Non-interactive mode for automation
af init test-agent --non-interactive --language python
cd test-agent
pip install -r requirements.txt
python -m pytest tests/

Multi-Agent System

# Create multiple agents
af init sentiment-agent -l python
af init analytics-agent -l python
af init orchestrator-agent -l go

# Start control plane
af server &

# Run all agents
cd sentiment-agent && python main.py &
cd analytics-agent && python main.py &
cd orchestrator-agent && go run . &

Troubleshooting

Command Not Found

# Add Agentfield to PATH
export PATH="$HOME/.agentfield/bin:$PATH"

# Make permanent (bash)
echo 'export PATH="$HOME/.agentfield/bin:$PATH"' >> ~/.bashrc

# Make permanent (zsh)
echo 'export PATH="$HOME/.agentfield/bin:$PATH"' >> ~/.zshrc

Port Already in Use

# Agentfield server uses port 8080 by default
# Change it with --port flag
af server --port 9000

Agent Won't Connect

# Check control plane is running
curl http://localhost:8080/health

# Verify AGENTFIELD_SERVER environment variable
echo $AGENTFIELD_SERVER

# Check agent is running
ps aux | grep "python main.py"

Hot Reload Not Working

# Ensure dev_mode is enabled in your agent
# Python: dev_mode=True
# Go: DevMode: true

# Restart your agent if needed
python main.py  # or: go run .

Best Practices

Project Organization

my-workspace/
├── agents/
│   ├── sentiment-agent/
│   ├── analytics-agent/
│   └── orchestrator-agent/
└── shared/
    ├── schemas/
    └── utils/

Version Control

Always commit:

agentfield.yaml - Agent configuration
Source code files
requirements.txt or go.mod
.env.example (not .env)

Never commit:

.env - Contains secrets
__pycache__/ - Python cache
*.pyc - Compiled Python
Binary executables

Environment Management

# Development
export AGENTFIELD_SERVER=http://localhost:8080
export DEV_MODE=true

# Staging
export AGENTFIELD_SERVER=https://agentfield-staging.company.com
export DEV_MODE=false

# Production
export AGENTFIELD_SERVER=https://agentfield.company.com
export DEV_MODE=false