Agent Configuration

Every agent has a set of configurable properties that control its behavior, capabilities, and constraints.

Core properties

Property	Type	Description
`name`	string	Display name shown in the UI
`description`	string	What the agent does (used by other agents for delegation)
`model_group`	string	Which LLM configuration to use
`enabled`	bool	Whether the agent is active
`tools`	string[]	List of tool names the agent can access
`avatar`	string	Optional avatar URL

Identity

The identity field is a key-value map that shapes the agent’s personality. Common keys:

name: the agent’s display name in conversations
emoji: an icon or emoji for the agent
traits: personality characteristics

Identity values are injected into the agent’s system prompt. You can update them at runtime using the update_identity tool.

Sandbox settings

For agents that use the CLI tool, sandbox settings control execution constraints:

{
  "sandbox_config": {
    "network_access": true,
    "allowed_network_destinations": ["api.example.com"],
    "timeout_secs": 30
  }
}

Setting	Default	Description
`network_access`	`true`	Allow network connections from sandboxed commands
`allowed_network_destinations`	`[]`	Specific hosts allowed when network is restricted
`timeout_secs`	`30`	Maximum execution time for a single command

Concurrency

The max_concurrent_tasks field limits how many tasks the agent can run at the same time. If not set, it falls back to the server-wide default (configurable via FRONA_SERVER_MAX_CONCURRENT_TASKS, default: 10).

Heartbeats

Agents can be configured with periodic heartbeats. When enabled, the agent wakes up at regular intervals to perform maintenance tasks.

Setting	Description
`heartbeat_interval`	Seconds between heartbeats
`heartbeat_chat_id`	Chat session used for heartbeat messages

Model groups

The model_group value maps to a configuration block that defines:

main: the primary model (e.g., claude-sonnet-4-6)
fallbacks: backup models to try if the primary fails
max_tokens: token limit for responses
temperature: creativity/randomness setting
context_window: maximum context size
retry: backoff settings for transient failures

This indirection lets you change which model an agent uses without modifying the agent itself.

Creating agents via the API

POST /api/agents

{
  "name": "My Agent",
  "description": "Handles customer support inquiries",
  "model_group": "primary",
  "tools": ["web_search", "web_fetch", "remember"],
  "enabled": true
}

Updating agents

PUT /api/agents/{id}

Send the fields you want to change. Only the agent’s owner can update it.

Prompts

Agent behavior is primarily defined by system prompts, which are loaded from .md files:

AGENT.md: the core system prompt that defines the agent’s role and behavior
Tool-specific prompts: additional context for specific tools
Memory prompts: instructions for how the agent should handle memory

Built-in agents have prompts in the engine/config/agents/{agent_id}/ directory. Custom agents use a combination of default prompts and any overrides stored in the database.