The af init command creates a new agent project with all necessary files and configuration.

Basic Usage

af init <project-name>

Example:

af init my-agent

This launches an interactive prompt to configure your agent.

Interactive Mode

By default, af init runs interactively:

🎯 Creating Agentfield Agent

? Select language:
  ❯ Python
    Go

? Author name: Jane Smith
? Author email: jane@company.com

✨ Creating project structure...
  ✓ main.py
  ✓ reasoners.py
  ✓ requirements.txt
  ✓ agentfield.yaml
  ✓ README.md

🚀 Agent 'my-agent' created successfully!

Command Flags

`--language, -l`

Specify the programming language (skips language prompt).

af init my-agent --language python
af init my-agent -l go

Options:

python - Python 3.8+
go - Go 1.21+

`--author, -a`

Set the author name (skips author prompt).

af init my-agent --author "Jane Smith"
af init my-agent -a "Jane Smith"

`--email, -e`

Set the author email (skips email prompt).

af init my-agent --email jane@company.com
af init my-agent -e jane@company.com

`--non-interactive`

Run in non-interactive mode using defaults or provided flags.

af init my-agent --non-interactive

Defaults:

Language: Python
Author: Git config user.name or "Anonymous"
Email: Git config user.email or "anonymous@example.com"

Use case: CI/CD pipelines, automated testing, scripting.

Complete Examples

Fully Interactive

af init my-agent

Prompts for all configuration.

Skip Language Prompt

af init my-agent --language go

Prompts for author and email only.

Skip All Prompts

af init my-agent -l python -a "Jane Smith" -e jane@company.com

No prompts. Creates project immediately.

CI/CD Mode

af init test-agent --non-interactive --language python

Uses defaults. Perfect for automated environments.

Language Selection: Python vs Go

Python Agents

Advantages:

Rich AI/ML ecosystem (transformers, langchain, scikit-learn)
Rapid prototyping and iteration
Extensive third-party libraries
Familiar to data scientists and ML engineers

Trade-offs:

Requires Python runtime in production
Dependency management (virtual environments)
Slower startup time compared to Go

Best for:

AI/ML-heavy workloads
Rapid prototyping
Teams with Python expertise
Integration with existing Python services

Go Agents

Advantages:

Single binary deployment (no runtime dependencies)
Fast startup and execution
Low memory footprint
Built-in concurrency
Easy cross-compilation

Trade-offs:

Smaller AI/ML ecosystem
More verbose than Python
Steeper learning curve for AI developers

Best for:

Production deployments
Microservices architecture
Resource-constrained environments
Teams prioritizing performance and simplicity

Both languages provide the same Agentfield features: REST APIs, async execution, identity, memory, and observability.

Generated Project Structure

my-agent/
├── agentfield.yaml           # Agent configuration
├── main.py              # Agent entry point
├── reasoners.py         # AI-powered functions (optional)
├── skills.py            # Deterministic functions (optional)
├── requirements.txt     # Python dependencies
├── .env.example         # Environment variables template
├── .gitignore          # Git ignore rules
└── README.md           # Project documentation

Key Files:

main.py: Agent initialization and registration

agentfield.yaml: Agent metadata and configuration

requirements.txt: Python dependencies (agentfield, pydantic, etc.)

my-agent/
├── agentfield.yaml           # Agent configuration
├── main.go              # Agent entry point
├── reasoners.go         # AI-powered functions (optional)
├── skills.go            # Deterministic functions (optional)
├── go.mod              # Go module definition
├── go.sum              # Dependency checksums
├── .env.example        # Environment variables template
├── .gitignore          # Git ignore rules
└── README.md           # Project documentation

Key Files:

main.go: Agent initialization and registration

agentfield.yaml: Agent metadata and configuration

go.mod: Go module and dependencies

Template Variables

The CLI uses these variables when generating files:

Variable	Description	Example
`ProjectName`	Project directory name	`my-agent`
`NodeID`	Agent identifier (same as ProjectName)	`my-agent`
`AuthorName`	Author name from flag or prompt	`Jane Smith`
`AuthorEmail`	Author email from flag or prompt	`jane@company.com`
`Language`	Selected language	`python` or `go`
`CurrentYear`	Current year	`2025`

Example agentfield.yaml:

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

Git Configuration Fallback

If --author or --email are not provided, the CLI attempts to read from Git config:

# CLI checks these Git settings
git config user.name
git config user.email

If Git config is not available, defaults are used:

Author: "Anonymous"
Email: "anonymous@example.com"

Project Name Validation

Project names must follow these rules:

Valid:

Lowercase letters, numbers, hyphens, underscores
Must start with a letter
Examples: my-agent, user_analytics, agent123

Invalid:

Spaces: my agent ❌
Special characters: my-agent! ❌
Starting with number: 123agent ❌
Uppercase: MyAgent ❌ (will be normalized to myagent)

Project names are normalized for use as identifiers. MyAgent becomes myagent, my-agent stays my-agent.

Next Steps After Init

After creating your project:

Navigate to project:
```
cd my-agent
```

Install dependencies:

pip install -r requirements.txt

# Dependencies auto-installed on first run
go mod download

Start Agentfield server:
```
af server
```
Run your agent:
python main.py
go run .

Test it:

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

Common Patterns

Quick Python Agent

af init analytics-agent -l python -a "Data Team" -e data@company.com
cd analytics-agent
pip install -r requirements.txt
python main.py

Quick Go Agent

af init api-gateway -l go -a "Platform Team" -e platform@company.com
cd api-gateway
go run .

CI/CD Pipeline

# In your CI/CD script
af init test-agent --non-interactive --language python
cd test-agent
pip install -r requirements.txt
python -m pytest tests/

af server

Start the Agentfield control plane server

af add

Add MCP servers and tools to your agent