agent-farm 0.2.0

DuckDB multi-org agent swarm with Spec Engine, 175+ SQL macros, meta-learning, MCP Apps, and smart extensions

Agent Farm

DuckDB Spec-OS for multi-org AI agent swarms. Central specification management, 280+ SQL macros, interactive agent REPL, MCP Apps, meta-learning, and smart extensions.

---

Quick Start

# Install
uv add agent-farm

# Interactive REPL (default: OrchestratorOrg)
agent-farm

# Start MCP server
agent-farm mcp

# System status
agent-farm status

From Source

git clone https://github.com/agentic-dev-io/agent-farm.git
cd agent-farm
uv sync
agent-farm status

Docker

docker compose up agent-farm     # MCP server + HTTP API on :8080
docker compose run test          # Run test suite

---

CLI

agent-farm                              # Interactive REPL (Orchestrator)
agent-farm --org dev                    # REPL with DevOrg
agent-farm --session my-session         # Resume persistent session

agent-farm mcp                          # Start MCP server (stdio)
agent-farm mcp --http-port 8080         # With HTTP API

agent-farm status                       # Specs + Extensions + Orgs overview

agent-farm spec list [--kind agent]     # List specs
agent-farm spec get --id 10             # Get spec as JSON
agent-farm spec search <query>          # Full-text search

agent-farm app list                     # List MCP Apps (11+)
agent-farm app render <id>              # Render a MiniJinja app template

agent-farm approval list                # List pending approvals
agent-farm approval resolve 1 approved  # Resolve approval request

agent-farm sql <file.sql>               # Execute SQL against initialized DB

Interactive REPL

The default mode — chat with AI agents, run slash-commands:

[OrchestratorOrg]> Analyze the project structure and suggest improvements
[OrchestratorOrg]> /org dev                    # Switch to DevOrg
[DevOrg]> /spec list --kind agent              # List agent specs
[DevOrg]> /sql SELECT count(*) FROM spec_objects
[DevOrg]> /status                              # Quick status summary
[DevOrg]> /exit                                # Quit (saves session if --session)

REPL responses stream incrementally when the backend supports it.

---

Architecture

src/agent_farm/
├── cli.py             # Typer CLI (mcp, status, spec, app, sql)
├── repl.py            # Interactive REPL with slash-commands
├── main.py            # DuckDB init, extension loading, SQL macros
├── spec_engine.py     # Spec Engine (central specification management)
├── orgs.py            # 5 organizations with models, tools, security
├── schemas.py         # Data models, enums, table definitions
├── udfs.py            # Python UDFs (agent_chat, agent_tools, etc.)
└── sql/               # 280+ SQL macros
    ├── base.sql       # Utilities (url_encode, timestamps)
    ├── ollama.sql     # LLM calls (Ollama, Anthropic, cloud wrappers)
    ├── tools.sql      # Web search, shell, Python, fetch, file, git
    ├── agent.sql      # Security policies, audit, injection detection
    ├── harness.sql    # Agent harness (model routing, tool execution)
    ├── orgs.sql       # Org permissions, orchestrator routing
    ├── org_tools.sql  # SearXNG, CI/CD, notes, render jobs
    ├── ui.sql         # MCP Apps (24 MiniJinja UI templates)
    └── extensions.sql # JSONata, DuckPGQ, Radio, Bitfilters (hybrid), Lindel (hybrid)

db/                    # Spec Engine schema, macros, seed data, intelligence
tests/                 # pytest test suite
docs/                  # Documentation

---

Multi-Org Swarm

5 specialized organizations with security policies, tool permissions, and denial rules:

Org	Model	Security	Role
OrchestratorOrg	kimi-k2.5:cloud	conservative	Task routing, coordination
DevOrg	glm-5:cloud	standard	Code, reviews, tests
OpsOrg	kimi-k2.5:cloud	power	CI/CD, deploy, render
ResearchOrg	gpt-oss:20b-cloud	conservative	SearXNG search, analysis
StudioOrg	kimi-k2.5:cloud	standard	Specs, docs, DCC briefings

Each org has dedicated workspaces, allowed/denied tool lists, approval requirements, and smart extension integrations.

Approval requests are persisted in DuckDB and can be reviewed via agent-farm approval list.

Radio messages are persisted in DuckDB, so queued events survive process restarts when using a file-backed database.

---

SQL Macros (280+)

-- LLM calls (routed through Ollama)
SELECT deepseek('Explain quantum computing');
SELECT kimi_think('Solve step by step: ...');
SELECT qwen3_coder('Write a Python function for...');

-- Spec Engine
SELECT * FROM spec_list_by_kind('agent');
SELECT * FROM spec_search('planner');
SELECT spec_render('Hello {{ name }}!', '{"name": "World"}');

-- Web search
SELECT brave_search('DuckDB tutorial');
SELECT searxng('quantum computing');

-- Agent harness
SELECT quick_agent('agent-1', 'Summarize the project');
SELECT secure_read('agent-1', '/projects/dev/main.py');

-- Shell & Python
SELECT shell('ls -la');
SELECT py('print(2+2)');

See docs/spec_engine.md for the full SQL macro reference.

---

MCP Client Configuration

{
  "mcpServers": {
    "agent-farm": {
      "command": "agent-farm",
      "args": ["mcp"],
      "env": {
        "DUCKDB_DATABASE": ".agent_memory.db"
      }
    }
  }
}

---

Environment Variables

Variable	Description	Default
DUCKDB_DATABASE	Database path	:memory:
SPEC_ENGINE_HTTP_PORT	HTTP server port	—
SPEC_ENGINE_API_KEY	HTTP API key	—
OLLAMA_BASE_URL	Ollama endpoint	http://localhost:11434
ANTHROPIC_API_KEY	Anthropic API key	—
ANTHROPIC_BASE_URL	Anthropic endpoint override	https://api.anthropic.com
SEARXNG_BASE_URL	SearXNG endpoint	http://searxng:8080
BRAVE_API_KEY	Brave Search key	—

---

Development

uv sync --extra dev

# Tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

# Coverage
uv run pytest tests/ --cov=src/agent_farm

---

Documentation

• Spec Engine Reference

---

License

MIT — see LICENSE for details.