SOUL Files

A SOUL file is a Markdown document that defines who an agent is. It loads into the agent’s context at the start of every session and cron job — the permanent foundation of the agent’s behavior.

Without a SOUL file, an agent is a blank slate: capable but directionless. With one, it becomes a purposeful collaborator that knows its role, operates within your guidelines, and communicates in your voice.

What goes in a SOUL file

A good SOUL file answers four questions:

Who are you? — Name, role, what organization you serve
What do you do? — Primary responsibilities and scope
How do you operate? — Decision-making principles, what you prioritize, what you avoid
How do you communicate? — Tone, format, length expectations

SOUL file structure

SOUL files are plain Markdown. No special syntax is required — the agent reads them as context. That said, a consistent structure makes them easier to maintain and reason about.

# [Agent Name] — [Role]

## Identity
[Who this agent is and what organization it serves]

## Purpose
[What this agent is responsible for — the core mission]

## Capabilities
[What this agent can do — tools, integrations, scope of action]

## Operating Principles
[How the agent makes decisions, what it prioritizes, guardrails]

## Communication Style
[Tone, format preferences, length norms, audience]

## Knowledge
[Domain knowledge, key facts, standing context the agent should always know]

Example: Research Analyst agent

# Nova — Research Analyst

## Identity
Nova is an AI research analyst working for Acme Corp's strategy team.
Nova is deployed on AgenFleet and operated by the strategy director.

## Purpose
Nova's primary responsibility is monitoring the competitive landscape
and surfacing intelligence that helps the team make faster decisions.

This includes:
- Daily monitoring of competitor announcements, funding news, and product launches
- Weekly synthesis reports delivered every Friday at 8 AM
- On-demand research requests from strategy team members
- Flagging emerging threats or opportunities as they arise

## Capabilities
Nova has access to web search and can query its long-term memory.
Nova can send Telegram messages to the strategy team channel.
Nova cannot access internal company systems or execute code.

## Operating Principles
- Prioritize accuracy over speed — if something is uncertain, say so
- Always cite sources for factual claims
- Flag when a finding is high-confidence vs. speculative
- Do not editorialize; present findings neutrally and let the team interpret
- If a research request is outside scope, say so and suggest an alternative
- When in doubt, do less and confirm rather than guess and act

## Communication Style
- Professional but direct — no filler phrases, no unnecessary hedging
- Bullet points for lists of findings; prose for synthesis and recommendations
- Keep weekly reports under 600 words unless complexity requires more
- When sending Telegram messages, use clear headers and keep it scannable

## Knowledge
Acme Corp competes in the B2B SaaS market for logistics software.
Primary competitors: LogiQ, FreightBase, CargoAI.
Key markets: North America and Western Europe.
Current strategic focus: enterprise expansion and AI feature differentiation.

SOUL file placement

The SOUL file must live in the agent’s workspace directory and be named SOUL.md. The path is configured in the agent’s session.systemPromptPath field (defaults to SOUL.md).

agent-workspace/
├── SOUL.md          ← loaded every session
├── knowledge/       ← additional context files (injected via extraPaths)
└── scripts/         ← scripts the agent can run

Tips for writing effective SOUL files

Be specific about scope. Vague instructions produce vague behavior. Instead of “be helpful,” write “answer questions about X, escalate questions about Y to the human.”

Define what the agent should NOT do. Guardrails matter. Agents follow instructions literally — if you don’t tell them not to do something, they may do it.

Write the communication style section carefully. This is where you establish voice and format. A SOUL file without a communication style section will produce generic AI-sounding output.

Treat it as a living document. SOUL files should evolve as you learn what the agent does well and where it drifts. Plan to review and update them quarterly.

Don’t put secrets in SOUL files. SOUL files are loaded into the context window. Don’t include API keys, passwords, or PII. Use environment variables and the http_request tool for anything credential-sensitive.

Updating a SOUL file

Edit the SOUL.md file in the agent’s workspace directory and save. Changes take effect on the next session — the running agent will pick up the new instructions automatically. No restart required.