Una Agents
Una Agents are AI workers you define as simple Markdown files. Each agent has a name, a role, a set of tools it can use (these are a subset of the skills present in the Bot UI), and a system prompt that shapes how it thinks and communicates.
This guide covers how to write an agent file, what all the fields do, and how to get the best results.
Where to Put Agent Files
Agent files live in the Una file system. Place them at:
/Local AI/Agents/<agent-name>.md
The file name (without .md) is the agent's identifier. It must be lowercase kebab-case:
/Local AI/Agents/report-designer.md
/Local AI/Agents/data-validator.md
/Local AI/Agents/budget-analyst.md
Note: The platform also looks under
/AI/Agents/for agents shared by all tenants, while/Local AI/Agents/is the location for tenant-specific agents.
Invoking an Agent
Type the agent name as a slash command in the AI chat:
/report-designer I need a revenue report for EMEA comparing Actual vs Budget for 2025
/data-validator Check the headcount data in the March upload for consistency issues
The platform loads the agent's file, applies its model and tools, and runs your request through its system prompt.
Agent File Structure
An agent file has two parts: a frontmatter block at the top and an instructions section below it.
---
name: my-agent
description: One or two sentences describing what this agent does and when to invoke it.
model: model-router
temperature: 0.7
tools:
- queries
- file system
---
# My Agent
You are an expert in...
(Full system prompt here)
The frontmatter must be the very first thing in the file, delimited by --- on both sides. Everything after the closing --- is the system prompt.
Frontmatter Fields
name (required)
The agent's identifier. Must match the filename (without .md).
name: report-designer
description (required)
A one- or two-sentence description of what this agent does and when it should be used. This is read by the orchestrator when deciding which agent to assign a task to in multi-agent mode — make it specific and accurate.
description: Analyzes business requirements and a data model to produce a structured report specification. Use when a user needs to design a report including widgets and model queries.
Tip: A vague description ("A helpful agent") means the orchestrator cannot assign tasks to this agent reliably. Describe what it produces and what inputs it expects.
model (required)
The language model to use. Available values depend on your environment configuration.
| Value | Description |
|---|---|
model-router | Recommended default. Routes to the best available model for the task. |
gpt-4.1 | GPT-4.1 (Azure OpenAI) |
gpt-4o | GPT-4o |
claude-sonnet | Claude Sonnet (if configured) |
When in doubt, use model-router.
model: model-router
tools (optional)
List of tool groups (same as the skills in the bot ui) the agent is allowed to use. If omitted or set to ["*"], the agent has access to all available tools.
tools:
- queries
- file system
Available tool groups:
| Tool Group | What It Does |
|---|---|
queries | Query financial and planning data models. Retrieve dimension members, run model queries, variance analysis, global variables. |
file system | Read, create, update, and delete files and folders in the Una file system. |
users | Manage users and security groups — list, create, add/remove from groups, check login activity. |
actions | Manage workflow actions — list, view, create, update status and completion percentage. |
odata | Run OData queries against staging/integration tables to retrieve raw data rows. |
opords | Execute predefined operational order scripts (opords) by name. |
una help | Search the Una product documentation to answer how-to questions. |
code interpreter | Execute Python code for calculations, data processing, or chart generation. |
web search | Search the web for current information. |
devops | Tenant infrastructure management (Una employees only). |
go to market | Go-to-market pipeline tools. |
* | All available tools (default when tools is omitted). |
Principle of least privilege: Give agents only the tools they need. A report-designing agent only needs queries and file system. Restricting tools reduces the chance of unintended side effects and speeds up the model.
color (optional) WIP
UI accent color for the agent card. Accepts a CSS color name or hex value.
color: blue
The System Prompt (Instructions Section)
Everything after the closing --- is the agent's system prompt. This is sent to the model as the system role at the start of every conversation. It defines who the agent is, what it knows, and how it should behave.
Recommended Structure
# Agent Name
One-sentence summary of the agent's role.
## Overview
2–3 sentences explaining what this agent does, what inputs it expects, and what it produces.
## Domain Knowledge
Background information the agent needs. Definitions, rules, domain-specific concepts.
## Workflow
Step-by-step description of how the agent should approach a task.
1. Step one
2. Step two
3. ...
## Output
Description of what the agent must produce — format, structure, required fields.
## Examples
Optional but highly recommended. One or two worked examples.
You are not required to use this exact structure. What matters is that the system prompt gives the agent enough context to do its job without needing clarification on every request.
Best Practices
Write a strong role statement
Start with a clear identity: "You are an expert financial data analyst specialising in variance analysis." The model uses this to calibrate its tone, depth, and reasoning style for every response.
Be explicit about output format
If the agent produces structured output (a .md file, a JSON object, a table), describe the exact format in the system prompt and include a template or example. Agents that produce free-form prose rarely integrate well with downstream automation.
List what the agent should do when inputs are missing
Tell the agent what to ask for rather than having it guess. Example: "If the user does not specify a model name, ask for it before proceeding." This prevents silent errors.
Keep the system prompt focused
Each agent should do one thing well. If you find yourself writing instructions for two unrelated tasks, split them into two agents. The orchestrator can assign tasks to multiple agents automatically — you don't need one agent to do everything.
Calibrate tools to the task
An agent that only reads data should have queries and file system — not actions or devops. Fewer tools = faster execution and lower risk of unintended writes.
Test with the direct slash command first
Before using an agent in a multi-agent workflow, invoke it directly in chat: /my-agent here is a test request. This lets you verify the system prompt and tools work as expected before the orchestrator assigns it tasks.
Multi-Agent Mode
When you invoke /agentic in the AI chat, the platform automatically:
- Clarifies your requirements if anything is ambiguous
- Creates a plan — a list of tasks, each assigned to a named agent
- Resolves agents — loads each named agent from
/Local AI/Agents/(or creates an ad-hoc agent if no file exists) - Executes tasks in dependency order — tasks that don't depend on each other run concurrently
- Reviews the plan after each completed task and adjusts if needed
- Produces a final output — files written to
/AI Local/Results/<timestamp>/
Your named agents are first-class participants in this pipeline. If the orchestrator's plan references an agent called report-designer, it will look for /Local AI/Agents/report-designer.md. If found, it uses your file; if not, it creates a minimal ad-hoc agent for that role.
Agent Output in Multi-Agent Mode
When running as part of a plan, each agent must return a structured result. The agent runner handles this automatically — your system prompt does not need to describe the JSON envelope. Focus the system prompt on the content of the output (the report, the analysis, the file) rather than the technical response format.
Agents can write files to the work folder during execution. Files marked as final output are collected and surfaced to the user at the end of the run.
Complete Example
File: /Local AI/Agents/report-designer.md
---
name: report-designer
description: Analyzes user requirements and a data model description to produce a structured .md report specification file. Use when a user provides business requirements and a data model and wants to design a report — including what the report does, the widgets it contains (charts, KPIs, tables), and the model queries needed to power each widget.
model: model-router
temperature: 0.3
tools:
- queries
- file system
---
# Report Designer
You are an expert financial report designer for the Una platform.
## Overview
Analyze business requirements and a provided data model to produce a fully structured report specification as a `.md` file. The specification describes the report's purpose, the list of widgets it contains, and a detailed breakdown of each widget including what it shows and the model query that powers it.
## About Model Queries
The data model consists of fact tables. Each fact table has:
- **Dimensions** — categorical axes (e.g. Time, Entity, Scenario, Department, Currency). Dimensions have hierarchies with members (e.g. Time → Year → Quarter → Month).
- **Measures** — numeric values stored in the fact table (e.g. Revenue, Headcount, Budget).
A **model query** retrieves aggregated data from a fact table. It returns a 2D result set. You specify:
- **Rows axis** — which dimension(s) go on rows and which members to include
- **Columns axis** — which dimension(s) go on columns and which members
- **Measures** — which measure values to return (use `Value` unless otherwise instructed)
- **Filters** — dimensions not on rows/columns but required for slicing (e.g. Scenario = "Actual")
Use the `GetModelList` and `GetDimensionMembers` tools to validate dimension names and member names before writing queries. Always confirm the model exists before referencing it.
## Workflow
1. **Parse requirements** — identify the business question, target audience, and success criteria.
2. **Parse the data model** — understand the fact tables, dimensions, hierarchies, and measures.
3. **Validate with tools** — use `GetModelList` and `GetDimensionMembers` to confirm names.
4. **Design the widget list** — decide which 2–5 widgets best answer the business questions.
5. **Specify each widget's model query** — define rows, columns, measures, and filters using confirmed names.
6. **Write the specification** — produce the `.md` file using the template below.
## Output Format
Produce a single `.md` file with this exact structure:
---
# Report Specification: [Report Name]
## 1. Overview
| Field | Value |
|-----------------|------------------------------|
| Report Name | [Name] |
| Version | 1.0 |
| Created | [YYYY-MM-DD] |
| Target Audience | [Who will use this report] |
## 2. Business Requirements Addressed
[2–4 sentences explaining what business question this report answers.]
| # | Requirement | How This Report Addresses It |
|---|-------------|------------------------------|
| 1 | [Text] | [Explanation] |
## 3. Widget List
| # | Widget Name | Widget Type | Purpose |
|---|-------------|-------------|---------|
| 1 | [Name] | [Type] | [One line] |
## 4. Widget Specifications
### Widget [N]: [Widget Name]
**Type:** [KPI / Line Chart / Bar Chart / Table / Heatmap / ...]
**Purpose:** [1–2 sentences.]
**Description:** [What the user sees, axes, interactions.]
**Model Query:**
| Query Property | Value |
|-------------------|------------------------------------|
| Model | [model name] |
| Rows | [Dimension]: [member selection] |
| Columns | [Dimension]: [member selection] |
| Filter: [DimName] | [Member(s)] |
| Measure | Value |
## 5. Missing Model Elements
| Widget # | Required Element | Where Expected | Status | Recommendation |
|----------|-----------------|----------------|--------|----------------|
| [N] | [element] | [table/dim] | MISSING | [Action] |
---
If any required dimension or measure is not present in the model, mark it as `MISSING — not in model` and add it to section 5.
Quick Reference
| Field | Required | Default | Notes |
|---|---|---|---|
name | Yes | — | Must match filename (lowercase kebab-case) |
description | Yes | — | Used by orchestrator for task assignment |
model | Yes | — | Use model-router unless you need a specific model |
temperature | No | 0.7 | Use 0.0–0.3 for structured output |
tools | No | All tools | List only what the agent needs |
color | No | — | UI accent color |