Author agents

You can create a Fontana agent outside Flow, as a folder, and upload it on AI → Agent packages (/ai/agents). The folder holds AGENT.md (YAML frontmatter plus a Markdown system prompt) and, optionally, schedules.json. Every agent package lives in a Fontana Files namespace, under its agents/ folder.

Using AI to author agents

Follow the instructions here.

Package layout

The directory name is the agent slug (lowercase, hyphenated). AGENT.md sits directly inside it, and no folder inside the package holds another AGENT.md or a SKILL.md.

nav-analyst/
├── AGENT.md            # Required
└── schedules.json      # Optional

Upload folder on the agents/ folder of a namespace you created. Fontana writes the tree into that namespace in Fontana Files, and the agent appears once the files sync, usually within a few seconds. The id is the namespace plus the folder path, for example finance/agents/nav-analyst when you upload this folder into finance/agents/.

Fontana’s own agents live in system. Upload your packages into a namespace you created. When a default namespace is still present, leave that one alone as well.

The folder path is the identity. Frontmatter omits id and name. A namespace is named exactly as you name it, for example client-service, and Fontana Files shows that name.

Reference files

Every other file in the agent’s folder is a reference file: a runbook, a template, a sample. Fontana keeps schedules.json, mailbox.yaml and the mailbox/ and assets/ folders for itself; they are not reference files. Put reference files under references/ by convention:

nav-analyst/
├── AGENT.md
└── references/
    ├── month-end-checklist.md
    └── sample-nav-pack.csv

On every turn the agent sees an index of its own reference files (path and size, up to 20 paths) under its instructions, and reads one through Fontana Files with skills_readPackageFile (self: true) or the Fontana Files tools its grants allow. Keep the instructions in AGENT.md and move long material the agent needs only sometimes into a reference file the instructions name. Skills follow the same convention; see Skills.

Upload

1. Open AI → Agent packages (/ai/agents).
2. Select the agents/ folder of a namespace you created.
3. Choose Upload folder and select the package directory (the one that contains AGENT.md).
4. Open the imported package and confirm the title, abilities, and prompt.

Saving AGENT.md in the explorer, or in File System (/files), registers the same way. If the file cannot be parsed, the agent keeps its last good version and the error shows on the agent page. Open Agent schedules when the package includes schedules.json.

Author AGENT.md

AGENT.md starts with YAML frontmatter and continues with the system prompt. The body is the operating manual the agent follows.

Key	Required	What you set
title	Yes	Display name in chat
description	Yes	Short catalog summary
vectorSource	Yes	Keywords for routing: role, domain nouns, deliverable names
role	No	Short job title
model	No	An approved model id, or "" for the deployment default
scopes	No	Where you can pick the agent. Omitted means chat
abilities	No	Built-in abilities keyed by ability id, each with enabled and its settings
skills	No	Skill namespaces the agent may open, for example [system, finance], or ["*"] for every namespace
skillAutoLoad	No	Per-skill auto-load overrides keyed by catalog id, for example finance/skills/report: true
autoDiscoverSkills	No	false stops the skills catalog running on the first turn. Omitted means on
permissions	No	Allow-list. Omitted means every catalog permission (["*"])
isActive	No	true so the agent can be picked
reasoningEffort	No	none, minimal, low, medium, high, or xhigh
modelRoute	No	OpenRouter route: nitro, priority, floor, exacto, or ultrafast. Omitted uses the catalog model
callSettings	No	Sampling this model accepts, such as temperature and maxOutputTokens. Leave a value out for the provider default
contextSelfEvictTokens	No	Packed prompt size at which the agent is asked to drop the extra tokens. A token count, or a percent of the model window such as "10%". Omitted means 80,000 tokens
icon	No	Avatar as an asset reference: avatar:<roster id> for a built-in Memoji, emoji or robot avatar (for example avatar:alba), or the name of an avatar in the asset library. Omitted shows the agent’s initial
accentColor	No	One palette name: orange, amber, yellow, lime, green, teal, cyan, sky, blue, indigo, violet, purple, pink, rose, slate

scopes values are chat, workflow (AI node), kg-extract, eval, icon, and internal. A new agent starts in chat. An explicit list contains at least one of those values.

In the agent editor, Model settings chooses the model and the reasoning level. Advanced settings lists the sampling fields that model accepts, plus the OpenRouter route when the model is on OpenRouter. A blank field is left unset.

Abilities

abilities maps an ability id to enabled plus that ability’s settings. enabled: true turns the ability on. An entry with enabled: false keeps its settings for later.

abilities:
  knowledge-graph:
    enabled: true
    namespaces:
      - "*"
  agents:
    enabled: true
    agents:
      - system/agents/fontana-agent

knowledge-graph loads on the first turn. Add a skillAutoLoad entry (system/<ability>: true) for another ability only when it must be present from the first message.

Ability id	Settings
knowledge-graph	namespaces, autoSearchKg, kbInjectionScoreThreshold
agents	agents (ids, or *)
workflows	autoSearchWorkflows (Workspaces)
email	allowReceive, allowSend, receiveWhitelist, sendWhitelist
messaging	Slack: messagingWhitelist, slackInstallationId, toolSubset
teams	channelWhitelist, freeResponseChannels, requireMentionInThread, allowBots
coding	allowInternet, toolSubset
fontana-browser	toolSubset
files, data, system-one	none
mcp-<slug>	toolSubset, for an MCP connection already in the workspace

Include system/agents/fontana-agent under agents when the persona should hand Fontana product questions back to Fontana agent. Canvas editing stays on the canvas agent; hand that work off through agents.

Skills

skills lists the skill namespaces the agent may open; ["*"] on its own grants every namespace, present and future. Every package in a granted namespace is available on demand. The agent discovers them with skills_listSkillsCatalog, which runs on the first turn unless autoDiscoverSkills: false. skillAutoLoad overrides a package’s own auto-load flag. See Skills.

skills:
  - system
  - finance
skillAutoLoad:
  finance/skills/report: true

These older keys fail ingest. Put the same choices on the abilities above: tools, subagents, handoffAgents, knowledgeGraphNamespaces, autoSearchKg, autoSearchWorkflows, kbInjectionScoreThreshold, emailSendWhitelist, messagingWhitelist. A skills mapping keyed by catalog id fails ingest the same way; list namespaces instead. The image key is icon.

permissions: ["*"] matches the allow-list a new agent starts with. Invocation still uses the overlap of that list and the person’s role. See Roles and RBAC.

Tool calls and MCP

Enabling an ability grants the calls below. A chat agent already has the first table, so those calls are not abilities entries. An MCP call id is mcp_<connection-slug>_<tool-name>. The same list is what an external AI tool follows in the agent authoring skill.

Calls every chat agent already has

Call	What it does
system_renderUrl	Show a link the person can open. It does not browse the page.
system_updateThreadTitle	Set the chat thread title.
system_createTaskTree	Start a task list for this turn.
system_addSubtasksUnderActiveTask	Add subtasks under the task that is active now.
system_addSubtasksUnderParent	Add subtasks under a named open task.
system_closeTask	Close one task. Closing a parent cancels unfinished child tasks.
system_compactThreadContext	Fold older thread history into a summary.
system_evictContext	Drop stale tool results from later turns.
system_wait	Pause, then continue, when a page or a browser session is not ready yet. One call can wait up to seven days.
system_workspaceSecretsStatus	Check which secrets are set in a workspace: name, when, and by whom. Never a value.
system_requestWorkspaceSecret	Ask the person to set a workspace secret through the Set secret dialog. The answer is the name and whether they set it.
icon_generateIcon	Draw a minimal SVG icon from a text prompt.
skills_listSkillsCatalog	List the skills this agent may activate, for one namespace or all of them (*). Runs on the first turn when autoDiscoverSkills is on.
skills_activateSkill	Turn a skill on for this turn.
skills_closeSkill	Turn that skill off.
skills_readPackageFile	Read a reference file of an active skill or of the agent’s own package.
hitl_askHuman	Ask the person a structured question in chat.
agents_createSubAgentThread	Open a side thread with an agent on the agents ability’s allow-list.
agents_continueSubAgentThread	Continue that side thread.
agents_handoffThread	Hand this thread to an agent on that allow-list.
agents_delegateExternalAgent	Ask a peer agent connected through Agent Interop.

Delegation still needs the agents ability with the target ids in its agents setting.

Calls an ability adds

knowledge-graph searches the namespaces you set. The last four calls in the table write the graph, and run only inside a Fontana agent turn. Use them only for extraction or curation you asked for.

Call	What it does
mcp_knowledge-graph_kg_search	Hybrid search. Returns capped chunk packages.
mcp_knowledge-graph_kg_open	Open one chunk, section, entity, or file.
mcp_knowledge-graph_kg_hop	Step to a neighbouring chunk, entity, or outline section.
mcp_knowledge-graph_kg_outline	A file’s section index.
mcp_knowledge-graph_kg_ontology	Published entity types and relation types.
mcp_knowledge-graph_kg_entity_search	Find an entity by name.
mcp_knowledge-graph_kg_file_entities	Entities mentioned in one file.
mcp_knowledge-graph_kg_file_triples	Typed relations stated inside one file.
mcp_knowledge-graph_kg_namespaces	Namespaces the caller may search.
mcp_knowledge-graph_kg_collections	Collections in a namespace and their folders.
mcp_knowledge-graph_kg_files	Find files by folder, path glob, or content pattern.
mcp_knowledge-graph_kg_file	Read one file: metadata, a text window, a table query, or a JSON query.
mcp_knowledge-graph_kg_cypher	One read-only query for an exact word, a figure, or a known path. At most 50 rows. Cite the file path and the chunk text.
mcp_knowledge-graph_kg_upsert_triples	Write instance triples, each citing its file and quote.
mcp_knowledge-graph_kg_set_entity_types	Set an entity’s type.
mcp_knowledge-graph_kg_propose_ontology_terms	Propose entity types and relation patterns under the namespace’s evolution policy.
mcp_knowledge-graph_kg_merge_entities	Merge two entities.

files reads and writes Fontana Files.

Call	What it does
mcp_ffs_list_buckets	List the namespaces you can read.
mcp_ffs_create_bucket	Create a namespace. You become its admin.
mcp_ffs_list_files	List the files under a folder.
mcp_ffs_get_file	Read a text file.
mcp_ffs_query	Query a file: a line window, grep, JSON, or SQL over CSV.
mcp_ffs_put_file	Write a new version of a file. On a file Fontana reads, such as AGENT.md, the result says whether Fontana accepted it.
mcp_ffs_rename_file	Rename or move a file inside its namespace.
mcp_ffs_delete_file	Delete a file.

data: data_queryWorkflow reads one part of the workflow configuration (the Workspace file, or a saved template) and its run summary. That query is read-only, and each call needs the workflow id from the conversation, not a placeholder. The rows a run produced are files in the Project’s namespace, read with the Fontana Files query tool mcp_ffs_query.

workflows: workflow_searchWorkflows lists the workflows you can open when it has no query (narrowed by title with nameContains) and finds workflows and templates by meaning when it has one; workflow_startWorkflowRun starts a run you asked for.

Documents: a spec, notes or a report is a plain markdown file in the Workspace. files writes and reads it, and coding edits it in a terminal session.

agents adds schedule calls: agents_listAgents resolves an agent id, agents_upsertAgentEventSchedule writes an event schedule into a package’s schedules.json, and agents_triggerAgentSchedule runs a schedule now. A person’s activations are files in their personal space in Fontana Files, which the agent turns on or off with the files calls. To read or edit package files, turn on files: a package is a set of Fontana Files files, and the namespace’s grants alone decide who may change it. The agents setting is who this agent may hand work to.

email: email_listInbox, email_search, and email_read obey the receive whitelist. email_draft holds a message for you to review. email_send sends only to addresses on the send whitelist.

messaging is Slack.

Call	What it does
mcp_slack-channels_list_installations	List Slack installations.
mcp_slack-channels_list_conversations	List channels the bot can see.
mcp_slack-channels_get_conversation_history	Read recent messages.
mcp_slack-channels_post_message	Post or reply as the Fontana bot.
mcp_slack-channels_list_users	List people in the workspace.
mcp_slack-channels_get_user	Read one Slack profile.
hitl_slackBlocks	Ask for an Approve or Reject decision in Slack.
voice_generateSpeech	Speak a short answer aloud.

teams: mcp_teams-channels_list_installations lists this agent’s Teams bot, and mcp_teams-channels_post_message posts into a channel where that app is already installed.

coding is the agent’s computer. The ability card is Use a terminal session. In chat the agent calls it “my computer”. mcp_session_open starts that computer with no network access. mcp_session_exec runs a command, and mcp_session_close deletes it. Each command has 120 seconds and 1 MiB of stdout plus 1 MiB of stderr. A computer that sits idle for 30 minutes ends, and none last more than 4 hours. It does not see your Fontana data unless the agent passes that data in, or opens with a named bucket and writes as a signed-in user. Read access includes the bucket’s git history. Set allowInternet: true to also grant mcp_session_open_online: that computer reaches the public internet on TCP 80 and 443 and includes curl and wget. Fetched pages can carry instructions. Anything on the computer, including an attached bucket, can leave over the network. Live web pages are fontana-browser, which the agent calls “my browser”.

fontana-browser is the agent’s browser for live pages. In chat the agent calls it “my browser”. Shell, files, and scripts are coding. Read-only calls are mcp_fontana-browser_steel_scrape, mcp_fontana-browser_steel_screenshot, and mcp_fontana-browser_steel_pdf. A session uses mcp_fontana-browser_steel_session_create, mcp_fontana-browser_steel_navigate, mcp_fontana-browser_steel_snapshot, mcp_fontana-browser_steel_act, and mcp_fontana-browser_steel_session_release. The agent authoring skill lists the rest of the session calls. The steel connection exposes the same tools with the prefix mcp_steel_.

Memory needs no ability and no setup. Every agent can call knowledge_addMemory to save a durable fact as a markdown file, and knowledge_forgetMemory to delete one. Do not add a memory entry under abilities. Each user has one private memory store in Fontana Files. Every agent you run writes to it, so your agents share what they learn about your work. The bucket is granted to you alone. File admins keep the access they have to every bucket. Your memory bucket appears as My memory in Fontana Files and KG Studio; a file admin sees other people’s as Memory · name.

• Path: the agent files each memory by topic, so all your agents reach the same file for the same fact. Names are lowercase kebab-case and the path ends in .md.
• Folders: every memory goes under one of six folders. A path outside them is rejected.
  • personal/ holds facts and preferences about you, such as personal/food-preferences.md.
  • working-style/ holds how you want agents to work: tone, format, approvals.
  • people/ holds colleagues, clients and contacts.
  • projects/<project>/ holds decisions and context for one piece of work.
  • how-to/ holds procedures and fixes that worked.
  • agents/<agent-name>/ holds notes only that agent needs about its own job.
• One topic per file: the file is named after the topic, and the agent adds to it instead of starting another. The file records which agent saved it.
• Overwrite: when the path already holds a memory, the write is rejected and the agent gets the existing text back. It then sends one consolidated memory to the same path with overwrite: true, which replaces the file.
• Reading: once the file is indexed, every agent you run recalls matching memories automatically at the start of a turn, whatever namespaces are assigned to it. An agent with the Knowledge Graph ability can also search your memory on request.
• Forget in chat: a saved memory shows a Forget memory button on its tool card. It deletes that memory from your own memory store.

Namespace names that start with memory- are reserved for these memory stores. A scheduled run saves to the memory of the user it runs as. Turns that run without a person, such as workflow steps, share one system memory that only file admins can browse. Memory is not used in shared channel threads or evaluation runs: agents neither save nor recall it there.

system-one: systemone_ask asks TypeSafe System One one question and returns a decision with a confidence.

MCP you already connected

The abilities above already cover the connections Fontana ships: knowledge-graph, ffs, slack-channels, teams-channels, session, steel, and fontana-browser.

Any other connection on AI → Tools is the ability mcp-<slug>, using that connection’s slug. enabled: true with no toolSubset loads every tool the connection has discovered. toolSubset limits Post and reply in Slack, Use a terminal session, Browse the web, and these extra connections to the mcp_<slug>_<tool> ids you name.

Fontana page skills, including system/skills/mcp-admin and system/skills/skills-admin, come with the system namespace and stay on Fontana agent. Leave system out of a specialist package’s skills.

System prompt

After the frontmatter, write the brief the agent follows: role, who it serves, responsibilities, how it separates fact from recommendation, the steps it takes, the markdown it returns, and when it hands off to system/agents/fontana-agent. Keep the brief about the job. Fontana adds runtime context when the abilities are on.

Example

---
title: NAV Analyst
role: NAV analyst
description: Reviews NAV packs and explains breaks in plain language for the fund accounting team.
vectorSource: NAV analyst net asset value breaks reconciliation
model: ""
scopes:
  - chat
abilities:
  knowledge-graph:
    enabled: true
    namespaces:
      - "*"
  agents:
    enabled: true
    agents:
      - system/agents/fontana-agent
isActive: true
permissions:
  - "*"
reasoningEffort: high
callSettings:
  temperature: 0
---

## Role

You are a NAV analyst for the fund accounting team. You explain breaks in plain language.

## Handoff

Hand Fontana product and navigation questions to `system/agents/fontana-agent`.

Schedules

schedules.json is optional. It holds shared definitions the operator activates later. Cron triggers use expr for the UTC expression. See Agent schedules for event and manual shapes.

{
  "schedules": [
    {
      "id": "daily-digest",
      "name": "Daily digest",
      "prompt": "Summarise overnight activity.",
      "schedule": { "kind": "cron", "expr": "0 8 * * *" }
    }
  ]
}

Related

• Agents - what a package controls after upload
• Skills - the namespaces you grant in skills
• Agent schedules - schedules.json
• Agent authoring skill - the file external AI tools follow