Agents

In Flow, agents are governed AI personas for chat and automation. Each one is a package in Fontana Files (AGENT.md with YAML frontmatter plus a Markdown system prompt, optional schedules.json, optional avatars/ image pointed at by frontmatter icon, and sibling files such as the mailbox and saved assets). You edit it under AI → Agents or in File System (/files). Every tool call is audited; every agent runs inside the permissions you set.

To draft a package outside Flow and upload the folder, see Author agents. External AI tools start from the Fontana docs skill, which sends an agent-building task to the agent authoring skill.

Agent definitions follow the open AGENTS.md pattern. AI → Agent packages embeds the File System explorer filtered to namespaces tagged agents. Simple view, the default, lists each agent as a tile (avatar, name and role) under an Agents heading. Folders you add inside the agents folder appear as subheadings. Clicking a tile starts a new chat with that agent, and its menu opens Make default, Duplicate, Move to namespace, Settings, and Delete. Move to namespace copies the agent into another namespace you can write. Choose File under Explorer view in the explorer settings to browse the agent’s files; the explorer then opens the correct editor card for each path, and saving writes the file.

The header message box and a new AI Chat start on the agent you set with Make default. On Agents, the agent in the address bar still selects that agent in the header box. A chat that is already open keeps its agent.

Where agent files live

Agents live in Fontana Files namespaces tagged agents. A namespace is named exactly as you name it (any name without a slash), and the same namespace can also hold skills and Knowledge Graph documents. On AI → Agents, hover the catalog and use + beside a namespace name to create an agent in that namespace. Any folder that holds an AGENT.md (matched in any letter case) is an agent; new agents go under the namespace’s agents/ folder. An agent id is the namespace plus the folder path, for example finance/agents/nav-analyst for agents/nav-analyst/AGENT.md in the finance namespace. Agents do not nest: everything under the agent’s folder belongs to that agent, so a folder inside it cannot hold another AGENT.md, and a folder cannot hold both an AGENT.md and a SKILL.md. Everything under the package lives there: AGENT.md, schedules.json, avatars/, the mailbox/ folders, and assets/ such as voice snippets and browser screenshots.

Every edit goes to the file, whether it comes from the Agents page, the File System page, an agent tool, or an identity or avatar change in chat. In the File System page, an AGENT.md opens with the agent editor, and a schedules.json opens with the rendered schedules as Preview and the JSON as Source. After a save, the agent catalog, schedules, abilities, mailbox address, and Teams bot follow once the file syncs, usually within a few seconds.

When a file cannot be parsed, the agent keeps running on its last good version, and the error shows on the Agents page and in the File System page until you save a valid file. Deleting AGENT.md removes the agent.

Shipped defaults

Fontana ships ready-to-use agents you can tailor for your organisation:

Fontana agent (system/agents/fontana-agent) - the assistant on every page, including /ai/chat, unmapped routes, and general routing (including agent schedules). When you start a chat on a Flow surface such as Dashboard, Files, Knowledge Graph, Skills, or an Admin route, Fontana agent activates that page’s skill, so one agent carries the page-specific tools without a separate agent per page.
Workflow agent (system/agents/workflow-agent) - the agent on /workflow; the workflow canvas is the one surface with its own agent. The new-chat picker selects it there. You can change the agent before the first send; your choice sticks until you navigate again.
Canvas agent - specialist for building and editing workflow graphs (nodes, edges, ports, and canvas config). It remains a sub-agent of system/agents/workflow-agent, typically invoked by delegation.
Image, audio, and video agents - specialists that create a picture, a spoken clip, or a short video from your request. Chat stores the file with the message and plays it in the thread, including on the sub-agent card in the main conversation. Speech uses the agent’s own voice when one is configured. The audio agent speaks when that agent has no voice.
Operations specialists - agents for work such as reconciliation, fund accounting, corporate actions, and compliance. A new chat shows the selected agent’s description under its name, and the agent picker shows the same line, so you can see what it can do before you send.

On AI → Agents (/agents) with no agent selected, Flow shows a welcome plus your last three chats that belong to an agent. Each tile reopens that thread; the overflow menu copies the link, opens a new tab, marks unread as read, or deletes the chat. The expanded left-sidebar AI list opens that agent’s chat on Agents (/agents?agent=). AI → Agent packages (/ai/agents) is the package explorer. The menu next to the Agents title in the catalog sidebar opens Usage, Embeddings, API Keys, Chat Channels, and the other AI pages in the same pane. In a chat drawer, Agent Settings on the agent toolbar opens that agent’s editor on AI → Agents.

When you send a message on an existing thread from a different page than the thread’s current owner, Flow switches the thread to that page’s agent automatically. Intentional non-page transfers still use handoff (chat_handoffThread) to allowlisted agents. Chat history is per-user across pages (not siloed by workflow).

Where conversations are saved

Every conversation is saved to Fontana Files as soon as a turn completes. Each person has one private threads namespace, granted to them alone, with one folder per conversation: a thread.md header, one Markdown file per turn (your message, the agent’s answers, and each tool call with its result), and the files attached in that turn. A shared conversation is saved to every participant’s threads namespace, and leaving it removes your copy. Editing or deleting a turn file in File System changes what the chat shows and what the agent reads on its next turn. Workflow AI nodes are not saved: their conversations end with the run.

Your threads namespace is part of the Knowledge Graph, so in a chat of your own an agent can search your past conversations with its Knowledge Graph tools. Shared conversations, Slack and Teams threads, schedules, evaluation runs, and Knowledge Graph extraction never search anyone’s conversations, and the automatic Knowledge Graph search at the start of a turn never includes them. Nobody else’s agents search your conversations, a file admin’s included.

On Skills, the Skills page skill lets Fontana agent manage namespaces, packages, and files under the same namespace grants as the Skills page. Page selection (namespace, folder, file) is sent as structured chat context. When you ask to open a named skill, Fontana agent resolves it via the skill catalog and navigates to that skill’s SKILL.md (not only the Skills home page).

On Agents, the Agents page skill lets Fontana agent create and manage portable agent packages the same way: it picks a non-reserved namespace (users when only Fontana system exists; otherwise it asks), writes agents/<name>/AGENT.md with role-ready system prompts and defaults that include handoff to system/agents/fontana-agent for Fontana product requests, and opens the package in the explorer. It does not author into the reserved system namespace (or legacy default if present).

Creating an agent

+ beside a namespace on AI → Agents opens a short wizard for the name, role, and avatar. Flow then opens that agent’s chat. The agent greets you by name and by the time of day, then asks a few questions, one at a time, about what it should do, who it works with, and when it should run. Your answers are written into that agent’s own package. You can open the same conversation again later to change or add to the profile, and you can edit the same settings in the agent editor while the chat is open.

A new agent starts with the Knowledge Graph, Computer, and Agents abilities on. Computer starts with internet off. The Agents ability can hand work to every agent in the system namespace, including ones added later. Fontana skills are available for the agent to open.

Fontana-shipped agents and abilities live under system/, and every platform update reconciles that namespace: a package Fontana no longer ships is removed, and moving your own agent package into system or creating a skill there is refused. Keep your own packages in your own namespaces.

You can clone these defaults, adjust prompts, switch abilities on or off, and grant Skills namespaces as your operating model requires.

For recurring scheduled prompts on a persistent chat thread, see Agent schedules. For mailboxes and send/receive tools, see Agent email.

Configure each agent

In AI → Agents, you edit the package files that define each persona:

Setting	What you control
Id and display name	Stable identity and the label users see in chat
Avatar	Roster head on an accent ring (the same catalog face in the Agents sidebar, chat bubbles, hover tooltips, and pickers). Optional raster under the package `avatars/` folder; frontmatter `icon` points at the file. Upload or remove from the agent card header.
Description and system prompt	Short summary plus Markdown instructions that define tone, scope, and operating rules
Language model	Approved model override; leave empty to use the deployment default
Abilities	Fontana’s built-in abilities (Email, Messaging, Knowledge Graph, Data, Files, Workspaces, Workflow documents, Agents, System One, Fontana Browser, Computer, plus one per MCP connection you add). Each ability is a tile with an on/off switch. Select one tile to edit its settings and its Auto-load switch. An ability that is off keeps its settings. See Tools and MCP
Skills	A tree of skill namespaces. Tick a namespace to grant every skill in it. Expand a granted namespace to see its outermost skills, and expand a skill that contains others to see those nested skills. Each skill has an On-demand / Preloaded switch. Discover skills on first turn (on by default) makes the agent list the skills it may open before its first reply. Fontana page skills, including Skill authoring and MCP connections, come with the `system` namespace. See Skills
Auto-load	On an enabled ability: On puts its instructions and tools in from the first message, and the agent can close it later when the job is done. Off (the default for most) waits until the task needs it. Knowledge Graph is the one ability that auto-loads by default. On each skill under a granted namespace, the same choice is the On-demand / Preloaded switch: Preloaded matches On, On-demand waits until the agent opens the skill.
Available in	Under Advanced settings. Tiles for where you can pick the agent: Chat (chat pickers, your default agent, handoff targets, chat channels, schedules), AI node (workflow AI nodes), KG extract (Knowledge Graph ontology agent), and Internal (background workers Fontana calls itself, hidden from every picker). Hover a tile to see what it covers. An agent needs at least one; a new agent starts in Chat.
Permissions	Allow-list of the same permissions as a person’s role. When someone invokes the agent, the usable set is that person’s permissions overlapped with the allow-list.
Vector source	Keywords that help route and discover this agent and related workflow templates
Call settings	Optional JSONC for `generateText` fields (`temperature`, `maxOutputTokens`, `topP`, `topK`, `presencePenalty`, `frequencyPenalty`, `stopSequences`, `seed`). Uncomment a key to set it. Unused keys are stored as `_temperature`-style placeholders in AGENT.md so the raw frontmatter stays a parseable mapping. Runtime calls use only unprefixed keys.
Reasoning effort	Off through Max segmented control under Language model (gray to purple). Per-thread chat controls can override.
Context strategy	Default uses platform defaults; Custom sets token limit, compress target, minimum recent user messages, tool-result retention (rounds), and KG body retention (turns). Stale file reads and KG bodies are evicted deterministically; conversation is summarised when still over budget.
KB injection score threshold	Minimum similarity score for automatic Knowledge Graph injection on each turn; per-thread overrides available

Automatic and agentic context

Agents receive Knowledge Graph context in two ways, described fully on Knowledge Graph:

Automatic pre-turn injection - hybrid search over assigned namespaces before each message when you turn on auto-search for the agent, gated by its KB injection score threshold, so likely-relevant approved documents are already in context.
Agentic search - during the work, agents can call Knowledge Graph retrieval directly: hybrid search (full-text, vector, and relationship expansion), outline navigation over long structured documents, and entity navigation, each returning path citations back to the exact source section.

You assign namespaces per agent so regulated corpora stay segregated and retrieval stays least-privilege.

Long threads use a layered context model: durable goals and completed task summaries sit in a compact block after your latest message; stale file reads and KG evidence bodies are evicted automatically or when the agent calls evict context; only conversation text is summarised when the thread is still over budget. Compaction failures appear as failed tool rows in the transcript (no silent pruning).

Workflow-aware assistance

Agents can search community workflow templates by semantic similarity and, with user consent, read workflow configuration from the canvas. That lets assistants help you design and refine pipelines with awareness of graph structure, node types, and connections.

Runtime execution data is queried separately from canvas configuration, so design assistance and live run results stay strictly separated. With the Workflow capability assigned, an agent can also list, read, and update Exception Management tickets for a workflow you can access.

While an agent works on an open workflow, its face shows in the workspace header. On the canvas, one cursor sits with its tip on the bottom centre of the node that agent is working on. The pointer stays the same size when you zoom the canvas, uses that agent’s tone colour, and nudges when the agent calls that same node again. A query that names a node, including a workflow config lookup for that node’s id, moves the cursor there. The same face appears on a port grid or an exception row the call touches. On the Exceptions board, that face sits at the top right of the card, next to the title. On the Exceptions table, each agent has one cursor. Its arrow head sits at the end of a value that agent’s latest call updated, such as a Status pill or the last comment, halfway up the value, and it moves when the agent updates another cell. The face stays on the left of every row the agent touched. Show Agent Cursor in that view’s settings hides those cursors. The face stays in colour while that chat is still running. After the chat goes idle, a finished call stays visible as a gray silhouette, with how long ago it completed, and then drops off. Click a face to open that agent’s chat, including the thread when the work belongs to one. Show Agent Cursors in the workspace actions menu is on unless you turn it off. Turning it off hides the canvas cursors. The header, grids, and exception faces stay. The same switch is on the workflow preferences page.

Diagrams in chat

When an agent (or any other markdown surface in Flow) includes a fenced Mermaid diagram, you can zoom, pan, fit, export SVG or PNG, copy the diagram, and open it fullscreen from the hover controls on the preview. Inline previews do not zoom on mouse wheel (the page keeps scrolling); fullscreen keeps wheel zoom. Raw shows the Mermaid source in the same preview box; the control then reads Diagram to return to the chart. Language-less ASCII pipeline trees (box-drawing lines with pipeline arrows) render as the same interactive flowchart.

Sending while the agent is busy

The composer decides how a message you send lands while a reply or tool run is in progress. The cog beside the prompt sets the send mode, and Auto is the default: it interrupts while the agent is writing its reply and steers while tools are running. Enter and the purple button always use the mode you picked.

Steer lands your message in the thread right away; the agent answers it as soon as the current step settles.
Interrupt cancels the running turn and any pending tools, then answers your new message immediately.
Queue holds the message until the current turn finishes. Queued messages appear in a drawer on top of the prompt box where you can drag to reorder, edit, remove, or send one now. One queued message is sent each time the agent goes idle. Stop pauses the queue; the next completed turn resumes it.

When a question form is open above the prompt, sending a message closes that form in every send mode. The agent is told you answered in the chat, and your message is sent. If the form was the only step still running, Steer, Queue, and Auto send that reply immediately. Interrupt also cancels any other tools that were still running.

The same cog holds the composer preferences: auto-apply canvas suggestions, auto-read replies, and clearing every message in the thread.

Tool call details

Every tool call in a chat opens the same way. Click its row to see a readable summary built for that kind of call: a before and after diff for a document edit, a list of skills, files, or agents, a table of query rows, the Knowledge Graph results. The code icon on the right switches to the raw request and response, and clicking it again switches back. An open row sits on a light tinted background so you can see where it starts and ends.

Tool call details in the chat cog sets how much of each run opens on its own:

None leaves tool runs and reasoning out of the transcript. Page suggestions stay. Successful email send and read stay as collapsed tool rows plus a collapsible mail card.
Compact keeps each run of tool calls on one line until you open it. This is the default.
Expanded opens each run so you see every call in it.
Full also opens every call to its summary.

Opening or closing a row yourself always wins over the setting for that row.

Query mode

The icon beside the model chip sets the composer mode. Agent sends your message to the agent. Query runs what you type as a query on files in the namespace, at once and without an agent turn. Ask is listed for a later release.

In Query mode a bar above the prompt holds the query type (sql by default, then grep, jsonpath, jsonata, jinja, text, javascript, python), the namespace, and the files. On a workflow page the namespace is the workflow’s Workspace; elsewhere you pick one. The file picker starts on auto: SQL takes its tables from the quoted paths in the query, grep takes the path or folder the pattern names, and the other types take a path written in the query. When nothing resolves, the bar says so and nothing runs. Pick files to skip auto.

The query and its result land in the thread as a tool call that every tool call details setting shows and opens. The result shows the type, files, the query, and rows as a table, grep hits as path and line, or text, with Copy all. The mode stays Query after a run; switch back to Agent to ask about the result, which the agent sees like any other tool result. The help icon beside the type switches to Agent mode with a request for example queries of that type on those files. Run query on an agent’s SQL data query card prefills Query mode with the card’s query, its tables renamed to the published files of the last Workspace run. A JSONPath, JSONata, or Jinja card prefills only its text, because those queries read the run’s resources rather than a file; pick the files and rewrite it. The query runs only while the agent is idle.

On Home Custom, selecting a card attaches it to docked AI Chat as a composer chip. Stats show as Stat with title and value. Other cards show as Home card plus the cell title. Dismissing the chip clears the selection ring. The send payload includes the card id, type, and title so the agent knows which cell you selected.

If the server restarts in the middle of a turn, the thread recovers on its own: unanswered tool calls are closed with a visible error and any message you sent meanwhile is answered once the thread is idle again.

Permissions

Which agent namespaces you see is decided by your Fontana Files grants on each namespace, together with the agents:read and agents:write permissions of your role: you need both. When Fontana creates a namespace, it grants everyone in your workspace viewer access to system and editor access to every other namespace. You narrow or extend those grants in File System (/files), as for any other namespace, and Fontana keeps your changes.

Open the agent package and choose Permissions. The list is grouped by area: all permissions, a whole area, then each permission. You can turn on a permission outside your own role, so a colleague who holds it can use the agent for that work. Your own session still uses only the overlap of your role and this list. Admin → Roles and your profile keep the grid and the YAML view as well.

A new agent starts with every catalog permission on the allow-list. Invocation still limits the agent to what you hold. A sub-agent and a handoff target are limited the same way: your permissions overlapped with that agent’s allow-list. The agent that called or handed off does not remove permissions you still hold.

Profile has an Account section and a Permissions section. Permissions uses the same grid, and you cannot edit it there. Activity logs record the usable set for each invocation, and whether each tool call was allowed or denied.

Delegation and handoff

Complex work can span multiple agents without losing governance:

Sub-agents run delegated tasks in child threads while the parent conversation continues under audit.
Handoff transfers the same thread to another in-app agent when the task surface changes (for example from planning to canvas editing).

Peer-agent federation with external platforms uses separate interop protocols. See Agent Interop for A2A, ACP, and related patterns.