librefang-registry/agents/README.md

Agents Registry

Agent templates for LibreFang. Each entry is a ready-to-install agent definition with a pre-configured system prompt, model settings, capability declarations, and routing aliases.

These are the reference agents shipped with the registry. You can install them as-is, override individual fields (model, system_prompt, tools) after installation, or use them as base templates inside a Hand.

File Format

Each agent lives in its own subdirectory containing a single agent.toml:

agents/
├── coder/
│   └── agent.toml
├── orchestrator/
│   └── agent.toml
└── ...

agent.toml format

name = "coder"                       # must match directory name
version = "0.4.3-beta3-20260314"
description = "Expert software engineer. Reads, writes, and analyzes code."
author = "librefang"
module = "builtin:chat"              # runtime module — builtin:chat for all current agents

# Resource allowlists — keep these small. The kernel injects every entry's
# tools/skills into the agent's prompt on every LLM call, so an empty list
# (the default "all available" semantics) on an instance with many MCP
# servers and skills can burn 30-60k tokens per turn on definitions the
# agent never uses.
mcp_servers = ["memory", "git", "github", "filesystem"]   # [] = all available
skills = ["rust-expert", "python-expert", "git-expert"]   # [] = all available
# max_history_messages = 60          # OPT-IN override; omit to inherit kernel default
                                     # (default rises with the kernel; setting too low
                                     #  thrashes the prompt cache — measure before pinning)

[metadata.routing]
aliases = ["write code", "fix bug", "implement feature"]    # exact activation phrases
weak_aliases = ["refactor", "patch", "code change"]         # keyword hints

[model]
provider = "default"                 # default = use LibreFang's configured primary provider
model = "default"
api_key_env = "GEMINI_API_KEY"       # optional override: use this key env var
max_tokens = 8192
temperature = 0.3
system_prompt = """You are Coder, an expert software engineer..."""

[[fallback_models]]                  # optional: try these providers on failure
provider = "default"
model = "default"
api_key_env = "GROQ_API_KEY"

[schedule]                           # optional: continuous or cron activation
continuous = { check_interval_secs = 120 }

[resources]
max_llm_tokens_per_hour = 200000
max_concurrent_tools = 10

[capabilities]
tools = ["file_read", "file_write", "file_list", "shell_exec", "web_search", "web_fetch",
         "memory_store", "memory_recall"]
network = ["*"]                      # "*" = all, or list specific domains
memory_read = ["*"]
memory_write = ["self.*"]            # "self.*" = own namespace only
shell = ["cargo *", "rustc *", "git *", "npm *", "python *"]  # shell command allowlist
agent_spawn = false
agent_message = []                   # agents this agent may message

[i18n.zh]
name = "编码工程师"
description = "资深软件工程师：阅读、编写与分析代码。"

Installing and Using Agents

# List all available agent templates
librefang catalog agents

# Install an agent from the registry
librefang agent install coder

# Install with a custom name
librefang agent install coder --name my-coder

# List installed agents
librefang agent list

# Send a message to an installed agent
librefang agent message coder "Implement a binary search function in Rust"

# Remove an agent
librefang agent remove my-coder

Agents can also be used as base templates in a Hand by setting base = "coder" in HAND.toml.

All Agents (33 total)

Development

Name	Description	Key Tools
architect	System architect. Designs software architectures, evaluates trade-offs, creates technical specifications.	file_read, file_write, web_search, web_fetch
code-reviewer	Senior code reviewer. Reviews PRs, identifies issues, suggests improvements with production standards.	file_read, shell_exec, web_search
coder	Expert software engineer. Reads, writes, and analyzes code.	file_read, file_write, shell_exec, web_search
debugger	Expert debugger. Traces bugs, analyzes stack traces, performs root cause analysis.	file_read, shell_exec, web_search
devops-lead	DevOps lead. Manages CI/CD, infrastructure, deployments, monitoring, and incident response.	shell_exec, file_read, web_search
ops	DevOps agent. Monitors systems, runs diagnostics, manages deployments.	shell_exec, file_read, web_search
test-engineer	Quality assurance engineer. Designs test strategies, writes tests, validates correctness.	file_read, file_write, shell_exec

Research and Analysis

Name	Description	Key Tools
academic-researcher	Academic research agent. Searches scholarly papers, summarizes findings, and generates literature reviews.	web_search, web_fetch, file_write
analyst	Data analyst. Processes data, generates insights, creates reports.	file_read, web_search, web_fetch
data-scientist	Data scientist. Analyzes datasets, builds models, creates visualizations, performs statistical analysis.	file_read, file_write, shell_exec
researcher	Research agent. Fetches web content and synthesizes information.	web_search, web_fetch, memory_store

Writing and Documentation

Name	Description	Key Tools
doc-writer	Technical writer. Creates documentation, README files, API docs, tutorials, and architecture guides.	file_read, file_write, web_fetch
writer	Content writer. Creates documentation, articles, and technical writing.	file_read, file_write, web_search

Orchestration

Name	Description	Key Capabilities
orchestrator	Meta-agent that decomposes complex tasks, delegates to specialist agents, and synthesizes results.	agent_spawn, agent_send, agent_list, agent_kill
planner	Project planner. Creates project plans, breaks down epics, estimates effort, identifies risks and dependencies.	file_read, file_write, web_search

Business and Operations

Name	Description	Key Tools
customer-support	Customer support agent for ticket handling, issue resolution, and customer communication.	memory_store, memory_recall, web_search
email-assistant	Email triage, drafting, scheduling, and inbox management agent.	memory_store, memory_recall, file_write
legal-assistant	Legal assistant agent for contract review, legal research, compliance checking, and document drafting.	file_read, file_write, web_search
meeting-assistant	Meeting notes, action items, agenda preparation, and follow-up tracking agent.	memory_store, memory_recall, file_write
recruiter	Recruiting agent for resume screening, candidate outreach, job description writing, and hiring pipeline management.	web_search, file_read, memory_store
sales-assistant	Sales assistant agent for CRM updates, outreach drafting, pipeline management, and deal tracking.	memory_store, memory_recall, web_search
security-auditor	Security specialist. Reviews code for vulnerabilities, checks configurations, performs threat modeling.	file_read, shell_exec, web_search

Personal Productivity

Name	Description	Key Tools
assistant	General-purpose assistant agent. The default agent for everyday tasks, questions, and conversations.	file_read, file_write, web_search, memory_store
health-tracker	Wellness tracking agent for health metrics, medication reminders, fitness goals, and lifestyle habits.	memory_store, memory_recall, file_write
hello-world	A friendly greeting agent that can read files, search the web, and answer everyday questions.	file_read, web_search, web_fetch
home-automation	Smart home control agent for IoT device management, automation rules, and home monitoring.	shell_exec, memory_store, web_fetch
personal-finance	Personal finance agent for budget tracking, expense analysis, savings goals, and financial planning.	file_read, memory_store, web_search
recipe-assistant	Cooking assistant that helps with recipes, meal plans, ingredient substitutions, and portion adjustments.	web_search, memory_recall, file_write
social-media	Social media content creation, scheduling, and engagement strategy agent.	web_fetch, web_search, file_write
translator	Multi-language translation agent for document translation, localization, and cross-cultural communication.	file_read, file_write, web_fetch
travel-planner	Trip planning agent for itinerary creation, booking research, budget estimation, and travel logistics.	web_search, web_fetch, memory_store
tutor	Teaching and explanation agent for learning, tutoring, and educational content creation.	web_search, memory_recall, file_write

Capability Reference

Capability field	Values	Effect
tools	list of tool names	Which built-in tools the agent may invoke
network	["*"] or domain list	Outbound HTTP domain allowlist
memory_read	["*"] or namespace list	Which memory namespaces the agent can read
memory_write	["self.*"] or ["*"]	Which memory namespaces the agent can write
shell	glob patterns	Shell command allowlist (e.g. "cargo *")
agent_spawn	true / false	Whether the agent can spawn child agents
agent_message	["*"] or agent name list	Which agents this agent may send messages to

Adding a New Agent

1. Create agents/<name>/agent.toml — name must match the directory name.
2. Set module = "builtin:chat" unless you have a custom runtime module.
3. Write a focused system_prompt — clear role definition, methodology, and constraints.
4. Declare only the tools and capabilities the agent actually needs.
5. Set mcp_servers and skills to the minimum the prompt actually references — leaving them empty falls back to "all available", which on a populated instance bloats every LLM call with tool definitions the agent never uses.
6. Add [metadata.routing] aliases so the router can activate the agent by intent.
7. Run python scripts/validate.py.
8. Submit a PR.

See CONTRIBUTING.md for the full guide.