# 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
***
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.workfx.ai/workfx-1.1.x-english/workforce-factory/configuration-management/dsl.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.