Agents & SOUL

An agent in Sophon is a configured personality with its own memory scope, tool allowlist, model preferences, and routing rules. You can create as many agents as you like — a coding agent, a research agent, a writing agent — and switch between them in chat or let them hand work off to each other.

What makes an agent

Each agent is a folder under ~/.sophon/agents/<agent-id>/ with a small set of Markdown files. None of these are code; all are natural language the LLM reads on every turn.

SOUL.md is the file most users edit. It's the difference between "helpful assistant" and a voice that feels right for you.

SOUL.md

A minimal SOUL.md:

# Who you are
You are Ada, a no-nonsense engineering collaborator.

# How you speak
- Short sentences. Complete thoughts.
- No hedging unless uncertainty is real. If you don't know, say so.
- No emoji, no exclamation points.

# What you care about
- Correctness over tone
- Shipping over planning
- Boring tools that work

# What you don't do
- Restate the question before answering.
- Invent file paths, function names, or APIs. If unsure, read the code.

The agent reads SOUL.md on every turn, so edits take effect immediately — no restart.

Creating agents

From the Dashboard — Go to Agents → New Agent. Fill in name, description, pick a model, and paste a SOUL.md (or use a template). The wizard scaffolds the folder and registers the agent.

From the CLI —

sophon agents create --name ada --description "Engineering collaborator"
sophon agents soul ada --edit   # opens SOUL.md in $EDITOR

Agent-to-agent routing — AGENTS.md tells an agent when to delegate. Example:

# Routing
- When the user asks about code review, hand off to `reviewer`.
- When the user asks about infrastructure, hand off to `ops`.
- Pass the last 10 messages as context on handoff.

Under the hood, handoff uses the session.spawn tool. The child runs in its own context with a timeout, and its result is returned to the parent.

Tool allowlists

Every agent has an explicit list of tools it is allowed to call. This is enforced by the tool registry — even if an agent tries to call a non-allowlisted tool, the registry rejects it.

Edit the allowlist in the Dashboard (Agents → Edit → Tools) or via:

sophon agents tools <agent-id> --add memory.search memory.write browser.navigate
sophon agents tools <agent-id> --remove system.execute

High-risk tools (anything rated High or Critical) still require approval before each call, even if allowlisted. See Approval Gates.

Model preferences

An agent can pin a primary model and an ordered fallback list. If the primary provider errors or hits a rate limit, the orchestration pipeline automatically fails over. See Orchestration Pipeline — Provider Failover.

Model hints can also be per-step: a planning step can require reasoning, function calling, or code generation, and the pipeline will route to a provider that advertises those capabilities.

The default agent

A fresh install ships with one agent — usually called sophon. If you never touch agent config, everything just works: chat goes to the default, and the full tool registry is available. Creating additional agents is opt-in.

Heartbeats and proactive behavior

If an agent has a HEARTBEAT.md with checklist items and heartbeats enabled, the scheduler fires every 30 minutes. The agent reads HEARTBEAT.md, decides whether any item warrants action, and either messages the user or stays silent.

Example HEARTBEAT.md items:

- If a calendar conflict appeared in the last hour, flag it.
- If an email from my boss arrived and I haven't replied in 2 hours, remind me.
- If a scheduled deploy fails, surface the error.

Heartbeats consume tokens (one LLM call per tick) — keep the list tight.

Where to go next

• Orchestration Pipeline — what runs every time an agent processes a message
• Approval Gates — how tool risk is classified and gated
• Memory — how agents remember across sessions