Reference

agent.toml

An agent is one TOML file plus its prompt, templates and code. These are the sections the engine reads, and what each key means. Snippets on the home page show them in use.

`[agent]`

Who the agent is and what it may do.

name: The folder name under agents/ and the value of AGENT_NAME. An identifier.
display_name: How the agent introduces itself and signs receipts.
instruction_file: The system prompt, relative to the agent folder. Rendered with your organization's names.
model / fallback_model: The primary model and the one used on rate limits. The fallback must support function calling.
tools: Names of the tools this agent may call: the engine's, the shared toolkits', and its own. Unknown names fail at startup.
reference_files: Extra files whose text is appended to the prompt.

`[slack]`

The agent's own Slack app.

icon: The app icon, pushed to Slack on deploy.
bot_token_env: An environment override for the bot token; the token itself lives encrypted beside the definition.
placeholder_texts: What the agent says while it works. One is picked at random.

`[[data]]`

One entry per thing the agent keeps.

name: How the agent's code refers to it.
source: "git" (a CSV in a repository) or "spreadsheet" (a tab in a Google Sheet).
binding: The organization setting that names the repository or spreadsheet. Keeps the definition customer-neutral.
path / tab: The file inside the agent's folder of the repo, or the sheet tab. A path may be a template like activity/{task}.csv.
row_type: The registered row schema. Columns are bound by title; a missing column is added on first write.
writable: Whether the agent may write to it at all.
editors / editors_from: Who may write: named emails, the symbolic "boss", or owners resolved from another entity's rows.
key / unique: The field writes are keyed by (one row per id) and whether duplicates are refused.
root: Read another agent's folder in the same repository, read-only.

`[git]`

The data repository.

token_env: The environment variable holding the token, unless the organization supplies its own.
branch: Defaults to main.
root: The folder the agent's files live under. Defaults to the agent's name, so agents share one repository cleanly.

`[schedule] and [[reminders]]`

Cycle-relative reminders.

timezone / day_of_week / hour / minute: When the daily run happens, and which weekday carries the weekly reminder.
id: Unique per reminder; the key its sent state is recorded under.
day / week: Position in the cycle. Day 1 is the trigger date; negative days fire before it; week is validated against day.
trigger: "cycle_start" (default) or "cycle_end".
template: The message, with placeholders from the context type.
data: The registered context type whose fields the template may use. Validated at startup.
action: What a threaded reply does: "none", "post_update" (filed as a dated update), or "append_tab" (appended to action_tab).
tasks: Send-time tasks run once per item, such as creating a channel.
cc_boss: Send to a group DM of the owner and the admin instead of the owner alone.

`[daily]`

Work that runs every morning.

tasks: Names registered by the agent's tasks module. Each is idempotent and records what it sent.

`[limits]`

Cost and abuse guards.

daily_turns: Model turns per day before the agent politely refuses and alerts the admin once. Default 300.

`[bindings] and [bindings.defaults]`

What an organization supplies.

required: Binding keys the portal must collect before this agent can go live.
defaults: Values used when an organization has not set a binding. An empty default lets an optional capability switch itself off.

`[sessions], [reminder_state], [data_cache]`

Memory and caching.

backend: "firestore" in production, "memory" for tests and local runs.
firestore_collection / collection: The agent's own collections. Every one is namespaced per organization.
ttl_seconds: How long a fetched table is reused before it is read again. Writes invalidate it.

`Your own sections`

Anything the agent's code reads.

[calendar]: A subscribable feed of dated records, guarded by a token.
[engagement]: A weekly question schedule: channel, horizon, preview lead time, generation prompt.
[reporting_db]: A read-only warehouse connection with a statement guard, time limit and row cap.
[workflow], [messages], [mail], [gcal]: Process rules and the mailbox and calendar an agent sends from, when switched on.

Values in your sections can be bindings too (binding:key), so the section stays customer-neutral.

Where bindings come from

The definition names a binding; the organization supplies its value in the portal. Per-agent overrides are possible.

organization record

# In an organization's record (set from the portal), not in the agent:
[bindings]
data_store = "your-org/bot-data"
sites_sheet = "1AbC…"            # a pasted Sheets URL is normalized to its id
alerts_channel = "ops"

[agents.fieldops.bindings]
sites_sheet = "1XyZ…"            # a per-agent override