Knowledge Base Academy Community My Tickets
Fabric 8.5
Fabric 8.5

Agent Editor

The Agent Editor is the visual editor for agent definitions. It opens automatically for <LU>/AI/Agents/<agent>/agent.yaml and for sub-agent files under <LU>/AI/Agents/<agent>/Subagents/*.yaml, whether you open them from AI Explorer, the file Explorer, or a New Agent… / New Sub-Agent… command.

The editor gives you a structured form for every key of the agent schema, so you do not have to remember key names or YAML syntax. It writes back to the same agent.yaml file, so the file in Git stays the source of truth, and you can always switch to the raw YAML.

Editor Layout

The top strip of the editor has two tabs:

Tab Purpose
Editor Edit the agent definition, as a form or as YAML source.
Preview Chat with the deployed agent and inspect the trace. See Preview and Trace. Shown for top-level agents only; sub-agents cannot be run on their own.

When you open a top-level agent, the editor lands on Preview. Click Editor to edit the definition.

On the Editor tab, a Form / Source toggle switches between the two views:

  • Form — collapsible cards, one per area of the definition. All cards start collapsed and show a short summary (for example, word counts or how many tools are configured), so the form reads as an overview. Use Expand all / Collapse all to open or close every card.
  • Source — the raw YAML in an embedded code editor. Changes made in either view are reflected in the other.

If the file has a YAML syntax error, the editor switches to Source and shows a banner (YAML syntax error — fix it here in Source view) with the parser message. The form is unavailable until the file parses again.

How the Editor Writes the File

The form only updates the keys you change. Comments, key order and keys the editor does not know about are preserved, so a hand-edited agent.yaml survives a round trip through the form. Settings equal to their default are not written to the file.

You can still open the file as plain text with Open With… > Text Editor from the file's context menu.

Description

A short, human-readable summary of the agent. It is also the delegation hint: when this agent is used as a sub-agent, the parent agent reads the description to decide when to call it. YAML key: description.

System Prompt

The agent's main instructions, in Markdown. YAML key: system_prompt.

The field is a Markdown editor with syntax highlighting, edit and preview tabs, a heading Outline that jumps to a section, and a word count. The same editor is used for Response guidelines and Constraints.

Response Guidelines and Constraints

Both fields hold Markdown and both affect the final reply, but they behave differently when a turn is handed to a sub-agent:

Field YAML key Use it for Across a delegate handoff
Response guidelines response_prompt House style for the user-facing reply: tone, formatting, what must never be exposed. The turn owner's guidelines travel to the sub-agent and replace its own.
Constraints constraints Non-negotiable domain rules, such as "last four digits only". The caller's constraints are added to the sub-agent's own; both apply.

Click the ? on either card to open the Guidelines and constraints matrix, which shows what happens to each on every route: when the agent answers itself, when it calls a sub-agent with task, and when it hands the turn over with delegate.

In a sub-agent file, Response guidelines shows a Not in use yet note: a sub-agent never owns a turn, so its response guidelines take no effect. Use Constraints for rules that must hold whoever calls the sub-agent. See Sub-Agents and Delegation.

Tools & Interfaces

This card controls which tools the LLM can call. YAML keys: tools, mcp_interfaces.

Built-in Tools

Three built-in tools can be switched on or off:

Tool Default What it does
query On Runs an SQL query against the entity's Fabric micro-database (SQLite).
fabric Off Runs Fabric commands. This is a privileged tool — enable it only when the agent really needs it.
current_datetime On Returns the current date and time (UTC, ISO-8601) for the turn.

The core tools — task, ask_user, the skill tools, the reference-search tools and, for top-level agents, the planning tools — are added automatically and are not listed here.

Flow Tools

Click + Add flow tool to expose a Broadway flow as a tool. The picker lists the flows of the agent's LU and of Shared Objects; table population flows are excluded. Click the flow name's open icon to open the flow itself.

The extension has no wizard for creating tools: a tool is an existing Broadway flow, which you build with the regular Studio flow editor. See Tools.

Per-Tool Hooks

Every built-in or flow tool row has a Before and an After selector. A Before flow runs just before that tool is invoked (to mask arguments, validate, or block the call); an After flow runs on its result (to audit, redact or cache). These hooks apply to that one tool only; the agent-level pre_tool_call / post_tool_call hooks still run for every tool. In YAML, a tool with hooks is written as a single-key map:

tools:
  - query
  - current_datetime
  - getAccounts:
      before: MaskPII
      after: AuditLog

MCP Interfaces

Type the names of MCP interfaces defined in the project. Their tools become available to the agent. See Tools.

Hooks

Agent-level lifecycle hooks, each a single Broadway flow. YAML key: hooks. Each row shows the flow's inputs and what it may return.

Label YAML key Purpose
Before the user message step_start Inspect or rewrite the turn's user message before the model sees it. This is also where an entity-scoped agent loads its entity instance.
After the answer step_end Validate the answer and optionally trigger a follow-up run.
Before a tool call pre_tool_call Inspect and optionally block any tool call (ALLOW / BLOCK).
After a tool call post_tool_call Observe or log a completed tool call, or end the run early.
When the run errors on_error Customize the error message shown when an agent run fails. Tool errors are handled by the after-a-tool-call hook.

The external parameters of the hook flows are the agent's inputs — they are what the Preview New chat dialog asks for. See Hooks and Inputs.

Subagents

This card is shown for top-level agents only. YAML keys: sub_agents, delegate.

  • Folder sub-agents — every file in the agent's Subagents/ folder is listed automatically and is available by default. Switch one off to hide it from the agent without deleting it.
  • Linked agents — click + Add subagent, choose a Data Product (LU) under DATA PRODUCT, and pick a top-level agent from that LU. This lets an agent reuse another agent, including one from a different LU.
  • Allow handing a turn to a subagent — off by default. When on, the agent gets the delegate route: a sub-agent can answer the user directly, and the parent's response guidelines travel with the turn.
  • Route per sub-agent — enabled once handing off is allowed: Both (the agent decides per request; the recommended default), Task only (the sub-agent always returns its result to the parent, which writes the reply), or Delegate only (the sub-agent answers the user and ends the turn). YAML key per entry: invoke.

Sub-Agent Validation

The editor checks every sub_agents: entry and reports broken references in the Problems panel as errors, and the agent's agent.yaml (and its node in AI Explorer) is decorated in red. The checks are:

  • A folder entry must match a file Subagents/<name>.yaml of this agent.
  • A linked entry must name an existing LU, and an existing top-level agent in that LU.

In the form, a broken entry is tagged missing.

Planning

Shown for top-level agents only (sub-agents never plan). YAML key: planning.

  • Plan-then-execute — enables planning mode.
  • Require user approval of the plan — the agent waits for the user to approve the plan before executing it.
  • Custom planning prompt — optional; leave blank to use the default.

See References and Planning.

Reference-document search lets the agent search the reference packs under its References/ folder (for example, References/KB and References/Procedures). Packs are discovered automatically. An optional Custom ref-search prompt replaces the default instructions. YAML key: search_reference.

Widgets

Enable widget building lets the agent produce charts and tables in the chat. YAML key: widget.

Skills

Skills in the agent's own Skills/ folder are discovered automatically and do not need to be listed. Use this card to:

  • Add LU-wide or shared skills — click + Add skill to pick a skill from the LU's AI/Skills/ or from Shared Objects (each entry shows its origin), or type a name.
  • Auto-load — switch on to inject a skill into the system prompt from the start of every conversation, instead of letting the agent load it on demand.

YAML key: skills. See Skills.

Settings

Every setting is optional. Each row shows the default it falls back to; a changed value shows a reset button, and values equal to the default are not written to the file. In a sub-agent, unset values are inherited from the parent agent instead.

Label YAML key (under settings) Default Description
LLM interface llm_interface default The LLM interface used for the agent's LLM calls.
Thinking thinking off Extended-reasoning level: off, low, medium, high, xhigh, max.
Prompt caching use_cache true Caches prompt prefixes at the provider. Pays off for multi-turn and high-volume agents.
Logging level logging_level info off, debug, info or warn.
Snap session mode snap_session_mode none Which sessions are snapshotted: none, all, frequency (about one session in N, snap_frequency_limit, default 10) or period (at most one session per interval, snap_period_value / snap_period_unit, default 15 minutes).
Evaluation defaults eval_defaults_name evalDefaults The named default set (from the evaluation defaults MTable) that new test cases take their dimensions and thresholds from.
Max iterations max_iterations 20 Tool-call loop cap within a single turn.
Max retries max_retries 1 Automatic retries when a tool call fails.
Max step continuations max_step_continuations 3 How many follow-up runs are allowed after an answer (0 disables).
Memory memory false Persistent memory blocks across turns and sessions.
Observability observability true Persists messages, executions, token usage and tool calls. The Preview trace is read from this data.
Threshold fraction compaction_threshold_fraction 0 Compact the context when it reaches this fraction of the window (for example, 0.8).
Context window (tokens) compaction_context_window_tokens 0 The model's context window (for example, 200000).
Keep recent messages compaction_keep_recent_messages 20 Most recent messages kept verbatim; older ones are summarized.
Compaction interface compaction_interface default A separate LLM interface for the summarization call, for example a cheaper model.

Context compaction is off by default and runs only when both the threshold fraction and the context window are greater than 0. Note that the New Agent… template sets several of these explicitly (for example, thinking: medium, memory: true, max_iterations: 30 and compaction at 0.8 of 200000 tokens) — see AI Fusion Studio Overview. For details on each setting, see the agent.yaml Reference and Sessions and Context.

Editing Sub-Agents

A file under Subagents/ opens in the same editor, with these differences:

  • There is no Preview tab — sub-agents run only through their parent.
  • The Subagents and Planning cards are hidden (delegation is single-level, and sub-agents never plan).
  • Response guidelines carries the Not in use yet note.
  • Settings fall back to the parent agent's effective values, labeled inherited.

After You Edit

Saving agent.yaml changes the file only. Deploy the agent's LU (a soft deploy is enough) before testing the change in Preview — Preview talks to the deployed agent. See When Changes Take Effect.

Next article: Preview and Trace

Agent Editor

The Agent Editor is the visual editor for agent definitions. It opens automatically for <LU>/AI/Agents/<agent>/agent.yaml and for sub-agent files under <LU>/AI/Agents/<agent>/Subagents/*.yaml, whether you open them from AI Explorer, the file Explorer, or a New Agent… / New Sub-Agent… command.

The editor gives you a structured form for every key of the agent schema, so you do not have to remember key names or YAML syntax. It writes back to the same agent.yaml file, so the file in Git stays the source of truth, and you can always switch to the raw YAML.

Editor Layout

The top strip of the editor has two tabs:

Tab Purpose
Editor Edit the agent definition, as a form or as YAML source.
Preview Chat with the deployed agent and inspect the trace. See Preview and Trace. Shown for top-level agents only; sub-agents cannot be run on their own.

When you open a top-level agent, the editor lands on Preview. Click Editor to edit the definition.

On the Editor tab, a Form / Source toggle switches between the two views:

  • Form — collapsible cards, one per area of the definition. All cards start collapsed and show a short summary (for example, word counts or how many tools are configured), so the form reads as an overview. Use Expand all / Collapse all to open or close every card.
  • Source — the raw YAML in an embedded code editor. Changes made in either view are reflected in the other.

If the file has a YAML syntax error, the editor switches to Source and shows a banner (YAML syntax error — fix it here in Source view) with the parser message. The form is unavailable until the file parses again.

How the Editor Writes the File

The form only updates the keys you change. Comments, key order and keys the editor does not know about are preserved, so a hand-edited agent.yaml survives a round trip through the form. Settings equal to their default are not written to the file.

You can still open the file as plain text with Open With… > Text Editor from the file's context menu.

Description

A short, human-readable summary of the agent. It is also the delegation hint: when this agent is used as a sub-agent, the parent agent reads the description to decide when to call it. YAML key: description.

System Prompt

The agent's main instructions, in Markdown. YAML key: system_prompt.

The field is a Markdown editor with syntax highlighting, edit and preview tabs, a heading Outline that jumps to a section, and a word count. The same editor is used for Response guidelines and Constraints.

Response Guidelines and Constraints

Both fields hold Markdown and both affect the final reply, but they behave differently when a turn is handed to a sub-agent:

Field YAML key Use it for Across a delegate handoff
Response guidelines response_prompt House style for the user-facing reply: tone, formatting, what must never be exposed. The turn owner's guidelines travel to the sub-agent and replace its own.
Constraints constraints Non-negotiable domain rules, such as "last four digits only". The caller's constraints are added to the sub-agent's own; both apply.

Click the ? on either card to open the Guidelines and constraints matrix, which shows what happens to each on every route: when the agent answers itself, when it calls a sub-agent with task, and when it hands the turn over with delegate.

In a sub-agent file, Response guidelines shows a Not in use yet note: a sub-agent never owns a turn, so its response guidelines take no effect. Use Constraints for rules that must hold whoever calls the sub-agent. See Sub-Agents and Delegation.

Tools & Interfaces

This card controls which tools the LLM can call. YAML keys: tools, mcp_interfaces.

Built-in Tools

Three built-in tools can be switched on or off:

Tool Default What it does
query On Runs an SQL query against the entity's Fabric micro-database (SQLite).
fabric Off Runs Fabric commands. This is a privileged tool — enable it only when the agent really needs it.
current_datetime On Returns the current date and time (UTC, ISO-8601) for the turn.

The core tools — task, ask_user, the skill tools, the reference-search tools and, for top-level agents, the planning tools — are added automatically and are not listed here.

Flow Tools

Click + Add flow tool to expose a Broadway flow as a tool. The picker lists the flows of the agent's LU and of Shared Objects; table population flows are excluded. Click the flow name's open icon to open the flow itself.

The extension has no wizard for creating tools: a tool is an existing Broadway flow, which you build with the regular Studio flow editor. See Tools.

Per-Tool Hooks

Every built-in or flow tool row has a Before and an After selector. A Before flow runs just before that tool is invoked (to mask arguments, validate, or block the call); an After flow runs on its result (to audit, redact or cache). These hooks apply to that one tool only; the agent-level pre_tool_call / post_tool_call hooks still run for every tool. In YAML, a tool with hooks is written as a single-key map:

tools:
  - query
  - current_datetime
  - getAccounts:
      before: MaskPII
      after: AuditLog

MCP Interfaces

Type the names of MCP interfaces defined in the project. Their tools become available to the agent. See Tools.

Hooks

Agent-level lifecycle hooks, each a single Broadway flow. YAML key: hooks. Each row shows the flow's inputs and what it may return.

Label YAML key Purpose
Before the user message step_start Inspect or rewrite the turn's user message before the model sees it. This is also where an entity-scoped agent loads its entity instance.
After the answer step_end Validate the answer and optionally trigger a follow-up run.
Before a tool call pre_tool_call Inspect and optionally block any tool call (ALLOW / BLOCK).
After a tool call post_tool_call Observe or log a completed tool call, or end the run early.
When the run errors on_error Customize the error message shown when an agent run fails. Tool errors are handled by the after-a-tool-call hook.

The external parameters of the hook flows are the agent's inputs — they are what the Preview New chat dialog asks for. See Hooks and Inputs.

Subagents

This card is shown for top-level agents only. YAML keys: sub_agents, delegate.

  • Folder sub-agents — every file in the agent's Subagents/ folder is listed automatically and is available by default. Switch one off to hide it from the agent without deleting it.
  • Linked agents — click + Add subagent, choose a Data Product (LU) under DATA PRODUCT, and pick a top-level agent from that LU. This lets an agent reuse another agent, including one from a different LU.
  • Allow handing a turn to a subagent — off by default. When on, the agent gets the delegate route: a sub-agent can answer the user directly, and the parent's response guidelines travel with the turn.
  • Route per sub-agent — enabled once handing off is allowed: Both (the agent decides per request; the recommended default), Task only (the sub-agent always returns its result to the parent, which writes the reply), or Delegate only (the sub-agent answers the user and ends the turn). YAML key per entry: invoke.

Sub-Agent Validation

The editor checks every sub_agents: entry and reports broken references in the Problems panel as errors, and the agent's agent.yaml (and its node in AI Explorer) is decorated in red. The checks are:

  • A folder entry must match a file Subagents/<name>.yaml of this agent.
  • A linked entry must name an existing LU, and an existing top-level agent in that LU.

In the form, a broken entry is tagged missing.

Planning

Shown for top-level agents only (sub-agents never plan). YAML key: planning.

  • Plan-then-execute — enables planning mode.
  • Require user approval of the plan — the agent waits for the user to approve the plan before executing it.
  • Custom planning prompt — optional; leave blank to use the default.

See References and Planning.

Reference-document search lets the agent search the reference packs under its References/ folder (for example, References/KB and References/Procedures). Packs are discovered automatically. An optional Custom ref-search prompt replaces the default instructions. YAML key: search_reference.

Widgets

Enable widget building lets the agent produce charts and tables in the chat. YAML key: widget.

Skills

Skills in the agent's own Skills/ folder are discovered automatically and do not need to be listed. Use this card to:

  • Add LU-wide or shared skills — click + Add skill to pick a skill from the LU's AI/Skills/ or from Shared Objects (each entry shows its origin), or type a name.
  • Auto-load — switch on to inject a skill into the system prompt from the start of every conversation, instead of letting the agent load it on demand.

YAML key: skills. See Skills.

Settings

Every setting is optional. Each row shows the default it falls back to; a changed value shows a reset button, and values equal to the default are not written to the file. In a sub-agent, unset values are inherited from the parent agent instead.

Label YAML key (under settings) Default Description
LLM interface llm_interface default The LLM interface used for the agent's LLM calls.
Thinking thinking off Extended-reasoning level: off, low, medium, high, xhigh, max.
Prompt caching use_cache true Caches prompt prefixes at the provider. Pays off for multi-turn and high-volume agents.
Logging level logging_level info off, debug, info or warn.
Snap session mode snap_session_mode none Which sessions are snapshotted: none, all, frequency (about one session in N, snap_frequency_limit, default 10) or period (at most one session per interval, snap_period_value / snap_period_unit, default 15 minutes).
Evaluation defaults eval_defaults_name evalDefaults The named default set (from the evaluation defaults MTable) that new test cases take their dimensions and thresholds from.
Max iterations max_iterations 20 Tool-call loop cap within a single turn.
Max retries max_retries 1 Automatic retries when a tool call fails.
Max step continuations max_step_continuations 3 How many follow-up runs are allowed after an answer (0 disables).
Memory memory false Persistent memory blocks across turns and sessions.
Observability observability true Persists messages, executions, token usage and tool calls. The Preview trace is read from this data.
Threshold fraction compaction_threshold_fraction 0 Compact the context when it reaches this fraction of the window (for example, 0.8).
Context window (tokens) compaction_context_window_tokens 0 The model's context window (for example, 200000).
Keep recent messages compaction_keep_recent_messages 20 Most recent messages kept verbatim; older ones are summarized.
Compaction interface compaction_interface default A separate LLM interface for the summarization call, for example a cheaper model.

Context compaction is off by default and runs only when both the threshold fraction and the context window are greater than 0. Note that the New Agent… template sets several of these explicitly (for example, thinking: medium, memory: true, max_iterations: 30 and compaction at 0.8 of 200000 tokens) — see AI Fusion Studio Overview. For details on each setting, see the agent.yaml Reference and Sessions and Context.

Editing Sub-Agents

A file under Subagents/ opens in the same editor, with these differences:

  • There is no Preview tab — sub-agents run only through their parent.
  • The Subagents and Planning cards are hidden (delegation is single-level, and sub-agents never plan).
  • Response guidelines carries the Not in use yet note.
  • Settings fall back to the parent agent's effective values, labeled inherited.

After You Edit

Saving agent.yaml changes the file only. Deploy the agent's LU (a soft deploy is enough) before testing the change in Preview — Preview talks to the deployed agent. See When Changes Take Effect.

Next article: Preview and Trace

© Copyright 2026 K2VIEW