Skip to main content

​
Creating Custom Agents

Beyond the 30 built-in templates, you can create fully custom agents with tailored capabilities, tools, and system prompts.

​
Creating an Agent Manifest

1

Create agent.toml

mkdir my-agent
cd my-agent
touch agent.toml
2

Define basic metadata

name = "my-assistant"
version = "0.1.0"
description = "My custom assistant agent"
author = "your-name"
module = "builtin:chat"
tags = ["custom", "assistant"]
3

Configure the LLM

[model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
temperature = 0.7
max_tokens = 4096
system_prompt = """
You are a helpful assistant that...
"""
4

Set resource limits

[resources]
max_llm_tokens_per_hour = 50000
max_cost_per_hour = 2.0
5

Grant capabilities

[capabilities]
tools = ["file_read", "web_fetch", "memory_store", "memory_recall"]
memory_read = ["self.*"]
memory_write = ["self.*"]
agent_spawn = false
6

Spawn your agent

openfang agent spawn agent.toml

​
System Prompts

The system prompt defines your agent’s personality, instructions, and behavior: 
[model]
system_prompt = """
You are a customer support agent for Acme Corp.

## Your Role
- Answer questions about our products
- Help troubleshoot issues
- Escalate complex problems to human support

## Guidelines
- Always be polite and professional
- Ask clarifying questions when needed
- Never make promises about refunds (escalate instead)

## Tools Available
- file_read: Read support documentation
- web_fetch: Check our knowledge base
- memory_store/recall: Remember customer context
"""

​
Capability System

Capabilities control what your agent can access:

​
Tool Access

[capabilities]
tools = [
  "file_read",      # Read files
  "file_write",     # Write files
  "file_list",      # List directory contents
  "web_fetch",      # Fetch web pages
  "web_search",     # Search the web
  "shell_exec",     # Execute shell commands
  "memory_store",   # Store memories
  "memory_recall"   # Recall memories
]
See the Capabilities reference for all available tools.

​
Memory Access

[capabilities]
memory_read = ["self.*", "shared.*"]  # What memory keys to read
memory_write = ["self.*"]              # What memory keys to write
Patterns:
  • "*" - all memory (use with caution)
  • "self.*" - only this agent’s memory
  • "shared.*" - shared memory namespace
  • "project.foo" - specific key

​
Agent Spawning

[capabilities]
agent_spawn = true              # Can spawn child agents
agent_message = ["researcher"]  # Can message these agents
agent_kill = []                 # Cannot kill agents

​
Testing Your Agent

1

Spawn in test mode

openfang agent spawn agent.toml
2

Chat interactively

openfang agent chat my-assistant
Test various scenarios:
  • Tool usage
  • Memory persistence
  • Error handling
3

Check logs

# View agent activity
tail -f ~/.openfang/logs/agents/my-assistant.log
4

Monitor costs

openfang agent list
# Check token usage and costs

​
Advanced Configuration

​
Per-Tool Configuration

[tools.web_fetch]
timeout = 10
max_redirects = 3

[tools.shell_exec]
allowed_commands = ["ls", "cat", "grep"]

​
Scheduling

[schedule]
mode = "periodic"
interval = "1h"  # Run every hour

# Or cron-style
mode = "cron"
cron = "0 */6 * * *"  # Every 6 hours

​
Model Routing

[routing]
enable = true
fallback_chain = ["claude-sonnet-4", "gpt-4o", "llama-3-70b"]

​
Best Practices

Grant only the tools your agent needs. You can always add more later.
Start with a simple prompt and refine based on actual agent behavior.
Always configure max_llm_tokens_per_hour and max_cost_per_hour to prevent runaway costs.
Restrict memory writes to self.* unless you need cross-agent communication.
Increment the version field when making significant changes.

​
Next Steps

Workflows

Chain multiple agents together

Security

Deep dive into the capability system

Build docs developers (and LLMs) love

Get started for freeTalk to us