# DSL
### What is DSL?
DSL is a **YAML configuration format** that represents an Agent’s full setup, including (depending on type):
* metadata (name, description, tags, icon)
* prompts / instructions
* flows (ChatFlow / JobFlow)
* tools and tool parameters
* variables and bindings
* model configuration
* optional capabilities (e.g., file upload, voice)
DSL enables “configuration as code”:
* easy backups
* easy replication across workspaces
* reviewable changes in Git
* shareable templates inside your team
***
### Where You Can Use DSL
#### 1) Create from DSL (Agent & Multi-Agent)
When creating a new Agent (or Multi-Agent), you can choose **Create from DSL** to bootstrap everything from a YAML file.
#### 2) Export DSL (Draft)
From the Agent editor, you can export the **current Draft** as DSL.
#### 3) Export Config (Published Version)
From **Version History**, you can export DSL for **a specific published Version** using **Export Config**.
#### 4) Import DSL (into an Agent)
You can import a DSL file to load configuration into an Agent.
📌 **Important:** Depending on your product behavior, importing may:
* overwrite the current Draft, or
* create a new Agent from the DSL
> In this doc, label the behavior exactly as your UI works.\
> If import overwrites Draft, say it explicitly.
***
### Supported Agent Types
DSL supports:
* **Instruction Agents** (system prompt + tools + variables)
* **ChatFlow Agents**
* **JobFlow Agents**
* **Multi-Agents**
The DSL `kind` field indicates which type it represents (examples below).
***
### DSL Structure Overview
#### Top-level fields
Most DSL files follow this structure:
* `kind`: the resource type (e.g., `instruction`, `chatflow`, `jobflow`, `multi-agent`)
* `version`: DSL schema version (e.g., `1.0.0`)
* `metadata`: identity and display info (name, description, icon, tags, timestamps)
* `spec`: the functional definition (prompts, flows, nodes, etc.)
* `model_config`: model/provider and generation parameters
* `tools`: enabled tools and their parameter schemas/settings
* optional: `abilities`, `datasets`, `extend_properties` (platform-dependent
***
### Create from DSL (Step-by-step)
1. Go to **Workforce Factory → Agent** (or **Multi-Agents**)
2. Click **Create from DSL**
3. Paste or upload your DSL YAML
4. Confirm → the system creates an Agent with:
* prompts/flows
* tools
* variables
* model config
5. Review the created Draft
6. Publish when ready
***
### Export DSL (Draft)
Use this when you want to:
* backup work-in-progress
* share a configuration with teammates
* commit configuration to Git for review
**Steps**
1. Open the Agent editor
2. Click **Export as DSL** (or equivalent)
3. Save the YAML file
📌 Reminder: this exports the **current Draft** (which may not be published yet).
***
### Export Config (Version) — For Auditing & Releases
Use **Export Config** from Version History when you want a DSL file that represents an **immutable released snapshot**.
**Steps**
1. Open the Agent editor
2. Open **Versions** panel
3. Choose a version → click ⋯ → **Export Config**
4. Save the YAML file
This is the best option for:
* compliance
* production reproducibility
* release backups
***
### Import DSL (Step-by-step)
**Steps**
1. Open an Agent editor (or creation page, depending on UI)
2. Click **Import DSL**
3. Paste/upload YAML
4. Confirm import
📌 **Behavior to document clearly (choose the one that matches your UI):**
* **Option A — Import overwrites Draft:** Import replaces your current Draft configuration.
* **Option B — Import creates a new Agent:** Import generates a new Agent and leaves the original untouched.
***
### Best Practices
#### Keep DSL in source control
Store exported DSL files in Git to:
* track changes over time
* review with PRs
* compare version snapshots
#### Use Version export for production baselines
For production releases, export from **Versions → Export Config** so the artifact matches the published state.
#### Avoid secrets in DSL
Do not store API keys or secrets in plaintext DSL files.
* Use workspace secrets / credentials management (if available)
* Reference secrets by name/ID instead of embedding values (recommended)
#### Watch for portability differences
When importing DSL into another workspace:
* tool availability may differ
* knowledge bases/datasets may not exist
* icon URLs must be accessible
* referenced agents/resources may need remapping
***
### Troubleshooting
#### Import fails due to schema mismatch
* Check `version` field in DSL
* Export a fresh DSL from a working agent and compare structure
#### Tools missing after import
* Confirm the destination workspace has the same tools enabled
* Check tool parameter schemas (required fields)
#### Variables not bound correctly
* Ensure variable keys match the placeholders used in prompts/flows
* Rebind variables in the editor if needed
***
